# Testing Workflows

> Write, run, and debug Go tests, unit and integration, and diagnose Go build, toolchain, and CI-parity failures (GOROOT/GOTOOLDIR overrides, govulncheck stdlib findings, TempDir race flakes, local-green CI-red). Use when adding test coverage, debugging test failures, or when go build or CI fails for environmental reasons.

- Skill: `matt-riley/testing-workflows` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx get-skill add matt-riley/testing-workflows`
- Raw SKILL.md: https://api.skillmd.com/api/skills/matt-riley/testing-workflows/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: GNU GPL v3
- Author: matt-riley (https://skillmd.com/u/matt-riley)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/matt-riley/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.
- `go build` or CI fails for environmental reasons: toolchain mismatch, stale `GOROOT`/`GOTOOLDIR`, `govulncheck` stdlib findings, or local-green CI-red.

## Do not use this skill when

- The main risk is specifically HTTP endpoint behaviour (use `http-api`).
- Failures clearly stem from stale generated code (use `code-generation` first).
- The work is database schema change rather than test authoring (use `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

Use the most specific path for the task; fall through to the debugging sequence when tests fail for unclear reasons. Layer in `http-api` when the problem is specifically endpoint contracts, auth behaviour, or request/response assertions over HTTP.

### Fast paths

```bash
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
```

### Debugging failures

Follow this sequence:

0. **Build, toolchain, or CI-only failure** → follow `references/go-build-and-test.md` and work through `references/go-build-and-test-toolchain-environment-checklist.md` before touching test logic.
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

- `The domain validation test is failing after I renamed a field — isolate it and show me the fix.`
- `Add integration tests for the new repository method so it works against both SQLite and Postgres.`
- `The CI test run is red but I can't reproduce it locally — step me through the debugging sequence.`

## Reference files

- [`references/examples.md`](references/examples.md) — concrete user utterances, expected behaviour, and model answer shapes
- [`references/edge-cases.md`](references/edge-cases.md) — near-miss requests, partial matches, and first-attempt failure patterns
- [`references/go-build-and-test.md`](references/go-build-and-test.md) — build, toolchain, and CI-parity diagnosis

