testing-workflows

Testing workflows

Use this skill when

• Running, extending, or debugging Go unit or integration tests for this project.
• Tests are failing unexpectedly and the cause is not obvious.
• A feature change needs appropriate coverage across domain, repository, or handler layers.

Do not use this skill when

• Failures clearly stem from stale generated code (use code-generation first).
• The work is database schema change rather than test authoring (use database-migrations).

Routing boundary

Situation	Use this skill?	Route instead
Go unit, integration, or endpoint test authoring/debugging	Yes	-
Focused HTTP smoke validation after changes	No	api-smoke-validation
Stale generated artifacts are the root cause	No	code-generation
Main task is schema evolution, not test behavior	No	database-migrations

Inputs to gather

• The failing test name or the module whose coverage is changing.
• The entrypoint used by this repository (make test, go test, or a CI target).
• Whether integration tests need a live DB and whether its credentials are available.

First move

• Run the narrowest relevant test target first and read the actual failure output.
• If compile errors reference generated packages, run make generate before re-running.

Outputs

• A narrow failing-test reproduction and diagnosis, including generator refresh when stale generated inputs are the real cause.
• New or updated tests for the touched domain, repository, or handler behavior at the correct scope.
• Broader test-run evidence showing the fix or feature is ready beyond the isolated case.

Workflow

1. Reproduce with the narrowest failing test target first.
2. Refresh generated artifacts when compile output indicates stale generated inputs.
3. Add or adjust tests at the correct layer (domain, repository, and/or HTTP handlers).
4. Re-run narrow scope, then broaden to the repository-level suite before handoff.

Fast paths

make test                           # all tests (may run generation first)
make test-unit                      # unit tests only
make test-integration               # integration tests only
go test -v -run TestName ./pkg/...  # single test, verbose

Catalog position

Use this as the default testing entry point for Go work, including HTTP integration behavior. Use api-smoke-validation when the need is fast endpoint smoke checks rather than broader test development or debugging.

Debugging failures

Follow this sequence:

1. Compile errors in generated packages → make generate, then retry.
2. Specific test failure → go test -v -run TestName ./path/to/pkg to isolate.
3. DB-related failure in integration tests → verify DATABASE_URL is set and migrations are applied.
4. Flaky / order-dependent tests → check for shared mutable state; each test must be isolated.

Coverage expectations when adding features

Layer	What to test
Domain / service	Validation rules and business logic (prefer table-driven tests)
Repository	Persistence behaviour against a real or in-memory DB
HTTP handlers	Status codes, auth enforcement, request/response shapes

Guardrails

• Run make generate before make test whenever schema, query, or template files changed.
• Repository tests must work with at least one DB (e.g. SQLite or in-memory). Optional DBs should skip, not fail, when unavailable.
• New features require tests before merging.
• Tests must be order-independent with no shared mutable state between test cases.
• Reach for code-generation first when failures smell like stale generated inputs rather than test logic.

Validation

• Re-run the narrow failing test after each suspected fix before broadening.
• Run the repository's broader test target before claiming the change is ready.
• When adding features, confirm new or updated tests cover the touched domain, repository, or handler behavior.

Examples

• "Add integration coverage for this authenticated endpoint and include status-code and response-shape assertions."
• "Debug this flaky Go test suite, starting from the failing handler tests and broadening only after the root cause is fixed."
• "Extend tests for this repository change across domain logic, repository behavior, and HTTP handlers."

Reference files

• Read references/examples.md when you need concrete user utterances, expected behaviour, or a model answer shape to mirror.
• Read references/edge-cases.md when the request is a near miss, partially matches this skill, or the first attempt fails.