theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/skills/testing-go/SKILL.md

@@ -0,0 +1,719 @@
+---
+name: testing-go
+description: Patrones de testing en Go, incluyendo tests dirigidos por tablas, subtests, benchmarks, fuzzing y cobertura de tests. Sigue la metodología TDD con prácticas idiomáticas de Go.
+---
+
+# Patrones de testing en Go
+
+Patrones completos de testing en Go para escribir tests fiables y mantenibles siguiendo la metodología TDD.
+
+## Cuándo activar esta skill
+
+- Al escribir nuevas funciones o métodos en Go
+- Al añadir cobertura de tests a código existente
+- Al crear benchmarks para código crítico en rendimiento
+- Al implementar tests de fuzzing para validación de entradas
+- Al seguir el flujo TDD en proyectos Go
+
+## Flujo TDD para Go
+
+### El ciclo RED-GREEN-REFACTOR
+
+```
+RED      → Escribe primero un test que falle
+GREEN    → Escribe el código mínimo para que el test pase
+REFACTOR → Mejora el código manteniendo los tests en verde
+REPETIR  → Continúa con el siguiente requisito
+```
+
+### TDD paso a paso en Go
+
+```go
+// Paso 1: definir la interfaz/firma
+// calculator.go
+package calculator
+
+func Add(a, b int) int {
+    panic("not implemented") // Marcador temporal
+}
+
+// Paso 2: escribir el test que falla (RED)
+// calculator_test.go
+package calculator
+
+import "testing"
+
+func TestAdd(t *testing.T) {
+    got := Add(2, 3)
+    want := 5
+    if got != want {
+        t.Errorf("Add(2, 3) = %d; want %d", got, want)
+    }
+}
+
+// Paso 3: ejecutar el test - verificar que FALLA
+// $ go test
+// --- FAIL: TestAdd (0.00s)
+// panic: not implemented
+
+// Paso 4: implementar el código mínimo (GREEN)
+func Add(a, b int) int {
+    return a + b
+}
+
+// Paso 5: ejecutar el test - verificar que PASA
+// $ go test
+// PASS
+
+// Paso 6: refactorizar si hace falta, verificando que los tests siguen pasando
+```
+
+## Tests dirigidos por tablas
+
+El patrón estándar de los tests en Go. Permite una cobertura exhaustiva con un mínimo de código.
+
+```go
+func TestAdd(t *testing.T) {
+    tests := []struct {
+        name     string
+        a, b     int
+        expected int
+    }{
+        {"números positivos", 2, 3, 5},
+        {"números negativos", -1, -2, -3},
+        {"valores cero", 0, 0, 0},
+        {"signos mezclados", -1, 1, 0},
+        {"números grandes", 1000000, 2000000, 3000000},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            got := Add(tt.a, tt.b)
+            if got != tt.expected {
+                t.Errorf("Add(%d, %d) = %d; want %d",
+                    tt.a, tt.b, got, tt.expected)
+            }
+        })
+    }
+}
+```
+
+### Tests dirigidos por tablas con casos de error
+
+```go
+func TestParseConfig(t *testing.T) {
+    tests := []struct {
+        name    string
+        input   string
+        want    *Config
+        wantErr bool
+    }{
+        {
+            name:  "config válida",
+            input: `{"host": "localhost", "port": 8080}`,
+            want:  &Config{Host: "localhost", Port: 8080},
+        },
+        {
+            name:    "JSON inválido",
+            input:   `{invalid}`,
+            wantErr: true,
+        },
+        {
+            name:    "entrada vacía",
+            input:   "",
+            wantErr: true,
+        },
+        {
+            name:  "config mínima",
+            input: `{}`,
+            want:  &Config{}, // Config con valor cero
+        },
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            got, err := ParseConfig(tt.input)
+
+            if tt.wantErr {
+                if err == nil {
+                    t.Error("se esperaba un error, se obtuvo nil")
+                }
+                return
+            }
+
+            if err != nil {
+                t.Fatalf("error inesperado: %v", err)
+            }
+
+            if !reflect.DeepEqual(got, tt.want) {
+                t.Errorf("got %+v; want %+v", got, tt.want)
+            }
+        })
+    }
+}
+```
+
+## Subtests y sub-benchmarks
+
+### Organizar tests relacionados
+
+```go
+func TestUser(t *testing.T) {
+    // Setup compartido por todos los subtests
+    db := setupTestDB(t)
+
+    t.Run("Create", func(t *testing.T) {
+        user := &User{Name: "Alice"}
+        err := db.CreateUser(user)
+        if err != nil {
+            t.Fatalf("CreateUser falló: %v", err)
+        }
+        if user.ID == "" {
+            t.Error("se esperaba que el ID del usuario estuviera asignado")
+        }
+    })
+
+    t.Run("Get", func(t *testing.T) {
+        user, err := db.GetUser("alice-id")
+        if err != nil {
+            t.Fatalf("GetUser falló: %v", err)
+        }
+        if user.Name != "Alice" {
+            t.Errorf("got name %q; want %q", user.Name, "Alice")
+        }
+    })
+
+    t.Run("Update", func(t *testing.T) {
+        // ...
+    })
+
+    t.Run("Delete", func(t *testing.T) {
+        // ...
+    })
+}
+```
+
+### Subtests en paralelo
+
+```go
+func TestParallel(t *testing.T) {
+    tests := []struct {
+        name  string
+        input string
+    }{
+        {"case1", "input1"},
+        {"case2", "input2"},
+        {"case3", "input3"},
+    }
+
+    for _, tt := range tests {
+        tt := tt // Capturar la variable del range
+        t.Run(tt.name, func(t *testing.T) {
+            t.Parallel() // Ejecutar los subtests en paralelo
+            result := Process(tt.input)
+            // aserciones...
+            _ = result
+        })
+    }
+}
+```
+
+## Helpers de test
+
+### Funciones helper
+
+```go
+func setupTestDB(t *testing.T) *sql.DB {
+    t.Helper() // Marca esta función como helper
+
+    db, err := sql.Open("sqlite3", ":memory:")
+    if err != nil {
+        t.Fatalf("no se pudo abrir la base de datos: %v", err)
+    }
+
+    // Limpieza cuando el test termina
+    t.Cleanup(func() {
+        db.Close()
+    })
+
+    // Ejecutar las migraciones
+    if _, err := db.Exec(schema); err != nil {
+        t.Fatalf("no se pudo crear el esquema: %v", err)
+    }
+
+    return db
+}
+
+func assertNoError(t *testing.T, err error) {
+    t.Helper()
+    if err != nil {
+        t.Fatalf("error inesperado: %v", err)
+    }
+}
+
+func assertEqual[T comparable](t *testing.T, got, want T) {
+    t.Helper()
+    if got != want {
+        t.Errorf("got %v; want %v", got, want)
+    }
+}
+```
+
+### Archivos y directorios temporales
+
+```go
+func TestFileProcessing(t *testing.T) {
+    // Crear un directorio temporal - se limpia automáticamente
+    tmpDir := t.TempDir()
+
+    // Crear el archivo de prueba
+    testFile := filepath.Join(tmpDir, "test.txt")
+    err := os.WriteFile(testFile, []byte("test content"), 0644)
+    if err != nil {
+        t.Fatalf("no se pudo crear el archivo de prueba: %v", err)
+    }
+
+    // Ejecutar el test
+    result, err := ProcessFile(testFile)
+    if err != nil {
+        t.Fatalf("ProcessFile falló: %v", err)
+    }
+
+    // Aserciones...
+    _ = result
+}
+```
+
+## Archivos golden
+
+Testear contra archivos de salida esperada almacenados en `testdata/`.
+
+```go
+var update = flag.Bool("update", false, "update golden files")
+
+func TestRender(t *testing.T) {
+    tests := []struct {
+        name  string
+        input Template
+    }{
+        {"simple", Template{Name: "test"}},
+        {"complex", Template{Name: "test", Items: []string{"a", "b"}}},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            got := Render(tt.input)
+
+            golden := filepath.Join("testdata", tt.name+".golden")
+
+            if *update {
+                // Actualizar el archivo golden: go test -update
+                err := os.WriteFile(golden, got, 0644)
+                if err != nil {
+                    t.Fatalf("no se pudo actualizar el archivo golden: %v", err)
+                }
+            }
+
+            want, err := os.ReadFile(golden)
+            if err != nil {
+                t.Fatalf("no se pudo leer el archivo golden: %v", err)
+            }
+
+            if !bytes.Equal(got, want) {
+                t.Errorf("la salida no coincide:\ngot:\n%s\nwant:\n%s", got, want)
+            }
+        })
+    }
+}
+```
+
+## Mocking con interfaces
+
+### Mocking basado en interfaces
+
+```go
+// Definir la interface para las dependencias
+type UserRepository interface {
+    GetUser(id string) (*User, error)
+    SaveUser(user *User) error
+}
+
+// Implementación de producción
+type PostgresUserRepository struct {
+    db *sql.DB
+}
+
+func (r *PostgresUserRepository) GetUser(id string) (*User, error) {
+    // Consulta real a la base de datos
+}
+
+// Implementación mock para los tests
+type MockUserRepository struct {
+    GetUserFunc  func(id string) (*User, error)
+    SaveUserFunc func(user *User) error
+}
+
+func (m *MockUserRepository) GetUser(id string) (*User, error) {
+    return m.GetUserFunc(id)
+}
+
+func (m *MockUserRepository) SaveUser(user *User) error {
+    return m.SaveUserFunc(user)
+}
+
+// Test usando el mock
+func TestUserService(t *testing.T) {
+    mock := &MockUserRepository{
+        GetUserFunc: func(id string) (*User, error) {
+            if id == "123" {
+                return &User{ID: "123", Name: "Alice"}, nil
+            }
+            return nil, ErrNotFound
+        },
+    }
+
+    service := NewUserService(mock)
+
+    user, err := service.GetUserProfile("123")
+    if err != nil {
+        t.Fatalf("error inesperado: %v", err)
+    }
+    if user.Name != "Alice" {
+        t.Errorf("got name %q; want %q", user.Name, "Alice")
+    }
+}
+```
+
+## Benchmarks
+
+### Benchmarks básicos
+
+```go
+func BenchmarkProcess(b *testing.B) {
+    data := generateTestData(1000)
+    b.ResetTimer() // No contar el tiempo de setup
+
+    for i := 0; i < b.N; i++ {
+        Process(data)
+    }
+}
+
+// Ejecutar: go test -bench=BenchmarkProcess -benchmem
+// Salida: BenchmarkProcess-8   10000   105234 ns/op   4096 B/op   10 allocs/op
+```
+
+### Benchmark con distintos tamaños
+
+```go
+func BenchmarkSort(b *testing.B) {
+    sizes := []int{100, 1000, 10000, 100000}
+
+    for _, size := range sizes {
+        b.Run(fmt.Sprintf("size=%d", size), func(b *testing.B) {
+            data := generateRandomSlice(size)
+            b.ResetTimer()
+
+            for i := 0; i < b.N; i++ {
+                // Hacer una copia para evitar ordenar datos ya ordenados
+                tmp := make([]int, len(data))
+                copy(tmp, data)
+                sort.Ints(tmp)
+            }
+        })
+    }
+}
+```
+
+### Benchmarks de asignación de memoria
+
+```go
+func BenchmarkStringConcat(b *testing.B) {
+    parts := []string{"hello", "world", "foo", "bar", "baz"}
+
+    b.Run("plus", func(b *testing.B) {
+        for i := 0; i < b.N; i++ {
+            var s string
+            for _, p := range parts {
+                s += p
+            }
+            _ = s
+        }
+    })
+
+    b.Run("builder", func(b *testing.B) {
+        for i := 0; i < b.N; i++ {
+            var sb strings.Builder
+            for _, p := range parts {
+                sb.WriteString(p)
+            }
+            _ = sb.String()
+        }
+    })
+
+    b.Run("join", func(b *testing.B) {
+        for i := 0; i < b.N; i++ {
+            _ = strings.Join(parts, "")
+        }
+    })
+}
+```
+
+## Fuzzing (Go 1.18+)
+
+### Test de fuzzing básico
+
+```go
+func FuzzParseJSON(f *testing.F) {
+    // Añadir el corpus semilla
+    f.Add(`{"name": "test"}`)
+    f.Add(`{"count": 123}`)
+    f.Add(`[]`)
+    f.Add(`""`)
+
+    f.Fuzz(func(t *testing.T, input string) {
+        var result map[string]interface{}
+        err := json.Unmarshal([]byte(input), &result)
+
+        if err != nil {
+            // Un JSON inválido es esperable con entradas aleatorias
+            return
+        }
+
+        // Si el parseo tuvo éxito, la re-codificación debería funcionar
+        _, err = json.Marshal(result)
+        if err != nil {
+            t.Errorf("Marshal falló tras un Unmarshal exitoso: %v", err)
+        }
+    })
+}
+
+// Ejecutar: go test -fuzz=FuzzParseJSON -fuzztime=30s
+```
+
+### Test de fuzzing con múltiples entradas
+
+```go
+func FuzzCompare(f *testing.F) {
+    f.Add("hello", "world")
+    f.Add("", "")
+    f.Add("abc", "abc")
+
+    f.Fuzz(func(t *testing.T, a, b string) {
+        result := Compare(a, b)
+
+        // Propiedad: Compare(a, a) siempre debe ser 0
+        if a == b && result != 0 {
+            t.Errorf("Compare(%q, %q) = %d; want 0", a, b, result)
+        }
+
+        // Propiedad: Compare(a, b) y Compare(b, a) deben tener signos opuestos
+        reverse := Compare(b, a)
+        if (result > 0 && reverse >= 0) || (result < 0 && reverse <= 0) {
+            if result != 0 || reverse != 0 {
+                t.Errorf("Compare(%q, %q) = %d, Compare(%q, %q) = %d; inconsistente",
+                    a, b, result, b, a, reverse)
+            }
+        }
+    })
+}
+```
+
+## Cobertura de tests
+
+### Ejecutar la cobertura
+
+```bash
+# Cobertura básica
+go test -cover ./...
+
+# Generar el perfil de cobertura
+go test -coverprofile=coverage.out ./...
+
+# Ver la cobertura en el navegador
+go tool cover -html=coverage.out
+
+# Ver la cobertura por función
+go tool cover -func=coverage.out
+
+# Cobertura con detección de condiciones de carrera
+go test -race -coverprofile=coverage.out ./...
+```
+
+### Objetivos de cobertura
+
+| Tipo de código | Objetivo |
+|----------------|----------|
+| Lógica de negocio crítica | 100% |
+| APIs públicas | 90%+ |
+| Código general | 80%+ |
+| Código generado | Excluir |
+
+### Excluir código generado de la cobertura
+
+```go
+//go:generate mockgen -source=interface.go -destination=mock_interface.go
+
+// En el perfil de cobertura, excluir con build tags:
+// go test -cover -tags=!generate ./...
+```
+
+## Testing de handlers HTTP
+
+```go
+func TestHealthHandler(t *testing.T) {
+    // Crear la petición
+    req := httptest.NewRequest(http.MethodGet, "/health", nil)
+    w := httptest.NewRecorder()
+
+    // Llamar al handler
+    HealthHandler(w, req)
+
+    // Verificar la respuesta
+    resp := w.Result()
+    defer resp.Body.Close()
+
+    if resp.StatusCode != http.StatusOK {
+        t.Errorf("got status %d; want %d", resp.StatusCode, http.StatusOK)
+    }
+
+    body, _ := io.ReadAll(resp.Body)
+    if string(body) != "OK" {
+        t.Errorf("got body %q; want %q", body, "OK")
+    }
+}
+
+func TestAPIHandler(t *testing.T) {
+    tests := []struct {
+        name       string
+        method     string
+        path       string
+        body       string
+        wantStatus int
+        wantBody   string
+    }{
+        {
+            name:       "obtener usuario",
+            method:     http.MethodGet,
+            path:       "/users/123",
+            wantStatus: http.StatusOK,
+            wantBody:   `{"id":"123","name":"Alice"}`,
+        },
+        {
+            name:       "no encontrado",
+            method:     http.MethodGet,
+            path:       "/users/999",
+            wantStatus: http.StatusNotFound,
+        },
+        {
+            name:       "crear usuario",
+            method:     http.MethodPost,
+            path:       "/users",
+            body:       `{"name":"Bob"}`,
+            wantStatus: http.StatusCreated,
+        },
+    }
+
+    handler := NewAPIHandler()
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            var body io.Reader
+            if tt.body != "" {
+                body = strings.NewReader(tt.body)
+            }
+
+            req := httptest.NewRequest(tt.method, tt.path, body)
+            req.Header.Set("Content-Type", "application/json")
+            w := httptest.NewRecorder()
+
+            handler.ServeHTTP(w, req)
+
+            if w.Code != tt.wantStatus {
+                t.Errorf("got status %d; want %d", w.Code, tt.wantStatus)
+            }
+
+            if tt.wantBody != "" && w.Body.String() != tt.wantBody {
+                t.Errorf("got body %q; want %q", w.Body.String(), tt.wantBody)
+            }
+        })
+    }
+}
+```
+
+## Comandos de testing
+
+```bash
+# Ejecutar todos los tests
+go test ./...
+
+# Ejecutar los tests con salida detallada
+go test -v ./...
+
+# Ejecutar un test específico
+go test -run TestAdd ./...
+
+# Ejecutar los tests que coincidan con un patrón
+go test -run "TestUser/Create" ./...
+
+# Ejecutar los tests con detector de condiciones de carrera
+go test -race ./...
+
+# Ejecutar los tests con cobertura
+go test -cover -coverprofile=coverage.out ./...
+
+# Ejecutar solo los tests cortos
+go test -short ./...
+
+# Ejecutar los tests con timeout
+go test -timeout 30s ./...
+
+# Ejecutar los benchmarks
+go test -bench=. -benchmem ./...
+
+# Ejecutar el fuzzing
+go test -fuzz=FuzzParse -fuzztime=30s ./...
+
+# Repetir las ejecuciones (para detectar tests inestables)
+go test -count=10 ./...
+```
+
+## Buenas prácticas
+
+**SÍ:**
+- Escribe los tests PRIMERO (TDD)
+- Usa tests dirigidos por tablas para una cobertura exhaustiva
+- Testea el comportamiento, no la implementación
+- Usa `t.Helper()` en las funciones helper
+- Usa `t.Parallel()` en los tests independientes
+- Limpia los recursos con `t.Cleanup()`
+- Usa nombres de test significativos que describan el escenario
+
+**NO:**
+- Testear funciones privadas directamente (testea a través de la API pública)
+- Usar `time.Sleep()` en los tests (usa canales o condiciones)
+- Ignorar los tests inestables (corrígelos o elimínalos)
+- Mockear todo (prefiere tests de integración cuando sea posible)
+- Omitir el testing de los caminos de error
+
+## Integración con CI/CD
+
+```yaml
+# Ejemplo con GitHub Actions
+test:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-go@v5
+      with:
+        go-version: '1.22'
+
+    - name: Run tests
+      run: go test -race -coverprofile=coverage.out ./...
+
+    - name: Check coverage
+      run: |
+        go tool cover -func=coverage.out | grep total | awk '{print $3}' | \
+        awk -F'%' '{if ($1 < 80) exit 1}'
+```
+
+**Recuerda**: los tests son documentación. Muestran cómo se debe usar tu código. Escríbelos con claridad y mantenlos actualizados.