¿Qué primitivo de sincronización dentro del paquete de pruebas de **Go** rige los límites de la bandera `-parallel` para las jerarquías de subpruebas?

Respuesta a la pregunta.

Historia

El marco de pruebas de Go introdujo t.Parallel() para abordar la creciente duración de los pipelines de CI en grandes bases de código. Antes de la adopción generalizada de procesadores multinúcleo, las pruebas se ejecutaban secuencialmente por defecto. A medida que los proyectos se ampliaban a miles de pruebas, la ejecución puramente secuencial se convirtió en un cuello de botella, sin embargo, el paralelismo ilimitado arriesgaba agotar recursos del proceso como descriptores de archivo o conexiones de base de datos. El objetivo del diseño era proporcionar un modelo de concurrencia integrado y optativo que respetara un límite global sin requerir que los desarrolladores orquestaran manualmente grupos de trabajo o sincronización compleja para cada conjunto de pruebas.

Problema

Cuando un desarrollador llama a t.Parallel(), la prueba debe señalar al ejecutor que puede ejecutarse concurrentemente con otras pruebas. Sin embargo, el marco debe imponer un límite estricto de concurrencia (que por defecto es GOMAXPROCS pero configurable a través de la bandera -parallel) para prevenir la inanición de recursos. El desafío se intensifica con las subpruebas anidadas: una prueba padre podría invocar t.Run múltiples veces, y cada subprueba podría llamar independientemente a t.Parallel(). La solución debe evitar que el padre libere su espacio de ejecución antes de que todos sus descendientes terminen, mientras se asegura de que las subpruebas paralelas profundamente anidadas adquieran correctamente espacios del mismo grupo global sin bloquear al padre o exceder el límite.

Solución

El paquete testing utiliza un semáforo implementado como un canal con búfer de estructuras vacías (chan struct{}) dimensionado al valor de la bandera -parallel. Este canal se comparte entre todas las pruebas en un paquete. Cada instancia de T mantiene una referencia a este canal parallel y un canal de signal interno para coordinase con su padre.

Cuando se invoca `t.Parallel() mira:

1. Cierra el canal de signal, desbloqueando la llamada t.Run del padre para que el padre pueda continuar o terminar mientras la subprueba se ejecuta concurrentemente.
2. Bloquea la goroutine actual enviando al canal semáforo parallel, adquiriendo un espacio de ejecución.
3. Una función diferida en el ejecutor de pruebas libera el espacio recibiendo del canal parallel una vez que la función de prueba retorna y se ejecutan todos los ganchos de t.Cleanup.

Para jerarquías, t.Run bloquea la goroutine padre utilizando un sync.WaitGroup hasta que la subprueba se completa completamente, incluso si la subprueba se ejecuta en paralelo. Esto asegura que el padre mantenga su espacio (o espere) hasta que todo el árbol de subpruebas termine, evitando que se exceda el límite global por un estallido de pruebas paralelas profundamente anidadas.

// Modelo conceptual de las internals del paquete de pruebas
type T struct {
    parallel chan struct{} // Semáforo compartido
    signal   chan struct{} // Señaliza al padre que se llamó a Parallel()
    parent   *T
    wg       sync.WaitGroup // Espera por subpruebas
}

func (t *T) Parallel() {
    // Libera al padre para continuar
    close(t.signal)
    // Adquiere espacio del grupo global
    t.parallel <- struct{}{}
    // Cleanup libera el espacio cuando la prueba termina
    t.Cleanup(func() { <-t.parallel })
}

func (t *T) Run(name string, f func(t *T)) bool {
    t.wg.Add(1)
    sub := &T{parallel: t.parallel, signal: make(chan struct{})}
    go func() {
        defer t.wg.Done()
        f(sub)
    }()
    <-sub.signal // Espera a que la subprueba comience o llame a Parallel
    t.wg.Wait()  // Espera a la finalización
    return !sub.Failed()
}

Situación de la vida real

Contexto

Un equipo de plataforma mantenía un monorepo que contenía 2,000 pruebas de integración para una arquitectura de microservicios. Cada prueba levantaba contenedores Docker efímeros para Postgres y Redis. Ejecutar pruebas secuencialmente requería 45 minutos, lo que hacía imposible recibir retroalimentación rápida. Sin embargo, al ejecutar go test -parallel 100, los ejecutores de CI agotaban el límite de max_user_namespaces del núcleo, causando que el host se bloqueara y corrompiera la caché de compilación.

Problema

El equipo necesitaba limitar las pruebas que consumían contenedores a cinco instancias concurrentes para respetar los límites del núcleo, mientras permitía que las pruebas unitarias puras se ejecutaran con -parallel 32 para un máximo rendimiento. El paquete de pruebas estándar de Go solo acepta un único valor global de -parallel por invocación, ofreciendo ninguna manera incorporada de aplicar diferentes límites a diferentes categorías de pruebas dentro de la misma ejecución.

Soluciones consideradas

Orquestación externa con Bazel. Se propuso migrar a Bazel porque soporta cortado de pruebas y etiquetado de recursos (por ejemplo, tags = ["resources:postgres:1"]). Esto permitiría al programador limitar las pruebas de base de datos concurrentes de manera precisa. Sin embargo, esto requería reescribir todo el sistema de compilación y perder la simplicidad de go test. La curva de aprendizaje era empinada, y los flujos de trabajo de desarrollo local cambiarían drásticamente, ralentizando a los desarrolladores que no estaban familiarizados con el lenguaje de consulta de Bazel.

Semáforo manual dentro de las suites de prueba. Los desarrolladores consideraron agregar un var dbSem = make(chan struct{}, 5) a nivel de paquete y hacer que cada prueba de integración lo adquiriera manualmente al inicio. Esto proporcionó control detallado pero introdujo un importante boilerplate y riesgo de bloqueo si una prueba fallaba mientras sostenía el semáforo. También fragmentó el modelo de concurrencia—algunas pruebas respetaban la bandera -parallel, otras respetaban el semáforo personalizado—lo que dificultaba la depuración y conducía a una contabilidad inconsistente de recursos.

Separación de etiquetas de compilación con etapas de CI. El equipo optó por segregar las pruebas utilizando etiquetas de compilación. Agregaron //go:build integration a todas las pruebas contenidas en contenedores y dejaron las pruebas unitarias sin marcar. La pipeline de CI primero ejecutó go test -short -parallel 32 ./... para pruebas unitarias, luego ejecutó por separado go test -tags=integration -parallel 5 ./.... Esto aprovechó las características existentes de la herramienta estándar de Go sin modificar la lógica de prueba. La desventaja fue perder el paralelismo interpaquete entre pruebas unitarias e integración; las etapas se ejecutaron secuencialmente. Sin embargo, dado que las pruebas unitarias se completaron en tres minutos, el tiempo total (3m + 20m) fue aceptable y estable.

Solución y resultado elegidos

Eligieron la separación por etiquetas de compilación. Requirió cambios mínimos de código—solo añadiendo etiquetas a los encabezados de archivos—y utilizó el semáforo del paquete estándar testing de manera natural sin sincronización personalizada. La CI se volvió estable, los límites del núcleo fueron respetados, y los desarrolladores pudieron seguir ejecutando go test -tags=integration -parallel 4 localmente para depuración. El tiempo total de CI se redujo de 45 minutos a 23 minutos, y los bloqueos del host cesaron por completo.

Qué suelen pasar por alto los candidatos

¿Por qué llamar a t.Parallel() después de crear una goroutine a veces resulta en que esa goroutine registre en la salida de la prueba incorrecta o falle?

Cuando se invoca t.Parallel(), la goroutine de prueba actual se bloquea en el semáforo, y el ejecutor de prueba padre continúa con la siguiente prueba. La goroutine creada, sin embargo, hereda la instancia de T. Si la función de prueba principal retorna mientras la goroutine aún está en ejecución, el paquete de pruebas marca al T como terminado y cierra sus búferes de salida. Las llamadas subsecuentes a t.Log o t.Error desde la goroutine huérfana pueden generar un pánico con "Log en goroutine después de que TestX haya completado". El enfoque correcto es sincronizar la finalización de la goroutine usando sync.WaitGroup o garantizar que t.Cleanup espere por ella, porque t.Parallel() no espera automáticamente a las goroutines separadas; solo coordina el ciclo de vida de la función de prueba con el ejecutor.

¿Cómo evita el paquete de pruebas que una prueba padre libere su espacio de paralelismo antes de que todas sus subpruebas—algunas de las cuales también pueden llamar a t.Parallel()—hayan terminado de ejecutarse?

La estructura T incorpora un sync.WaitGroup. Cuando se llama a t.Run para crear una subprueba, el padre llama a t.wg.Add(1) antes de lanzar la goroutine de la subprueba, y la subprueba llama a t.wg.Done() en una función diferida al completarse. De manera crucial, cuando una subprueba llama a t.Parallel(), decremente inmediatamente el WaitGroup del padre (permitiendo que el padre termine potencialmente su propio cuerpo de función), pero la finalización global de la prueba del padre—y por lo tanto la liberación de su token semáforo—es bloqueada por un t.wg.Wait() final en la cadena de limpieza. Esto crea una espera estructurada en árbol donde la prueba paralela raíz mantiene el espacio hasta que todo el subárbol de subpruebas seriales y paralelas concluye, asegurando que el límite -parallel refleje con precisión el número de árboles de prueba activos, no solo goroutines activas.

¿Por qué podría t.Setenv generar un pánico si se llama después de t.Parallel(), y qué revela esto sobre el modelo de aislamiento de pruebas paralelas en Go?

t.Setenv genera un pánico cuando se llama después de t.Parallel() porque las variables de entorno son estado global de proceso. Las pruebas paralelas se ejecutan concurrentemente en el mismo proceso; si una prueba modificó PATH mientras otra lo leía, el resultado sería una carrera de datos y un comportamiento no determinista. Para prevenir esto, el paquete de pruebas de Go marca el entorno como "congelado" una vez que una prueba se vuelve paralela, y cualquier intento de mutarlo mediante t.Setenv o os.Setenv activa un pánico. Esto revela que las pruebas paralelas están diseñadas para la concurrencia dentro de un solo espacio de direcciones, pero suponen un estado compartido inmutable o sincronización explícita. Los candidatos a menudo pasan por alto que t.Parallel() implica un estricto contrato de "sin mutación del estado global del proceso", lo que requiere el uso de t.Cleanup para restaurar el estado solo si la prueba no fue paralela, o diseñar pruebas para evitar el estado global por completo.