@baselane/packs 0.1.3 → 0.1.5

package/packs/go-rules/rendered/GEMINI.md

@@ -1,3 +1,1397 @@
 # GEMINI.md
 
 @AGENTS.md
+
+## Skills
+
+### golang-patterns
+
+Idiomatic Go patterns, best practices, and conventions for building robust, efficient, and maintainable Go applications — API shape, error handling, concurrency, interface design, package organization, and performance. Use when writing, reviewing, or refactoring Go code, or designing Go packages/modules.
+
+# Go Development Patterns
+
+Idiomatic Go patterns and best practices for building robust, efficient, and maintainable applications.
+
+## When to use
+
+- Writing new Go code.
+- Reviewing Go code.
+- Refactoring existing Go code.
+- Designing Go packages/modules.
+
+## Core principles
+
+### 1. Simplicity and clarity
+
+Go favors simplicity over cleverness. Code should be obvious and easy to read.
+
+\`\`\`go
+// Good: clear and direct
+func GetUser(id string) (*User, error) {
+    user, err := db.FindUser(id)
+    if err != nil {
+        return nil, fmt.Errorf("get user %s: %w", id, err)
+    }
+    return user, nil
+}
+
+// Bad: overly clever
+func GetUser(id string) (*User, error) {
+    return func() (*User, error) {
+        if u, e := db.FindUser(id); e == nil {
+            return u, nil
+        } else {
+            return nil, e
+        }
+    }()
+}
+\`\`\`
+
+### 2. Make the zero value useful
+
+Design types so their zero value is immediately usable without initialization.
+
+\`\`\`go
+// Good: zero value is useful
+type Counter struct {
+    mu    sync.Mutex
+    count int // zero value is 0, ready to use
+}
+
+func (c *Counter) Inc() {
+    c.mu.Lock()
+    c.count++
+    c.mu.Unlock()
+}
+
+// Good: bytes.Buffer works with zero value
+var buf bytes.Buffer
+buf.WriteString("hello")
+
+// Bad: requires initialization
+type BadCounter struct {
+    counts map[string]int // nil map will panic
+}
+\`\`\`
+
+### 3. Accept interfaces, return structs
+
+Functions should accept interface parameters and return concrete types.
+
+\`\`\`go
+// Good: accepts interface, returns concrete type
+func ProcessData(r io.Reader) (*Result, error) {
+    data, err := io.ReadAll(r)
+    if err != nil {
+        return nil, err
+    }
+    return &Result{Data: data}, nil
+}
+
+// Bad: returns interface (hides implementation details unnecessarily)
+func ProcessData(r io.Reader) (io.Reader, error) {
+    // ...
+}
+\`\`\`
+
+## Error handling patterns
+
+### Error wrapping with context
+
+\`\`\`go
+func LoadConfig(path string) (*Config, error) {
+    data, err := os.ReadFile(path)
+    if err != nil {
+        return nil, fmt.Errorf("load config %s: %w", path, err)
+    }
+
+    var cfg Config
+    if err := json.Unmarshal(data, &cfg); err != nil {
+        return nil, fmt.Errorf("parse config %s: %w", path, err)
+    }
+
+    return &cfg, nil
+}
+\`\`\`
+
+### Custom error types
+
+\`\`\`go
+// Define domain-specific errors
+type ValidationError struct {
+    Field   string
+    Message string
+}
+
+func (e *ValidationError) Error() string {
+    return fmt.Sprintf("validation failed on %s: %s", e.Field, e.Message)
+}
+
+// Sentinel errors for common cases
+var (
+    ErrNotFound     = errors.New("resource not found")
+    ErrUnauthorized = errors.New("unauthorized")
+    ErrInvalidInput = errors.New("invalid input")
+)
+\`\`\`
+
+### Error checking with errors.Is and errors.As
+
+\`\`\`go
+func HandleError(err error) {
+    // Check for specific error
+    if errors.Is(err, sql.ErrNoRows) {
+        log.Println("No records found")
+        return
+    }
+
+    // Check for error type
+    var validationErr *ValidationError
+    if errors.As(err, &validationErr) {
+        log.Printf("Validation error on field %s: %s",
+            validationErr.Field, validationErr.Message)
+        return
+    }
+
+    // Unknown error
+    log.Printf("Unexpected error: %v", err)
+}
+\`\`\`
+
+### Never ignore errors
+
+\`\`\`go
+// Bad: ignoring error with blank identifier
+result, _ := doSomething()
+
+// Good: handle or explicitly document why it's safe to ignore
+result, err := doSomething()
+if err != nil {
+    return err
+}
+
+// Acceptable: when error truly doesn't matter (rare)
+_ = writer.Close() // Best-effort cleanup, error logged elsewhere
+\`\`\`
+
+## Concurrency patterns
+
+### Worker pool
+
+\`\`\`go
+func WorkerPool(jobs <-chan Job, results chan<- Result, numWorkers int) {
+    var wg sync.WaitGroup
+
+    for i := 0; i < numWorkers; i++ {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            for job := range jobs {
+                results <- process(job)
+            }
+        }()
+    }
+
+    wg.Wait()
+    close(results)
+}
+\`\`\`
+
+### Context for cancellation and timeouts
+
+\`\`\`go
+func FetchWithTimeout(ctx context.Context, url string) ([]byte, error) {
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+    defer cancel()
+
+    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+    if err != nil {
+        return nil, fmt.Errorf("create request: %w", err)
+    }
+
+    resp, err := http.DefaultClient.Do(req)
+    if err != nil {
+        return nil, fmt.Errorf("fetch %s: %w", url, err)
+    }
+    defer resp.Body.Close()
+
+    return io.ReadAll(resp.Body)
+}
+\`\`\`
+
+### Graceful shutdown
+
+\`\`\`go
+func GracefulShutdown(server *http.Server) {
+    quit := make(chan os.Signal, 1)
+    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+
+    <-quit
+    log.Println("Shutting down server...")
+
+    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+    defer cancel()
+
+    if err := server.Shutdown(ctx); err != nil {
+        log.Fatalf("Server forced to shutdown: %v", err)
+    }
+
+    log.Println("Server exited")
+}
+\`\`\`
+
+### errgroup for coordinated goroutines
+
+\`\`\`go
+import "golang.org/x/sync/errgroup"
+
+func FetchAll(ctx context.Context, urls []string) ([][]byte, error) {
+    g, ctx := errgroup.WithContext(ctx)
+    results := make([][]byte, len(urls))
+
+    for i, url := range urls {
+        i, url := i, url // Capture loop variables
+        g.Go(func() error {
+            data, err := FetchWithTimeout(ctx, url)
+            if err != nil {
+                return err
+            }
+            results[i] = data
+            return nil
+        })
+    }
+
+    if err := g.Wait(); err != nil {
+        return nil, err
+    }
+    return results, nil
+}
+\`\`\`
+
+### Avoiding goroutine leaks
+
+\`\`\`go
+// Bad: goroutine leak if context is cancelled
+func leakyFetch(ctx context.Context, url string) <-chan []byte {
+    ch := make(chan []byte)
+    go func() {
+        data, _ := fetch(url)
+        ch <- data // Blocks forever if no receiver
+    }()
+    return ch
+}
+
+// Good: properly handles cancellation
+func safeFetch(ctx context.Context, url string) <-chan []byte {
+    ch := make(chan []byte, 1) // Buffered channel
+    go func() {
+        data, err := fetch(url)
+        if err != nil {
+            return
+        }
+        select {
+        case ch <- data:
+        case <-ctx.Done():
+        }
+    }()
+    return ch
+}
+\`\`\`
+
+## Interface design
+
+### Small, focused interfaces
+
+\`\`\`go
+// Good: single-method interfaces
+type Reader interface {
+    Read(p []byte) (n int, err error)
+}
+
+type Writer interface {
+    Write(p []byte) (n int, err error)
+}
+
+type Closer interface {
+    Close() error
+}
+
+// Compose interfaces as needed
+type ReadWriteCloser interface {
+    Reader
+    Writer
+    Closer
+}
+\`\`\`
+
+### Define interfaces where they're used
+
+\`\`\`go
+// In the consumer package, not the provider
+package service
+
+// UserStore defines what this service needs
+type UserStore interface {
+    GetUser(id string) (*User, error)
+    SaveUser(user *User) error
+}
+
+type Service struct {
+    store UserStore
+}
+
+// Concrete implementation can be in another package
+// It doesn't need to know about this interface
+\`\`\`
+
+### Optional behavior with type assertions
+
+\`\`\`go
+type Flusher interface {
+    Flush() error
+}
+
+func WriteAndFlush(w io.Writer, data []byte) error {
+    if _, err := w.Write(data); err != nil {
+        return err
+    }
+
+    // Flush if supported
+    if f, ok := w.(Flusher); ok {
+        return f.Flush()
+    }
+    return nil
+}
+\`\`\`
+
+## Package organization
+
+### Standard project layout
+
+\`\`\`text
+myproject/
+├── cmd/
+│   └── myapp/
+│       └── main.go           # Entry point
+├── internal/
+│   ├── handler/              # HTTP handlers
+│   ├── service/              # Business logic
+│   ├── repository/           # Data access
+│   └── config/                # Configuration
+├── pkg/
+│   └── client/                # Public API client
+├── api/
+│   └── v1/                    # API definitions (proto, OpenAPI)
+├── testdata/                  # Test fixtures
+├── go.mod
+├── go.sum
+└── Makefile
+\`\`\`
+
+### Package naming
+
+\`\`\`go
+// Good: short, lowercase, no underscores
+package http
+package json
+package user
+
+// Bad: verbose, mixed case, or redundant
+package httpHandler
+package json_parser
+package userService // Redundant 'Service' suffix
+\`\`\`
+
+### Avoid package-level state
+
+\`\`\`go
+// Bad: global mutable state
+var db *sql.DB
+
+func init() {
+    db, _ = sql.Open("postgres", os.Getenv("DATABASE_URL"))
+}
+
+// Good: dependency injection
+type Server struct {
+    db *sql.DB
+}
+
+func NewServer(db *sql.DB) *Server {
+    return &Server{db: db}
+}
+\`\`\`
+
+## Struct design
+
+### Functional options pattern
+
+\`\`\`go
+type Server struct {
+    addr    string
+    timeout time.Duration
+    logger  *log.Logger
+}
+
+type Option func(*Server)
+
+func WithTimeout(d time.Duration) Option {
+    return func(s *Server) {
+        s.timeout = d
+    }
+}
+
+func WithLogger(l *log.Logger) Option {
+    return func(s *Server) {
+        s.logger = l
+    }
+}
+
+func NewServer(addr string, opts ...Option) *Server {
+    s := &Server{
+        addr:    addr,
+        timeout: 30 * time.Second, // default
+        logger:  log.Default(),    // default
+    }
+    for _, opt := range opts {
+        opt(s)
+    }
+    return s
+}
+
+// Usage
+server := NewServer(":8080",
+    WithTimeout(60*time.Second),
+    WithLogger(customLogger),
+)
+\`\`\`
+
+### Embedding for composition
+
+\`\`\`go
+type Logger struct {
+    prefix string
+}
+
+func (l *Logger) Log(msg string) {
+    fmt.Printf("[%s] %s\n", l.prefix, msg)
+}
+
+type Server struct {
+    *Logger // Embedding - Server gets Log method
+    addr    string
+}
+
+func NewServer(addr string) *Server {
+    return &Server{
+        Logger: &Logger{prefix: "SERVER"},
+        addr:   addr,
+    }
+}
+
+// Usage
+s := NewServer(":8080")
+s.Log("Starting...") // Calls embedded Logger.Log
+\`\`\`
+
+## Memory and performance
+
+### Preallocate slices when size is known
+
+\`\`\`go
+// Bad: grows slice multiple times
+func processItems(items []Item) []Result {
+    var results []Result
+    for _, item := range items {
+        results = append(results, process(item))
+    }
+    return results
+}
+
+// Good: single allocation
+func processItems(items []Item) []Result {
+    results := make([]Result, 0, len(items))
+    for _, item := range items {
+        results = append(results, process(item))
+    }
+    return results
+}
+\`\`\`
+
+### Use sync.Pool for frequent allocations
+
+\`\`\`go
+var bufferPool = sync.Pool{
+    New: func() interface{} {
+        return new(bytes.Buffer)
+    },
+}
+
+func ProcessRequest(data []byte) []byte {
+    buf := bufferPool.Get().(*bytes.Buffer)
+    defer func() {
+        buf.Reset()
+        bufferPool.Put(buf)
+    }()
+
+    buf.Write(data)
+    // Process...
+    return buf.Bytes()
+}
+\`\`\`
+
+### Avoid string concatenation in loops
+
+\`\`\`go
+// Bad: creates many string allocations
+func join(parts []string) string {
+    var result string
+    for _, p := range parts {
+        result += p + ","
+    }
+    return result
+}
+
+// Good: single allocation with strings.Builder
+func join(parts []string) string {
+    var sb strings.Builder
+    for i, p := range parts {
+        if i > 0 {
+            sb.WriteString(",")
+        }
+        sb.WriteString(p)
+    }
+    return sb.String()
+}
+
+// Best: use standard library
+func join(parts []string) string {
+    return strings.Join(parts, ",")
+}
+\`\`\`
+
+## Go tooling integration
+
+### Essential commands
+
+\`\`\`bash
+# Build and run
+go build ./...
+go run ./cmd/myapp
+
+# Testing
+go test ./...
+go test -race ./...
+go test -cover ./...
+
+# Static analysis
+go vet ./...
+staticcheck ./...
+golangci-lint run
+
+# Module management
+go mod tidy
+go mod verify
+
+# Formatting
+gofmt -w .
+goimports -w .
+\`\`\`
+
+### Recommended linter configuration (.golangci.yml)
+
+\`\`\`yaml
+linters:
+  enable:
+    - errcheck
+    - gosimple
+    - govet
+    - ineffassign
+    - staticcheck
+    - unused
+    - gofmt
+    - goimports
+    - misspell
+    - unconvert
+    - unparam
+
+linters-settings:
+  errcheck:
+    check-type-assertions: true
+  govet:
+    enable:
+      - shadow
+
+issues:
+  exclude-use-default: false
+\`\`\`
+
+## Quick reference: Go idioms
+
+| Idiom | Description |
+|-------|-------------|
+| Accept interfaces, return structs | Functions accept interface params, return concrete types |
+| Errors are values | Treat errors as first-class values, not exceptions |
+| Don't communicate by sharing memory | Use channels for coordination between goroutines |
+| Make the zero value useful | Types should work without explicit initialization |
+| A little copying is better than a little dependency | Avoid unnecessary external dependencies |
+| Clear is better than clever | Prioritize readability over cleverness |
+| gofmt is no one's favorite but everyone's friend | Always format with gofmt/goimports |
+| Return early | Handle errors first, keep happy path unindented |
+
+## Anti-patterns to avoid
+
+\`\`\`go
+// Bad: naked returns in long functions
+func process() (result int, err error) {
+    // ... 50 lines ...
+    return // What is being returned?
+}
+
+// Bad: using panic for control flow
+func GetUser(id string) *User {
+    user, err := db.Find(id)
+    if err != nil {
+        panic(err) // Don't do this
+    }
+    return user
+}
+
+// Bad: passing context in struct
+type Request struct {
+    ctx context.Context // Context should be first param
+    ID  string
+}
+
+// Good: context as first parameter
+func ProcessRequest(ctx context.Context, id string) error {
+    // ...
+}
+
+// Bad: mixing value and pointer receivers
+type Counter struct{ n int }
+func (c Counter) Value() int { return c.n }    // Value receiver
+func (c *Counter) Increment() { c.n++ }        // Pointer receiver
+// Pick one style and be consistent
+\`\`\`
+
+**Remember**: Go code should be boring in the best way — predictable, consistent, and easy to understand. When in doubt, keep it simple.
+
+### golang-testing
+
+Go testing patterns including TDD workflow, table-driven tests, subtests, benchmarks, fuzzing, golden files, HTTP handler testing, mocking with interfaces, and coverage targets. Use when writing new Go functions, adding test coverage, creating benchmarks, or following TDD in a Go project.
+
+# Go Testing Patterns
+
+Comprehensive Go testing patterns for writing reliable, maintainable tests following TDD methodology.
+
+## When to use
+
+- Writing new Go functions or methods.
+- Adding test coverage to existing code.
+- Creating benchmarks for performance-critical code.
+- Implementing fuzz tests for input validation.
+- Following a TDD workflow in Go projects.
+
+## TDD workflow for Go
+
+### The RED-GREEN-REFACTOR cycle
+
+\`\`\`
+RED     → Write a failing test first
+GREEN   → Write minimal code to pass the test
+REFACTOR → Improve code while keeping tests green
+REPEAT  → Continue with next requirement
+\`\`\`
+
+### Step-by-step TDD in Go
+
+\`\`\`go
+// Step 1: Define the interface/signature
+// calculator.go
+package calculator
+
+func Add(a, b int) int {
+    panic("not implemented") // Placeholder
+}
+
+// Step 2: Write failing test (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)
+    }
+}
+
+// Step 3: Run test - verify FAIL
+// $ go test
+// --- FAIL: TestAdd (0.00s)
+// panic: not implemented
+
+// Step 4: Implement minimal code (GREEN)
+func Add(a, b int) int {
+    return a + b
+}
+
+// Step 5: Run test - verify PASS
+// $ go test
+// PASS
+
+// Step 6: Refactor if needed, verify tests still pass
+\`\`\`
+
+## Table-driven tests
+
+The standard pattern for Go tests. Enables comprehensive coverage with minimal code.
+
+\`\`\`go
+func TestAdd(t *testing.T) {
+    tests := []struct {
+        name     string
+        a, b     int
+        expected int
+    }{
+        {"positive numbers", 2, 3, 5},
+        {"negative numbers", -1, -2, -3},
+        {"zero values", 0, 0, 0},
+        {"mixed signs", -1, 1, 0},
+        {"large numbers", 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)
+            }
+        })
+    }
+}
+\`\`\`
+
+### Table-driven tests with error cases
+
+\`\`\`go
+func TestParseConfig(t *testing.T) {
+    tests := []struct {
+        name    string
+        input   string
+        want    *Config
+        wantErr bool
+    }{
+        {
+            name:  "valid config",
+            input: \`{"host": "localhost", "port": 8080}\`,
+            want:  &Config{Host: "localhost", Port: 8080},
+        },
+        {
+            name:    "invalid JSON",
+            input:   \`{invalid}\`,
+            wantErr: true,
+        },
+        {
+            name:    "empty input",
+            input:   "",
+            wantErr: true,
+        },
+        {
+            name:  "minimal config",
+            input: \`{}\`,
+            want:  &Config{}, // Zero value config
+        },
+    }
+
+    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("expected error, got nil")
+                }
+                return
+            }
+
+            if err != nil {
+                t.Fatalf("unexpected error: %v", err)
+            }
+
+            if !reflect.DeepEqual(got, tt.want) {
+                t.Errorf("got %+v; want %+v", got, tt.want)
+            }
+        })
+    }
+}
+\`\`\`
+
+## Subtests and sub-benchmarks
+
+### Organizing related tests
+
+\`\`\`go
+func TestUser(t *testing.T) {
+    // Setup shared by all 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 failed: %v", err)
+        }
+        if user.ID == "" {
+            t.Error("expected user ID to be set")
+        }
+    })
+
+    t.Run("Get", func(t *testing.T) {
+        user, err := db.GetUser("alice-id")
+        if err != nil {
+            t.Fatalf("GetUser failed: %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) {
+        // ...
+    })
+}
+\`\`\`
+
+### Parallel subtests
+
+\`\`\`go
+func TestParallel(t *testing.T) {
+    tests := []struct {
+        name  string
+        input string
+    }{
+        {"case1", "input1"},
+        {"case2", "input2"},
+        {"case3", "input3"},
+    }
+
+    for _, tt := range tests {
+        tt := tt // Capture range variable
+        t.Run(tt.name, func(t *testing.T) {
+            t.Parallel() // Run subtests in parallel
+            result := Process(tt.input)
+            // assertions...
+            _ = result
+        })
+    }
+}
+\`\`\`
+
+## Test helpers
+
+### Helper functions
+
+\`\`\`go
+func setupTestDB(t *testing.T) *sql.DB {
+    t.Helper() // Marks this as a helper function
+
+    db, err := sql.Open("sqlite3", ":memory:")
+    if err != nil {
+        t.Fatalf("failed to open database: %v", err)
+    }
+
+    // Cleanup when test finishes
+    t.Cleanup(func() {
+        db.Close()
+    })
+
+    // Run migrations
+    if _, err := db.Exec(schema); err != nil {
+        t.Fatalf("failed to create schema: %v", err)
+    }
+
+    return db
+}
+
+func assertNoError(t *testing.T, err error) {
+    t.Helper()
+    if err != nil {
+        t.Fatalf("unexpected error: %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)
+    }
+}
+\`\`\`
+
+### Temporary files and directories
+
+\`\`\`go
+func TestFileProcessing(t *testing.T) {
+    // Create temp directory - automatically cleaned up
+    tmpDir := t.TempDir()
+
+    // Create test file
+    testFile := filepath.Join(tmpDir, "test.txt")
+    err := os.WriteFile(testFile, []byte("test content"), 0644)
+    if err != nil {
+        t.Fatalf("failed to create test file: %v", err)
+    }
+
+    // Run test
+    result, err := ProcessFile(testFile)
+    if err != nil {
+        t.Fatalf("ProcessFile failed: %v", err)
+    }
+
+    // Assert...
+    _ = result
+}
+\`\`\`
+
+## Golden files
+
+Testing against expected output files stored in \`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 {
+                // Update golden file: go test -update
+                err := os.WriteFile(golden, got, 0644)
+                if err != nil {
+                    t.Fatalf("failed to update golden file: %v", err)
+                }
+            }
+
+            want, err := os.ReadFile(golden)
+            if err != nil {
+                t.Fatalf("failed to read golden file: %v", err)
+            }
+
+            if !bytes.Equal(got, want) {
+                t.Errorf("output mismatch:\ngot:\n%s\nwant:\n%s", got, want)
+            }
+        })
+    }
+}
+\`\`\`
+
+## Mocking with interfaces
+
+### Interface-based mocking
+
+\`\`\`go
+// Define interface for dependencies
+type UserRepository interface {
+    GetUser(id string) (*User, error)
+    SaveUser(user *User) error
+}
+
+// Production implementation
+type PostgresUserRepository struct {
+    db *sql.DB
+}
+
+func (r *PostgresUserRepository) GetUser(id string) (*User, error) {
+    // Real database query
+}
+
+// Mock implementation for 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 using 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("unexpected error: %v", err)
+    }
+    if user.Name != "Alice" {
+        t.Errorf("got name %q; want %q", user.Name, "Alice")
+    }
+}
+\`\`\`
+
+## Benchmarks
+
+### Basic benchmarks
+
+\`\`\`go
+func BenchmarkProcess(b *testing.B) {
+    data := generateTestData(1000)
+    b.ResetTimer() // Don't count setup time
+
+    for i := 0; i < b.N; i++ {
+        Process(data)
+    }
+}
+
+// Run: go test -bench=BenchmarkProcess -benchmem
+// Output: BenchmarkProcess-8   10000   105234 ns/op   4096 B/op   10 allocs/op
+\`\`\`
+
+### Benchmark with different sizes
+
+\`\`\`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++ {
+                // Make a copy to avoid sorting already sorted data
+                tmp := make([]int, len(data))
+                copy(tmp, data)
+                sort.Ints(tmp)
+            }
+        })
+    }
+}
+\`\`\`
+
+### Memory allocation benchmarks
+
+\`\`\`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+)
+
+### Basic fuzz test
+
+\`\`\`go
+func FuzzParseJSON(f *testing.F) {
+    // Add seed corpus
+    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 {
+            // Invalid JSON is expected for random input
+            return
+        }
+
+        // If parsing succeeded, re-encoding should work
+        _, err = json.Marshal(result)
+        if err != nil {
+            t.Errorf("Marshal failed after successful Unmarshal: %v", err)
+        }
+    })
+}
+
+// Run: go test -fuzz=FuzzParseJSON -fuzztime=30s
+\`\`\`
+
+### Fuzz test with multiple inputs
+
+\`\`\`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)
+
+        // Property: Compare(a, a) should always equal 0
+        if a == b && result != 0 {
+            t.Errorf("Compare(%q, %q) = %d; want 0", a, b, result)
+        }
+
+        // Property: Compare(a, b) and Compare(b, a) should have opposite signs
+        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; inconsistent",
+                    a, b, result, b, a, reverse)
+            }
+        }
+    })
+}
+\`\`\`
+
+## Test coverage
+
+### Running coverage
+
+\`\`\`bash
+# Basic coverage
+go test -cover ./...
+
+# Generate coverage profile
+go test -coverprofile=coverage.out ./...
+
+# View coverage in browser
+go tool cover -html=coverage.out
+
+# View coverage by function
+go tool cover -func=coverage.out
+
+# Coverage with race detection
+go test -race -coverprofile=coverage.out ./...
+\`\`\`
+
+### Coverage targets
+
+| Code Type | Target |
+|-----------|--------|
+| Critical business logic | 100% |
+| Public APIs | 90%+ |
+| General code | 80%+ |
+| Generated code | Exclude |
+
+### Excluding generated code from coverage
+
+\`\`\`go
+//go:generate mockgen -source=interface.go -destination=mock_interface.go
+
+// In coverage profile, exclude with build tags:
+// go test -cover -tags=!generate ./...
+\`\`\`
+
+## HTTP handler testing
+
+\`\`\`go
+func TestHealthHandler(t *testing.T) {
+    // Create request
+    req := httptest.NewRequest(http.MethodGet, "/health", nil)
+    w := httptest.NewRecorder()
+
+    // Call handler
+    HealthHandler(w, req)
+
+    // Check response
+    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:       "get user",
+            method:     http.MethodGet,
+            path:       "/users/123",
+            wantStatus: http.StatusOK,
+            wantBody:   \`{"id":"123","name":"Alice"}\`,
+        },
+        {
+            name:       "not found",
+            method:     http.MethodGet,
+            path:       "/users/999",
+            wantStatus: http.StatusNotFound,
+        },
+        {
+            name:       "create user",
+            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)
+            }
+        })
+    }
+}
+\`\`\`
+
+## Testing commands
+
+\`\`\`bash
+# Run all tests
+go test ./...
+
+# Run tests with verbose output
+go test -v ./...
+
+# Run specific test
+go test -run TestAdd ./...
+
+# Run tests matching pattern
+go test -run "TestUser/Create" ./...
+
+# Run tests with race detector
+go test -race ./...
+
+# Run tests with coverage
+go test -cover -coverprofile=coverage.out ./...
+
+# Run short tests only
+go test -short ./...
+
+# Run tests with timeout
+go test -timeout 30s ./...
+
+# Run benchmarks
+go test -bench=. -benchmem ./...
+
+# Run fuzzing
+go test -fuzz=FuzzParse -fuzztime=30s ./...
+
+# Count test runs (for flaky test detection)
+go test -count=10 ./...
+\`\`\`
+
+## Best practices
+
+**DO:**
+- Write tests FIRST (TDD).
+- Use table-driven tests for comprehensive coverage.
+- Test behavior, not implementation.
+- Use \`t.Helper()\` in helper functions.
+- Use \`t.Parallel()\` for independent tests.
+- Clean up resources with \`t.Cleanup()\`.
+- Use meaningful test names that describe the scenario.
+
+**DON'T:**
+- Test private functions directly (test through the public API).
+- Use \`time.Sleep()\` in tests (use channels or conditions).
+- Ignore flaky tests (fix or remove them).
+- Mock everything (prefer integration tests when possible).
+- Skip error path testing.
+
+## Integration with CI/CD
+
+\`\`\`yaml
+# GitHub Actions example
+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}'
+\`\`\`
+
+**Remember**: Tests are documentation. They show how your code is meant to be used. Write them clearly and keep them up to date.