@grimoire-cc/cli 0.13.2 → 0.14.0

package/packs/go-pack/skills/grimoire.unit-testing-go/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: grimoire.unit-testing-go
+description: "Go unit testing specialist. Patterns and best practices for the testing stdlib, testify, and gomock. Use when writing tests for .go files, table-driven tests, or asking about Go testing patterns, test helpers, mocking interfaces, benchmarks."
+---
+
+# Go Unit Testing
+
+Focused guidance for writing clean, idiomatic unit tests in Go projects.
+
+## Framework Selection
+
+### Detection
+
+1. Check existing test files first — always match what the project uses
+2. Check `go.mod` for `testify`, `gomock`, `mockery` dependencies
+3. Check existing `*_test.go` files for assertion style
+
+### Decision Table
+
+| Condition | Use | Reason |
+|-----------|-----|--------|
+| Project has existing tests | **Match existing** | Consistency is paramount |
+| New project, standard needs | **testing** (stdlib) | Built-in, zero dependencies |
+| Need rich assertions + mocking | **testify** | `assert`, `require`, `mock` packages |
+| Strict interface mocking | **gomock** | Code generation, strict expectations |
+| User explicitly requests | **Requested** | Respect user preference |
+
+## Naming Conventions
+
+Use `TestMethod_Scenario_Expected` with PascalCase/underscores:
+
+```go
+// Pattern: TestMethod_Scenario_Expected
+func TestGetUser_WithInvalidID_ReturnsNotFound(t *testing.T) { ... }
+func TestCalculateTotal_WithDiscount_AppliesPercentage(t *testing.T) { ... }
+func TestParseConfig_WithMissingFields_ReturnsError(t *testing.T) { ... }
+```
+
+## Patterns
+
+### AAA with testify
+
+```go
+func TestProcessOrder_WithValidOrder_ReturnsID(t *testing.T) {
+    // Arrange
+    repo := new(MockOrderRepository)
+    repo.On("Save", mock.Anything).Return(&Order{ID: "123"}, nil)
+    service := NewOrderService(repo)
+
+    // Act
+    result, err := service.ProcessOrder(context.Background(), validOrder)
+
+    // Assert
+    require.NoError(t, err)
+    assert.Equal(t, "123", result.ID)
+    repo.AssertExpectations(t)
+}
+
+func TestProcessOrder_WithInvalidOrder_ReturnsError(t *testing.T) {
+    // Arrange
+    service := NewOrderService(nil)
+
+    // Act
+    _, err := service.ProcessOrder(context.Background(), invalidOrder)
+
+    // Assert
+    assert.ErrorIs(t, err, ErrValidation)
+}
+```
+
+### Table-Driven Tests (Go idiom)
+
+```go
+func TestApplyDiscount(t *testing.T) {
+    tests := []struct {
+        name     string
+        price    float64
+        discount int
+        expected float64
+    }{
+        {"no discount", 100.0, 0, 100.0},
+        {"10 percent", 100.0, 10, 90.0},
+        {"50 percent", 100.0, 50, 50.0},
+    }
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := ApplyDiscount(tt.price, tt.discount)
+            assert.Equal(t, tt.expected, result)
+        })
+    }
+}
+```
+
+### Table-Driven with Error Cases
+
+```go
+func TestValidateOrder(t *testing.T) {
+    tests := []struct {
+        name    string
+        order   Order
+        wantErr error
+    }{
+        {"valid order", validOrder(), nil},
+        {"empty items", Order{Items: nil}, ErrEmptyItems},
+        {"negative total", Order{Total: -1}, ErrNegativeTotal},
+    }
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            err := ValidateOrder(tt.order)
+            if tt.wantErr != nil {
+                assert.ErrorIs(t, err, tt.wantErr)
+            } else {
+                assert.NoError(t, err)
+            }
+        })
+    }
+}
+```
+
+### Test Helpers
+
+```go
+// t.Helper() marks function as a test helper — errors report caller's line
+func newTestService(t *testing.T, opts ...func(*ServiceConfig)) *OrderService {
+    t.Helper()
+    cfg := defaultTestConfig()
+    for _, opt := range opts {
+        opt(cfg)
+    }
+    return NewOrderService(cfg)
+}
+
+// t.Cleanup() for automatic teardown
+func setupTestDB(t *testing.T) *sql.DB {
+    t.Helper()
+    db, err := sql.Open("sqlite3", ":memory:")
+    require.NoError(t, err)
+    t.Cleanup(func() { db.Close() })
+    return db
+}
+```
+
+### Subtests for Parallel Execution
+
+```go
+func TestOrderService(t *testing.T) {
+    t.Run("ProcessOrder", func(t *testing.T) {
+        t.Run("with valid order", func(t *testing.T) {
+            t.Parallel()
+            // ... test body
+        })
+        t.Run("with invalid order", func(t *testing.T) {
+            t.Parallel()
+            // ... test body
+        })
+    })
+}
+```
+
+### Error Testing
+
+```go
+// Check specific error
+func TestDivide_ByZero_ReturnsError(t *testing.T) {
+    _, err := Divide(1, 0)
+    assert.ErrorIs(t, err, ErrDivideByZero)
+}
+
+// Check error type
+func TestParse_InvalidInput_ReturnsParseError(t *testing.T) {
+    _, err := Parse("bad input")
+    var parseErr *ParseError
+    assert.ErrorAs(t, err, &parseErr)
+    assert.Equal(t, "bad input", parseErr.Input)
+}
+
+// Check error message
+func TestValidate_EmptyName_ReturnsErrorMessage(t *testing.T) {
+    err := Validate(User{Name: ""})
+    assert.EqualError(t, err, "name cannot be empty")
+}
+```
+
+## Mocking
+
+### testify/mock
+
+```go
+type MockOrderRepository struct {
+    mock.Mock
+}
+
+func (m *MockOrderRepository) Save(ctx context.Context, order *Order) (*Order, error) {
+    args := m.Called(ctx, order)
+    return args.Get(0).(*Order), args.Error(1)
+}
+
+// Usage
+repo := new(MockOrderRepository)
+repo.On("Save", mock.Anything, mock.Anything).Return(&Order{ID: "123"}, nil)
+// ... use repo ...
+repo.AssertExpectations(t)
+```
+
+### Interface-based fakes (preferred for simple cases)
+
+```go
+// Define a minimal interface where you use it
+type orderSaver interface {
+    Save(ctx context.Context, order *Order) (*Order, error)
+}
+
+// Fake implementation in test file
+type fakeOrderSaver struct {
+    saved []*Order
+    err   error
+}
+
+func (f *fakeOrderSaver) Save(_ context.Context, order *Order) (*Order, error) {
+    if f.err != nil {
+        return nil, f.err
+    }
+    f.saved = append(f.saved, order)
+    return &Order{ID: "123"}, nil
+}
+```
+
+### What NOT to mock
+
+- Value types, structs used as data containers
+- Pure functions with no side effects
+- The package under test itself
+- Standard library types (use real `bytes.Buffer`, etc.)
+
+Mock only at system boundaries: external APIs, databases, file system, time.
+
+## File Conventions
+
+- `*_test.go` in the same package (white-box) or `_test` package (black-box)
+- `go test ./...` to run all tests
+- `testdata/` for test fixtures (ignored by Go tooling)
+- `go test -race ./...` to detect race conditions
+- `go test -cover ./...` for coverage
+
+## Authoritative Sources
+
+- testing package: https://pkg.go.dev/testing
+- testify: https://github.com/stretchr/testify
+- gomock: https://github.com/uber-go/mock
+- Kent Beck — Canon TDD: https://tidyfirst.substack.com/p/canon-tdd
+- Martin Fowler — Mocks Aren't Stubs: https://martinfowler.com/articles/mocksArentStubs.html
+
+## Reference Materials
+
+- **[Anti-Patterns](reference/anti-patterns.md)** — Common testing mistakes and how to fix them
+- **[TDD Workflow Patterns](reference/tdd-workflow-patterns.md)** — Red-Green-Refactor, Transformation Priority Premise, when to use TDD

package/packs/go-pack/skills/grimoire.unit-testing-go/reference/anti-patterns.md

@@ -0,0 +1,244 @@
+# Testing Anti-Patterns
+
+Common testing mistakes that reduce test value and increase maintenance cost. These are language-agnostic — they apply to any test framework.
+
+## Table of Contents
+
+- [The Liar](#the-liar)
+- [The Giant](#the-giant)
+- [Excessive Setup](#excessive-setup)
+- [The Slow Poke](#the-slow-poke)
+- [The Peeping Tom](#the-peeping-tom)
+- [The Mockery](#the-mockery)
+- [The Inspector](#the-inspector)
+- [The Flaky Test](#the-flaky-test)
+- [The Cargo Culter](#the-cargo-culter)
+- [The Hard Test](#the-hard-test)
+
+## The Liar
+
+**What it is:** A test that passes but doesn't actually verify the behavior it claims to test. It gives false confidence.
+
+**How to spot it:**
+- Test name says "validates input" but assertions only check the return type
+- Assertions are too loose (`assert result is not None` instead of checking the actual value)
+- Test catches exceptions broadly and passes regardless
+
+**Fix:** Ensure assertions directly verify the specific behavior described in the test name. Every assertion should fail if the behavior breaks.
+
+```python
+# Bad — passes even if discount logic is completely wrong
+def test_apply_discount():
+    result = apply_discount(100, 10)
+    assert result is not None
+
+# Good — fails if the calculation is wrong
+def test_apply_discount_with_10_percent_returns_90():
+    result = apply_discount(100, 10)
+    assert result == 90.0
+```
+
+## The Giant
+
+**What it is:** A single test that verifies too many things. When it fails, you can't tell which behavior broke.
+
+**How to spot it:**
+- Test has more than 8-10 assertions
+- Test name uses "and" (e.g., "creates user and sends email and updates cache")
+- Multiple Act phases in one test
+
+**Fix:** Split into focused tests, each verifying one logical concept. Multiple assertions are fine if they verify aspects of the same behavior.
+
+```typescript
+// Bad — three unrelated behaviors in one test
+test('user registration works', () => {
+  const user = register({ name: 'Alice', email: 'alice@test.com' });
+  expect(user.id).toBeDefined();
+  expect(emailService.send).toHaveBeenCalled();
+  expect(cache.set).toHaveBeenCalledWith(`user:${user.id}`, user);
+  expect(auditLog.entries).toHaveLength(1);
+});
+
+// Good — separate tests for each behavior
+test('register with valid data creates user with id', () => { ... });
+test('register with valid data sends welcome email', () => { ... });
+test('register with valid data caches the user', () => { ... });
+test('register with valid data writes audit log entry', () => { ... });
+```
+
+## Excessive Setup
+
+**What it is:** Tests that require dozens of lines of setup before the actual test logic. Often signals that the code under test has too many dependencies.
+
+**How to spot it:**
+- Arrange section is 20+ lines
+- Multiple mocks configured with complex behaviors
+- Shared setup methods that configure things most tests don't need
+
+**Fix:** Use factory methods/builders for test data. Consider whether the code under test needs refactoring to reduce dependencies. Only set up what the specific test needs.
+
+```go
+// Bad — every test sets up the entire world
+func TestProcessOrder(t *testing.T) {
+    db := setupDatabase()
+    cache := setupCache()
+    logger := setupLogger()
+    emailClient := setupEmailClient()
+    validator := NewValidator(db)
+    processor := NewProcessor(cache)
+    service := NewOrderService(db, cache, logger, emailClient, validator, processor)
+    // ... 10 more lines of setup
+    result, err := service.ProcessOrder(ctx, order)
+    assert.NoError(t, err)
+}
+
+// Good — factory method hides irrelevant details
+func TestProcessOrder_WithValidOrder_Succeeds(t *testing.T) {
+    service := newTestOrderService(t)
+    result, err := service.ProcessOrder(ctx, validOrder())
+    assert.NoError(t, err)
+    assert.Equal(t, "processed", result.Status)
+}
+```
+
+## The Slow Poke
+
+**What it is:** Tests that are slow because they use real I/O, network calls, or sleeps. Slow tests get run less frequently and slow down the feedback loop.
+
+**How to spot it:**
+- `time.Sleep()`, `Thread.sleep()`, `setTimeout` in tests
+- Real HTTP calls, database connections, file system operations
+- Test suite takes more than a few seconds for unit tests
+
+**Fix:** Mock external dependencies. Use fake implementations for I/O. Replace time-based waits with event-based synchronization.
+
+## The Peeping Tom
+
+**What it is:** Tests that access private/internal state to verify behavior instead of testing through the public interface.
+
+**How to spot it:**
+- Reflection to access private fields
+- Testing internal method calls instead of observable results
+- Assertions on implementation details (internal data structures, private counters)
+
+**Fix:** Test through the public API. If you can't verify behavior through the public interface, the class may need a design change (e.g., expose a query method or extract a collaborator).
+
+## The Mockery
+
+**What it is:** Tests that mock so heavily that they're testing mock configurations rather than real behavior. Every dependency is mocked, including simple value objects.
+
+**How to spot it:**
+- More mock setup lines than actual test logic
+- Mocking concrete classes, value objects, or data structures
+- Test passes but the real system fails because mocks don't match reality
+
+**Fix:** Only mock at system boundaries (external services, databases, clocks). Use real implementations for in-process collaborators when practical.
+
+## The Inspector
+
+**What it is:** Tests that verify exact method calls and their order rather than outcomes. They break whenever the implementation changes, even if behavior is preserved.
+
+**How to spot it:**
+- `verify(mock, times(1)).method()` for every mock interaction
+- Assertions on call order
+- Test breaks when you refactor without changing behavior
+
+**Fix:** Verify state (the result) rather than interactions (how it got there). Only verify interactions for side effects that ARE the behavior (e.g., "email was sent").
+
+```java
+// Bad — breaks if implementation changes sort algorithm
+verify(sorter, times(1)).quickSort(any());
+verify(sorter, never()).mergeSort(any());
+
+// Good — verifies the outcome
+assertThat(result).isSortedAccordingTo(naturalOrder());
+```
+
+## The Flaky Test
+
+**What it is:** Tests that pass and fail intermittently without code changes. They erode trust in the test suite.
+
+**Common causes:**
+- Time-dependent logic (`new Date()`, `time.Now()`)
+- Random data without fixed seeds
+- Shared mutable state between tests
+- Race conditions in async tests
+- Dependency on test execution order
+
+**Fix:** Inject time as a dependency. Use fixed seeds for randomness. Ensure test isolation. Use proper async synchronization.
+
+## The Cargo Culter
+
+**What it is:** Writing tests to hit a coverage percentage target rather than to verify behavior. The tests exist to satisfy a metric, not to provide confidence.
+
+**How to spot it:**
+- Tests that assert trivially obvious things (e.g., `assert user.name == user.name`)
+- Every private method has a corresponding test accessed via reflection
+- 100% coverage but bugs still escape to production
+- Test suite takes minutes to pass but developers don't trust it
+
+**Fix:** Coverage is a diagnostic tool, not a goal. Use it to find untested gaps, not as a number to optimize. High 80s–90% emerges naturally from disciplined TDD. A test that only exists to push coverage up is worse than no test — it adds maintenance cost without adding confidence.
+
+```python
+# Bad — written for coverage, not for confidence
+def test_user_has_name():
+    user = User(name="Alice")
+    assert user.name is not None  # This verifies nothing meaningful
+
+# Good — written to verify a business rule
+def test_user_with_empty_name_raises_validation_error():
+    with pytest.raises(ValidationError, match="name cannot be empty"):
+        User(name="")
+```
+
+> See: https://martinfowler.com/bliki/TestCoverage.html
+
+## The Hard Test
+
+**What it is:** Not an anti-pattern in the test itself, but a signal from the test about the production code. When a test is painful, complex, or requires elaborate setup, the production code has a design problem.
+
+**How to spot it:**
+- Need to mock 5+ dependencies to test one class
+- Need to access private internals to verify behavior
+- Test requires a complex sequence of operations just to get to the state under test
+- You find yourself thinking "testing this would be too hard"
+
+**What it signals:**
+- Too many responsibilities in one class (SRP violation)
+- Hidden dependencies or tight coupling
+- Poor separation of concerns
+- Untestable architecture (e.g., side effects embedded in business logic)
+
+**Fix:** Resist the urge to skip the test or work around it with clever mocking. Instead, fix the production code design. Extract classes, inject dependencies, separate concerns. A hard test is a free design review — take the feedback.
+
+```python
+# Hard to test — service does too much
+class OrderService:
+    def process(self, order):
+        db = Database()          # hidden dependency
+        email = EmailClient()    # hidden dependency
+        self._validate(order)
+        db.save(order)
+        email.send_confirmation(order)
+        self._update_inventory(order)  # another responsibility
+
+# Easy to test — dependencies explicit, concerns separated
+class OrderService:
+    def __init__(self, repo: OrderRepository, notifier: Notifier):
+        self._repo = repo
+        self._notifier = notifier
+
+    def process(self, order: Order) -> OrderResult:
+        self._validate(order)
+        saved = self._repo.save(order)
+        self._notifier.notify(saved)
+        return saved
+```
+
+---
+
+## Further Reading
+
+- xUnit Patterns (Meszaros): http://xunitpatterns.com
+- Codepipes testing anti-patterns: https://blog.codepipes.com/testing/software-testing-antipatterns.html
+- Google SWE Book — Test Doubles: https://abseil.io/resources/swe-book/html/ch13.html