write-tests

Writing Backend Tests

Thesis: Test the contract, not the implementation. Integration tests hit real PostgreSQL; unit tests are table-driven; every service method has error path coverage.

Before writing tests for a module, read docs/modules/{module}/spec.md for the Critical Test Scenarios section — it's a verified test plan.

Integration Tests (Service Layer)

Test real SQL against a real PostgreSQL instance using testutil.WithTestDB.

//go:build integration

package service_test

import (
    "testing"
    "github.com/golid-ai/golid/backend/internal/service"
    "github.com/golid-ai/golid/backend/internal/testutil"
)

func TestItemService_Create(t *testing.T) {
    testutil.WithTestDB(t, func(pool *pgxpool.Pool) {
        svc := service.NewItemService(pool, 20, 100)

        // Seed prerequisite data with raw SQL
        _, err := pool.Exec(ctx, `INSERT INTO users (...) VALUES (...)`)
        // ...

        // Test the service method
        result, err := svc.Create(ctx, &service.CreateItemInput{...})
        if err != nil { t.Fatalf("expected no error, got %v", err) }
        if result.Title != "Test Item" { t.Errorf("expected title 'Test Item', got %s", result.Title) }
    })
}

Key Rules

• Build tag: //go:build integration at the top of the file.
• File naming: x_integration_test.go (not x_test.go) to make it clear.
• Seed with raw SQL: Use pool.Exec with INSERT statements. Never use service methods to seed — they have their own validation and side effects.
• Test one thing per function: Each test function should test one behavior (happy path, error case, permission check, etc.).
• Clean state: WithTestDB provides a fresh database for each test. No cleanup needed.

What to Test

• Happy paths: Create, Read, Update, Delete with valid inputs.
• Permission checks: Wrong user type, non-owner, non-member. Expect FORBIDDEN.
• Status guards: Operation on wrong-status parent. Expect BAD_REQUEST.
• Not found: Non-existent ID. Expect NOT_FOUND.
• Conflict: Duplicate entries. Expect CONFLICT.
• Edge cases: Empty arrays, null optional fields, boundary values.