theus-cli 0.2.82 → 0.2.84

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

@@ -1,719 +0,0 @@
----
-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.