go test, list y generate

go test ejecuta pruebas de paquetes, go list introspecciona lo que ve el sistema de compilación y go generate activa hooks de generación de código que defines junto a los archivos fuente.

Resumen

Las pruebas son de primera clase en la toolchain: no se requiere un runner externo para pruebas unitarias, benchmarks, ejemplos o targets de fuzzing.

go list expone paquetes, dependencias, tags y versiones de módulos como JSON legible por máquina para scripts y CI.

go generate ejecuta directivas //go:generate, generalmente llamando a herramientas instaladas con go install.

Juntos forman el ciclo diario: listar lo que existe, generar lo que está obsoleto, probar lo que ha cambiado.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

# Ejecuta todas las pruebas con detector de race y cobertura
go test -race -cover ./...
 
# Ejecuta una prueba por nombre con salida detallada
go test -run TestParseConfig -v ./internal/config
 
# Lista los paquetes como JSON para scripting
go list -json ./...
 
# Ejecuta todos los generadores en el módulo
go generate ./...

Cuándo usar esto:

• Usa go test ./... como la puerta de enlace predeterminada de CI antes de fusionar.
• Usa plantillas de go list -f para generar informes de SBOM o de propiedad.
• Usa go generate después de cambiar definiciones de protobuf, stringer o mock.
• Usa go test -bench al optimizar rutas críticas con números reproducibles.

Ejemplo de Trabajo

// mathutil/sum.go
package mathutil
 
func Sum(nums []int) int {
    total := 0
    for _, n := range nums {
        total += n
    }
    return total
}

// mathutil/sum_test.go
package mathutil
 
import "testing"
 
func TestSum(t *testing.T) {
    got := Sum([]int{1, 2, 3})
    if got != 6 {
        t.Fatalf("got %d want 6", got)
    }
}
 
func BenchmarkSum(b *testing.B) {
    data := make([]int, 1000)
    for i := range data {
        data[i] = i
    }
    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        Sum(data)
    }
}

// api/doc.go
package api
 
//go:generate go run golang.org/x/tools/cmd/stringer@latest -type=Kind
 
type Kind int
 
const (
    KindHTTP Kind = iota
    KindGRPC
)

go test -cover ./mathutil
go test -bench=. -benchmem ./mathutil
go list -f '{{.ImportPath}} tags={{.BuildTags}}' ./...
go generate ./api

Lo que esto demuestra:

• Prueba unitaria sin tabla con t.Fatalf para fallos rápidos.
• Benchmark con b.ResetTimer() excluyendo el trabajo de configuración.
• go list -f plantilla personalizada para scripts de inventario.
• //go:generate ubicado junto al tipo que mantiene.

Análisis Profundo

Cómo Funciona

• go test compila un main de prueba que enlaza los archivos _test.go, luego ejecuta el binario y transmite los resultados.
• Las claves de caché de pruebas incluyen hashes de origen, flags y versión de Go; los resultados pasados se reutilizan a menos que se use -count=1.
• go list carga paquetes sin necesariamente enlazar; -json emite estructuras para automatización.
• go generate escanea las líneas //go:generate y ejecuta comandos en orden de archivo; no rastrea la obsolescencia por sí mismo.

Flags de go test de un Vistazo

Plantillas de go list

Reglas de go generate

• Las directivas deben comenzar con //go:generate (sin espacio antes de go).
• Los comandos se ejecutan con el directorio del paquete como directorio de trabajo.
• Los generadores deben ser idempotentes; confirma las salidas o aplica comprobaciones de git diff en CI.
• Prefiere go run tool@version sobre binarios locales no documentados para reproducibilidad.

Trampas Comunes

• Asumir que go test sin ./... ejecuta todo - . solo se refiere al paquete actual. Solución: go test ./... desde la raíz del módulo.
• Pasada inestable cacheada para siempre - la caché predeterminada oculta fallos intermitentes. Solución: go test -count=1 mientras depuras; soluciona la causa raíz antes de fusionar.
• Benchmarking sin -benchmem - las regresiones de asignación permanecen invisibles. Solución: añade -benchmem y compara con benchstat.
• go generate en CI sin comprobar diffs - la deriva se fusiona silenciosamente. Solución: ejecuta generate en un trabajo que falle si git diff no está vacío.
• Confusión de paquete de prueba externo - package foo_test no puede acceder a símbolos no exportados. Solución: prueba la API exportada o usa el paquete de prueba interno package foo.
• Análisis manual de JSON de List - fácil pasar por alto saltos de línea incrustados. Solución: usa jq en la salida de go list -json en scripts.

Alternativas

Preguntas Frecuentes

Relacionado

• The go Command: Build, Test, and Module Lifecycle - pipeline de carga compartido
• Go Toolchain Basics - primeros ejemplos de go test y go list
• go fix Modernizers & go vet Analyzers - comprobaciones estáticas antes de las pruebas
• Build Tags & Conditional Compilation - por qué la salida de list difiere según los tags
• Go Toolchain Best Practices - hábitos de prueba de CI

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