setup-testing

---
name: setup-testing
description: Seeds unit tests in a project that has none — installs the recommended framework for the stack, writes a real test in an existing module, wires the `test` script, and runs until green. Use when the project has no tests, when asked to "configure tests", "setup tests", "add tests", or "create test suite".
---

# Setup unit testing

Seeds unit test infrastructure and proves it runs. **Never claim green without having run it and seen the output.**

## 1. Determine the framework

Read the recommended framework in `CLAUDE.md` (line "recommended: ..."). If absent, use the table for the detected stack. **Confirm with the user** — they may choose an alternative.

| Stack | Framework | Install | Config |
| --- | --- | --- | --- |
| JS/TS + React/Next | Vitest + Testing Library + jsdom | `npm i -D vitest @testing-library/react @testing-library/jest-dom jsdom` (use project PM) | `vitest.config.ts` |
| JS/TS + Vue/Nuxt | Vitest + @vue/test-utils + jsdom | `npm i -D vitest @vue/test-utils jsdom` | `vitest.config.ts` |
| JS/TS + Vite | Vitest | `npm i -D vitest` | `vitest.config.ts` |
| JS/TS Node only | node:test | — (native since Node 18) | — |
| PHP + Laravel | Pest | `composer require --dev pestphp/pest && php artisan pest:install` | Pest scaffold |
| PHP other | PHPUnit | `composer require --dev phpunit/phpunit` | `phpunit.xml` |
| Python | pytest (+ pytest-django / pytest-asyncio / httpx) | `pip install -U pytest ...` | `pytest.ini` |
| Go | testing (stdlib) | — | — |
| Rust | `#[test]` | — | — |
| JVM Spring Boot | JUnit 5 (spring-boot-starter-test) | usually already included — check `pom.xml`/`build.gradle` | — |
| JVM Quarkus | JUnit 5 + @QuarkusTest | usually already included — check | — |
| JVM generic | JUnit 5 | add `org.junit.jupiter:junit-jupiter` to build file | — |
| .NET | xUnit | `dotnet add package xunit xunit.runner.visualstudio Microsoft.NET.Test.Sdk` | — |

## 2. Install (if needed)

For non-native frameworks: **confirm with the user before running the install** (machine action). Run the install command. If built-in (Go, Rust, node:test), skip this step.

## 3. Write the config file

Write the config file adapted to the real project: correct paths, ESM/CJS as the project uses, `environment: jsdom` for UI components. Do not use generic configuration — read the project structure first.

## 4. Write 1 REAL test

Choose **one pure/deterministic existing module** (util, helper, domain function — few imports, no IO/network/DB). Read the code, understand the behavior, and write 1 genuine unit test covering the happy path + 1 edge case.

- If no suitable module exists, write a minimal smoke test (guaranteed floor) and **explicitly tell the user** it is a placeholder to be replaced.

## 5. Wire the test script

Ensure the test script is declared in the project manifest (`package.json` `"test"`, `composer.json` `"scripts"."test"`, `Makefile` `test:`, etc.). Do not duplicate if it already exists.

## 6. Run until green

Run the test command. Fix config, path, and import errors until the output shows green. **Show the real output** (pass/fail count) to the user. If installation fails (network/permission), report the exact command for the user to run manually and do **not** claim green.

## 7. Update CLAUDE.md

After confirmed green output, in the project's `CLAUDE.md`:

1. **Remove** the warning line generated by the harness (and the blank line immediately after):

   ```markdown
   > No unit tests yet — recommended: **...**. Run `/setup-testing` to seed.
   ```

2. **Add** immediately below the `## Canonical commands` block a note about the configured test stack and the coverage rule:

   ```markdown
   > **Tests:** `{framework}` — run `{test-command}`. Test what can break (business rules, branching logic, bug regressions); skip trivial/presentational code. Rubric: `.claude/rules/05-testing.md`.
   ```

   Replace `{framework}` and `{test-command}` with the actual project values.

## 8. Report

Summarize what was done: framework installed, config file created, test file created, green output. Remind the user to review the generated test and expand coverage for real project cases.