Mejores Prácticas de Pruebas

Guía de la pirámide de pruebas para servicios y bibliotecas de Go.

Estas reglas mantienen las pruebas de Go rápidas, legibles y confiables, desde go test local hasta las puertas de fusión de CI.

Cómo Usar Esta Lista

• Aplica durante el diseño y la revisión cuando las pruebas son una ocurrencia tardía o el tiempo de CI explota.
• Ejecuta go test -race ./... y golangci-lint en los mismos paquetes que controlas en CI.
• Prefiere añadir una fila a la tabla en lugar de una función de prueba única cuando el comportamiento está parametrizado.
• Revisa los corpora de fuzzing y los archivos dorados siempre que el formato de salida cambie intencionalmente.

A - Estructura y legibilidad

• Por defecto, usa pruebas basadas en tablas con subpruebas nombradas. Los revisores ven los casos como datos; los fallos nombran la fila a través de t.Run.
• Mantén las pruebas junto al código de producción en *_test.go. Mismo módulo, misma refactorización, mismos errores de compilación cuando las APIs se mueven.
• Usa t.Helper() en ayudantes de aserción compartidos. Los fallos apuntan a la línea de prueba, no a los internos de la utilidad.
• Prueba el comportamiento exportado desde package foo_test al modelar consumidores. Las pruebas internas permanecen en package foo para ayudantes no exportados.
• Una ruta de aserción lógica por subprueba cuando sea posible. Las comprobaciones mixtas dificultan el diagnóstico de los fallos.

B - Velocidad y determinismo

• Apunta a go test ./... en segundos a pocos minutos en portátiles. Divide las suites de integración con etiquetas de compilación o módulos separados cuando sea necesario.
• Evita time.Sleep para la sincronización. Usa canales, sync.WaitGroup o manejadores httptest controlables.
• Simula los límites de IO, no cada función privada. Falsos manuales detrás de interfaces pequeñas superan a los mocks generados para APIs estrechas.
• Ejecuta go test -count=1 al depurar fallos. Los pases cacheados ocultan errores de ordenación hasta que la CI se vuelve a ejecutar.
• Saca la configuración de benchmark fuera de b.Loop(). Mide la ruta activa, no la construcción de fixtures.

C - HTTP, bases de datos y servicios

• Usa httptest.NewRecorder para pruebas unitarias de manejadores. Reserva NewServer cuando la pila del cliente deba ejecutarse de verdad.
• Cierra resp.Body después de cada llamada al cliente en las pruebas. Las fugas fallan con -count=100 y cargas similares en CI.
• Limita las pruebas de bases de datos reales a una fina capa de humo. Mantén las pruebas de lógica de negocio en falsos; usa contenedores para la integración SQL con moderación.
• Pasa r.Context() a través de los manejadores en las pruebas. La cancelación y los middleware de plazos solo funcionan cuando los manejadores respetan el contexto.
• Documenta qué pruebas requieren Docker o red. Marca con etiquetas de compilación para que go test por defecto permanezca sin conexión.

D - Señales de calidad de CI

• Ejecuta -race en paquetes que generan goroutines o comparten cachés. Acepta el coste de CPU en los agentes de CI de Linux.
• Rastrea la cobertura en paquetes críticos, no en porcentajes globales vanidosos. Empareja la cobertura con aserciones en ramas de error.
• Confirma los crashers de fuzzing y los archivos dorados bajo testdata/. Trata las diferencias como fixtures de regresión que requieren revisión humana.
• Programa trabajos de fuzzing limitados (-fuzztime) por la noche o semanalmente. Reproduce corpora en cada PR sin fuzzing de duración abierta en los pipelines de fusión.
• Ordena la CI: formato/vet/lint, pruebas unitarias, compilación de race, humo de integración. Alinea con las plantillas de puerta de calidad de linting.

E - Documentación y evolución

• Añade funciones Example para copiar y pegar el uso de la API pública. Mantén los comentarios // Output: precisos para que godoc se mantenga verificado.
• Actualiza los ejemplos cuando cambie el comportamiento exportado. go test falla cuando la documentación se desvía.
• Prefiere errors.Is / errors.As en las filas de la tabla de errores. Los errores envueltos rompen las comparaciones ==.
• Revisa la política de require vs assert de testify por equipo. require para precondiciones; assert para comprobaciones independientes.
• Haz profiling antes de micro-optimizar basándote solo en benchmarks. Usa pprof en cargas de trabajo realistas después de que benchstat muestre una ganancia.

Preguntas Frecuentes

Relacionados

• Cultura de Pruebas en Go: Simple, Rápida, Basada en Tablas - resumen de la sección
• Conceptos Básicos de Pruebas en Go - ejemplos ejecutables introductorios
• Cobertura, Detector de Race y Archivos Dorados - señales de CI en profundidad
• Pruebas de Fuzzing con testing.F - corpora y fuzzing programado
• Puertas de Calidad de CI: Lint, Test, Race, Vuln - ordenación completa del pipeline

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de Green Tea GC, go fix modernizers - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica los objetivos de la placa en la compilación), wazero (última versión - verifica en la compilación) y golangci-lint (última versión - verifica el conjunto de linters en la compilación).