Test

Test Generator — Framework-Aware Test Scaffolding

You are generating and optionally running tests for source files in the current project, matching the project's existing test framework and conventions.

Arguments

$ARGUMENTS may contain any combination of:

Step 1: Identify Target Files

Determine which files to generate tests for:

1. Explicit path in $ARGUMENTS — use the specified file(s).
2. No path specified — auto-detect from recent changes:
   • Run git diff --name-only HEAD for unstaged changes
   • Run git diff --name-only --cached for staged changes
   • Filter to source files only (exclude tests, configs, lockfiles, docs)
3. If no changes are found and no path was given, tell the user to specify a file and stop.

Read each target file in full using the Read tool.

Step 2: Detect Test Framework

Check project configuration files to determine the test framework:

If --framework was specified, use that instead of auto-detection.

If no framework is detected, infer from the target file's language:

• Python -> pytest
• JavaScript/TypeScript -> Jest
• Go -> Go testing
• Rust -> Rust built-in tests

Step 3: Learn Project Test Conventions

Read 2-3 existing test files to extract patterns:

1. Find existing tests — search for files matching common test patterns:
   • test_*.py, *_test.py, tests/, __tests__/
   • *.test.ts, *.spec.ts, *.test.js, *.spec.js
   • *_test.go
   • tests/ directory in Rust crates
2. Extract patterns from existing tests:
   • Naming: test_<function>, describe/it blocks, Test<Struct> functions
   • File location: colocated (src/foo.test.ts) vs separate directory (tests/test_foo.py)
   • Imports: how the project imports test utilities, fixtures, mocks
   • Assertion style: assert, expect(), assertEqual, custom matchers
   • Setup/teardown: fixtures, beforeEach, setUp, test helpers
   • Mocking: how external dependencies are mocked (mock libraries, dependency injection, test doubles)
3. If no existing tests are found, use the framework's standard conventions.

Step 4: Determine Test File Path

Follow the project's existing convention for test file placement:

If --update was specified, find and use the existing test file for this source file.

Step 5: Analyze Target Code

For each target file, identify what to test:

1. Public API — exported functions, classes, methods, types
2. Branching logic — if/else, match/switch, early returns, guard clauses
3. Error paths — try/catch, Result/Option handling, error returns, validation failures
4. Edge cases — empty inputs, boundary values, nil/null/undefined, zero, negative numbers, empty collections
5. Side effects — database calls, network requests, file I/O, environment variable reads (these need mocking)

If --coverage was specified:

1. Read the existing test file for this source
2. Identify which public functions already have tests
3. Only generate tests for untested functions

Step 6: Generate Tests

Write tests following these principles:

Structure

• One test per behavior — each test verifies a single logical behavior, not a single function
• Arrange-Act-Assert — clear separation of setup, execution, and verification
• Descriptive names — test names describe the scenario and expected outcome, e.g., test_parse_returns_none_for_empty_input

What to Test

• Happy path with typical inputs
• Edge cases identified in Step 5
• Error paths and validation failures
• Boundary conditions (empty, single element, max values)
• Return values AND side effects where relevant

What NOT to Test

• Private/internal functions directly (test through public API)
• Third-party library behavior
• Trivial getters/setters with no logic
• Implementation details that could change without affecting behavior

Mocking

• Mock external dependencies only (network, database, filesystem, time)
• Do NOT mock the code under test
• Use the project's existing mock patterns (from Step 3)
• Prefer dependency injection over monkey-patching when possible

Test Quality

• Tests should fail for the right reasons — a test that never fails is useless
• Avoid brittle assertions on exact strings, timestamps, or ordering unless order is part of the contract
• Use factory functions or fixtures for complex test data instead of inline object literals

Step 7: Write Test File

Creating a new test file:

Use the Write tool. Include all necessary imports, fixtures, and the generated tests.

Updating an existing test file (--update):

Use the Edit tool. Add new test functions after the existing ones, maintaining the file's import style and organization.

After writing, show a summary:

## Tests Generated

| Source File | Test File | Tests Added |
|-------------|-----------|-------------|
| `path/to/source.py` | `tests/test_source.py` | 8 |

### Test Inventory
- `test_function_a_returns_expected_output` — happy path
- `test_function_a_raises_on_empty_input` — edge case
- `test_function_b_handles_network_error` — error path
...

Step 8: Run Tests (if --run)

If --run was specified in $ARGUMENTS:

1. Execute tests using the detected framework:

   • pytest: pytest path/to/test_file.py -v
   • Jest: npx jest path/to/test_file --verbose
   • Vitest: npx vitest run path/to/test_file --reporter=verbose
   • Go: go test ./path/to/package/ -v -run TestName
   • Cargo: cargo test test_module_name -- --nocapture
   • Mocha: npx mocha path/to/test_file
   • RSpec: bundle exec rspec path/to/spec_file

2. If tests fail, analyze the failure:

   • Test-side bug (wrong assertion, missing mock, import error) — fix the test and retry. Up to 3 retries.
   • Source-side bug (the test correctly caught a real bug) — report it to the user, do NOT modify the source code. Format as:

     ## Source Bug Detected
     
     **File:** `path/to/source.py:42`
     **Test:** `test_function_a_raises_on_empty_input`
     **Issue:** [Description of the bug the test revealed]
     

3. After tests pass (or after 3 failed retries), show results:

   ## Test Results
   
   Passed: N
   Failed: N
   Skipped: N
   Total:  N
   

Composability

After generating tests, suggest next steps:

• "Run /commit to commit the new tests."
• If source bugs were found: "Consider running /review on the source file to investigate further."
• If --run wasn't used: "Add --run to execute the tests and verify they pass."

Edge Cases

• No test framework detected and no --framework: Default based on language. If the language is ambiguous, ask the user which framework to use.
• Target file is already a test file: Tell the user and stop. Don't generate tests for tests.
• Target file doesn't exist: Tell the user the file wasn't found and stop.
• Generated file has no public API: Warn the user there's nothing to test publicly. Offer to test internal functions if the user confirms.
• Rust inline tests: When the convention is inline #[cfg(test)] modules, use Edit to append the test module to the source file instead of creating a separate file.
• Monorepo: If the project has multiple packages (workspace), detect and use the correct package's test config.