testing

What this skill does

<objective>
Principles and patterns for writing effective Go tests.
Writes tests autonomously based on code structure and type design, and serves as testing expert advisor.

**Reference**: See `reference.md` for comprehensive testutils patterns and DSL examples.
</objective>

<quick_start>
1. **Identify test level** needed (unit/integration/system)
2. **Choose structure**: table-driven (simple) or testify suites (complex setup)
3. **Write in pkg_test package** - test public API only
4. **Use in-memory implementations** from testutils
5. **Avoid pitfalls**: No time.Sleep, no conditionals in test cases

Ready after tests? Run linter: `task lintwithfix`
</quick_start>

<when_to_use>
<automatic_invocation>
- **Automatically invoked** by @linter-driven-development during Phase 1 (Implementation Foundation)
- **Automatically invoked** by @refactoring when new isolated types are created
- **Automatically invoked** by @code-designing after designing new types
- **After creating new leaf types** - Types that should have 100% unit test coverage
- **After extracting functions** during refactoring that create testable units
</automatic_invocation>

<manual_invocation>
- User explicitly requests tests to be written
- User asks for testing advice, recommendations, or "what to do"
- When testing strategy is unclear (table-driven vs testify suites)
- When choosing between dependency levels (in-memory vs binary vs test-containers)
- When adding tests to existing untested code
- When user needs testing expert guidance or consultation
</manual_invocation>
</when_to_use>

<philosophy>
**Test only the public API**
- Use `pkg_test` package name
- Test types through their constructors
- No testing private methods/functions

**Prefer real implementations over mocks**
- Use in-memory implementations (fastest, no external deps)
- Use HTTP test servers (httptest)
- Use temp files/directories
- Test with actual dependencies when beneficial

**Coverage targets**
- Leaf types: 100% unit test coverage
- Orchestrating types: Integration tests
- Critical workflows: System tests
</philosophy>

<test_pyramid>
Three levels of testing, each serving a specific purpose:

<unit_tests level="base">
- Test leaf types in isolation
- Fast, focused, no external dependencies
- 100% coverage target for leaf types
- Use `pkg_test` package, test public API only
</unit_tests>

<integration_tests level="middle">
- Test seams between components
- Test workflows across package boundaries
- Use real or in-memory implementations
- Verify components work together correctly
</integration_tests>

<system_tests level="top">
- Black box testing from `tests/` folder
- Test entire system via CLI/API
- Test critical end-to-end workflows
- **Dependency options**: in-memory mocks, binaries (exec.Command), or test-containers
- Prefer in-memory when possible, but use appropriate level for the test
</system_tests>
</test_pyramid>

<reusable_infrastructure>
Build shared test infrastructure in `internal/testutils/`:
- In-memory mock servers with DSL (HTTP, DB, file system)
- Reusable across all test levels
- Test the infrastructure itself!
- Can expose as CLI tools for manual testing

**Dependency Priority** (choose appropriate level):
1. **In-memory** (fastest): Pure Go, httptest, in-memory DB - use when testing your code's logic
2. **Binary** (isolated): Standalone executable via exec.Command - use when testing against real service
3. **Test-containers** (realistic): Programmatic Docker from Go - use when you need real external services
4. **Docker-compose** (full stack): For complex multi-service scenarios

Choose based on what you're testing, not dogmatically. In-memory is fastest but sometimes you need real services.

See reference.md for comprehensive testutils patterns and DSL examples.
</reusable_infrastructure>

<workflow>

<unit_tests_workflow>
**Purpose**: Test leaf types in isolation, 100% coverage target

1. **Identify leaf types** - Self-contained types with logic
2. **Choose structure** - Table-driven (simple) or testify suites (complex setup)
3. **Write in pkg_test package** - Test public API only
4. **Use in-memory implementations** - From testutils or local implementations
5. **Avoid pitfalls** - No time.Sleep, no conditionals in cases, no private method tests

**Test structure:**
- Table-driven: Separate success/error test functions (complexity = 1)
- Testify suites: Only for complex infrastructure setup (HTTP servers, DBs)
- Always use named struct fields (linter reorders fields)

See reference.md for detailed patterns and examples.
</unit_tests_workflow>

<integration_tests_workflow>
**Purpose**: Test seams between components, verify they work together

1. **Identify integration points** - Where packages/components interact
2. **Choose dependencies** - Prefer: in-memory > binary > test-containers
3. **Write tests** - In `pkg_test` or `integration_test.go` with build tags
4. **Test workflows** - Cover happy path and error scenarios across boundaries
5. **Use real or testutils implementations** - Avoid heavy mocking

**File organization:**
```go
//go:build integration

package user_test

// Test Service + Repository + real/mock dependencies
```

See reference.md for integration test patterns with dependencies.
</integration_tests_workflow>

<system_tests_workflow>
**Purpose**: Black box test entire system, critical end-to-end workflows

1. **Place in tests/ folder** - At project root, separate from packages
2. **Test via CLI/API** - exec.Command for CLI, HTTP client for APIs
3. **Choose dependency level** based on what you're testing:
   - **In-memory**: Fastest, use when testing your code's behavior
   - **Binary**: exec.Command to run real executables in separate process
   - **Test-containers**: When you need real external services (DB, message queue)
4. **Test critical workflows** - User journeys, not every edge case

**Example with in-memory mock:**
```go
// tests/cli_test.go - Testing CLI against mock API
func TestCLI_UserWorkflow(t *testing.T) {
    mockAPI := testutils.NewMockServer().
        OnGET("/users/1").RespondJSON(200, user).
        Build() // In-memory httptest.Server
    defer mockAPI.Close()

    cmd := exec.Command("./myapp", "get-user", "1",
        "--api-url", mockAPI.URL())
    output, err := cmd.CombinedOutput()
    // Assert on output
}
```

**Example with binary executable:**
```go
// tests/integration_test.go - Testing against real service binary
func TestSystem_WithRealService(t *testing.T) {
    // Start service binary in background
    svc := exec.Command("./myservice", "--port", "8080")
    svc.Start()
    defer svc.Process.Kill()

    // Wait for service to be ready
    waitForHealthy(t, "http://localhost:8080/health")

    // Run tests against real service
    resp, err := http.Get("http://localhost:8080/api/users")
    // Assert on response
}
```

See reference.md for comprehensive system test patterns including test-containers.
</system_tests_workflow>

</workflow>

<key_patterns>
**Table-Driven Tests (Cyclomatic Complexity = 1):**
- **NEVER use wantErr bool** - Splits test logic, adds conditionals
- **Max complexity = 1 inside t.Run()** - No if/else, no switch, no conditionals
- Separate success and error test functions (TestFoo_Success, TestFoo_Error)
- Always use named struct fields (linter reorders fields)

```go
// BAD - wantErr adds conditional, complexity > 1
tests := []struct {
    input   string
    want    string
    wantErr bool  // NEVER DO THIS
}{...}
for _, tt := range tests {
    t.Run(tt.name, func(t *testing.T) {
        got, err := Parse(tt.input)
        if tt.wantErr {  // <- Conditional! Complexity > 1
            require.Error(t, err)
        } else {
            require.NoError(t, err)
            require.Equal(t, tt.want, got)
        }
    })
}

// GOOD - Separate functions, complexity = 1
func TestParse_Success(t *testing.T) {
    tests := []struct {
        name  string
        input string
        want  string
    }{...}
    for _,