| name | setup-test-suite |
| description | Set up a repository's baseline unit and integration test suite, including package scripts, minimal passing example tests, and an isolated database strategy when the app uses a database. Use once per repo or when test tooling is missing or broken. Do not use for implementing feature coverage inside normal issues. |
| metadata | {"author":"marioaulima","version":"1.1.0"} |
Set Up Test Suite
One-time setup of a repo's baseline unit + integration test infrastructure. Use when test tooling is missing, weak, broken, or unconfigured — NOT for feature-specific coverage during normal issue work.
Workflow
Track these as todos. Do not skip step 1. Do not write any code before completing steps 1–2.
1. Inspect before changing anything
Detect, without editing: language/runtime · package manager · framework · existing test tooling · existing scripts · app entrypoints · database usage · ORM/query layer · migration tooling · env var conventions · CI/hook setup. Record findings before proceeding.
2. STOP — Ask the user before writing any code
This step is mandatory. Do not skip. Do not assume. Do not proceed to step 3 until the user answers.
Present findings from step 1, then ask:
Question A — Test runner (only if multiple options are valid for the detected stack):
"Which test runner do you want? Options for [detected stack]: [list options, e.g. Vitest / Jest]. Default recommendation: [X] because [reason]."
Question B — Database strategy (only if the repo uses a DB):
"The repo uses [ORM/DB]. Integration tests need an isolated DB. Which strategy do you want?
- Testcontainers (spins up real Postgres container per run — requires Docker)
- Docker Compose (dedicated test compose file — requires Docker)
- Framework-native test transactions (rollback after each test — no container needed)
- Branch/separate DB (e.g. a Neon branch for tests — requires credentials)
- Skip for now (use fake env vars, only test routes that don't hit DB)"
Wait for user answers before continuing.
3. Configure unit + integration tiers
- Unit: fast, no I/O, no DB, no network.
- Integration: exercise the highest practical public surface (see below).
4. Implement the chosen database strategy
Apply exactly what the user chose in step 2B. For each strategy:
Testcontainers:
- Install
@testcontainers/postgresql (or equivalent)
- Create a
globalSetup file: start container, run migrations, expose DATABASE_URL
- Create a
globalTeardown file: stop container
- Document: Docker required,
DATABASE_URL injected automatically
Docker Compose:
- Create
docker-compose.test.yml with isolated Postgres service
- Create
globalSetup: docker compose -f docker-compose.test.yml up -d, wait for health, run migrations
- Create
globalTeardown: docker compose -f docker-compose.test.yml down
- Document: Docker required, run
pnpm test:integration
Test transactions:
- Wrap each test in a transaction, rollback after
- No container needed
- Document: no setup required, works against any DB URL
Branch/separate DB:
- Add
.env.test to .gitignore
- Document: user must provide real
DATABASE_URL in .env.test
- Never commit real credentials
Skip (fake env only):
- Set fake-but-valid env values in vitest config or setup file
- Make explicit in docs that DB-touching tests are not covered yet
- Add a TODO comment in the integration test file
5. Write one minimal passing unit test
Prove the unit runner works. Prefer testing existing pure logic. Only if none exists, add the smallest reasonable pure helper — and only if it does not distort the architecture.
6. Write one minimal passing integration test
Prove the runtime can load the app, run realistic behavior, and isolate side effects. Target the smallest meaningful boundary:
- backend/API → HTTP request against the app/server handler
- frontend → render a public component/page behavior
- CLI → invoke the command entrypoint
- library → call the public exported API
- monorepo → pick the smallest meaningful app boundary first
If the user chose a real DB strategy (step 2B), the integration test must exercise at least one DB read/write to prove the connection works.
7. Add scripts / commands
Repo must end with clear, named commands future skills cite under ### Required commands in tracker issues. Adapt to the stack — do not assume JS/TS. JS/TS example:
{ "test": "...", "test:unit": "...", "test:integration": "...", "test:watch": "..." }
8. Document
Add or update a short section (README or docs/) on how to run tests locally, including DB setup and required env vars.
9. Run and verify
Run the commands. Finish only when both baseline tests pass. Report the actual output.
Constraints
- Do NOT add E2E infrastructure unless the user explicitly asks.
- Do NOT add CI from scratch unless the user explicitly asks.
- Coverage is not a goal — behavioral confidence is.
Done means
Tooling configured · 1 passing unit test · 1 passing integration test · chosen DB strategy implemented (not skipped unless user said so) · scripts added · docs updated · all commands pass locally · a concise summary of what changed and which commands future agents should use.
