unit-test-generation — Claude Code prompt for unit tests
The unit-test-generation prompt guides an agent through writing focused unit tests that check behavior and catch plausible bugs. Use it when adding tests to existing code or starting a new test suite.
MIT ★ 521 updated 2026-10-29
.claude/commands/unit-test-generation.mdWhat unit-test-generation does
Before writing tests, the prompt directs the agent to inspect the project’s test locations, naming patterns, frameworks, helpers, and written guidance. For a focused request, it examines the target and direct collaborators; for broader work, it first inventories the requested modules and their public behavior.
Tests should assert concrete outcomes across meaningful branches, boundaries, and interactions. Similar cases can share a parameterized method. The prompt also calls for running the tests and mapping stated requirements to test names. A coverage percentage matters only when the user or repository sets one.
Assertions should expose plausible implementation mistakes, rather than merely confirm that a value exists. For Claude Code, place the prompt at .claude/commands/unit-test-generation.md. The prompt is also listed for Cursor and Codex.
What it helps with
- cover meaningful branches and boundary values in a target
- combine similar test cases through parameterization
- map each stated requirement to a generated test
- replace weak assertions that would survive plausible bugs
Example prompts for the agent
- Write unit tests for
OrderServiceusing this project’s conventions, then run them. - Add parameterized tests for boundary behavior in
PriceCalculator. - Check that every requested behavior maps to a test, and strengthen assertions that would miss plausible bugs.
How to install unit-test-generation
Manually: put the files in place
.claude/commands/unit-test-generation.mdHow to use
Paste the text at the start of a chat or into project instructions
Questions about unit-test-generation
How do I install unit-test-generation in Claude Code?
Place the prompt file at .claude/commands/unit-test-generation.md.
What does unit-test-generation do?
It guides an agent to inspect project testing conventions and write unit tests for concrete behavior. It also asks the agent to run the tests and connect task requirements to test names.
How does the prompt handle parameterized tests?
It recommends grouping related input cases in parameterized tests instead of repeating the same test logic. Distinct public behaviors and boundaries still need their own coverage.
Source text
unit-test-generation.prompt.md · MIT
---
description: >-
Best practices for generating proportional, behavior-focused,
parameterized unit tests across programming languages
---
# Unit Test Generation Prompt
You are an expert code generation assistant specialized in writing concise,
effective unit tests. Analyze the requested source scope, identify meaningful
behavior partitions and plausible bugs, and produce minimal, buildable tests.
Treat a coverage percentage as a requirement only when the user or repository
specifies one; do not chase an arbitrary 80% target.
## Discover and Follow Conventions
Before generating tests, analyze the codebase to understand existing conventions:
- **Location**: Where test projects and test files are placed
- **Naming**: Namespace, class, and method naming patterns
- **Frameworks**: Testing, mocking, and assertion frameworks used
- **Harnesses**: Preexisting setups, base classes, or testing utilities
- **Guidelines**: Testing or coding guidelines in instruction files, README, or docs
If you identify a strong pattern, follow it unless the user explicitly requests otherwise. If no pattern exists and there's no user guidance, use your best judgment.
## Test Generation Requirements
Generate concise, parameterized, and effective unit tests using discovered conventions.
- **Prefer mocking** over generating one-off testing types
- **Prefer unit tests** over integration tests, unless integration tests are clearly needed and can run locally
- **Focused scope**: inspect the named target, its direct collaborators, and one
representative neighboring test for conventions
- **Broad scope**: inventory the requested modules first, then cover their
non-trivial public behavior without reading unrelated code. A module or layer
name is an inventory heading, not one test requirement: enumerate its public
operations and distinct validation, boundary, branch, interaction, and state
behavior before deciding it is covered
- Stop only when every requested behavior and distinct observable partition
has a mutation-relevant assertion and any requested coverage target is met
### Key Testing Goals
| Goal | Description |
| ----------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Minimal but Comprehensive** | Avoid redundant tests |
| **Logical Coverage** | Focus on meaningful edge cases, domain-specific inputs, boundary values, and bug-revealing scenarios |
| **Core Logic Focus** | Test positive cases and actual execution logic; avoid low-value tests for language features |
| **Balanced Coverage** | Don't let negative/edge cases outnumber tests of actual logic |
| **Best Practices** | Use Arrange-Act-Assert pattern and proper naming (`Method_Condition_ExpectedResult`) |
| **Buildable & Complete** | Tests must compile, run, and contain no hallucinated or missed logic |
## Quality over Quantity
When the task specifies particular test scenarios or behaviors to cover:
1. **Cover every stated requirement first** — each bullet point or scenario in the task description should map to at least one test
2. **Test the actual implementation** — read the source code to understand return values, side effects, and error conditions before writing assertions
3. **Keep focused suites concise without shrinking broad suites** — for one
function, 5 tests that thoroughly exercise its distinct behavior beat 20
shallow tests. For broad/comprehensive work, do not optimize for fewer tests:
combine only equivalent sibling inputs, never separate public behaviors,
validation paths, boundaries, or state transitions merely because coverage
already passes
4. **Every test must pass** — run tests after writing them; fix immediately if they fail
5. **Make completion auditable** — before finishing, cite at least one generated
test name for every explicit behavioral requirement. For scaffolding, scope,
commands, and coverage requirements, cite the relevant file or artifact.
Passing coverage is not completion when a requested mock seam, boundary,
transition, or property combination has no mapped test.
## Write Tests That Pin Down Behavior
A test that passes coincidentally gives a false signal. Beyond covering code, every test must *pin down behavior* — it should fail under a plausible bug. These principles are language-agnostic (MSTest, xUnit, NUnit, pytest, Jest, Go `testing`, JUnit, RSpec, ...):
- **Mutation thinking** — each assertion should fail under at least one plausible mutation (`>`→`>=`, `&&`→`||`, a dropped null/`None`/`nil` check, an off-by-one, returning the input unchanged). If it survives every mutation, replace weak checks (`IsNotNull`/`toBeDefined`) with a concrete expected value.
- **No tautologies** — do not compare a value with itself or derive the expected
value from the actual result. A write/read assertion is valid when persistence
or round-tripping is the contract and the expected value is independently
specified.
- **Property intersections** — when code handles independent properties (quoted/unquoted, ASCII/escaped, present/absent), add at least one test combining several at once. Bugs live at intersections, not on single axes.
- **Behavior radius** — assert a secondary observable only when it is part of the
public contract or required to prove the requested interaction; do not couple
every test to incidental state, logs, or call counts.
- **Fixture realism** — never set the parameter under test to a degenerate value (scroll with `scrollback=0`, eviction with `capacity=1`, retries with `maxRetries=0`, ordering with a single element).
Quick self-review before finishing a test: would emptying the function body make it fail? If not, the assertions are too weak.
## Parameterization
- Prefer parameterized tests (e.g., `[DataRow]`, `[Theory]`, `@pytest.mark.parametrize`) over multiple similar methods
- Combine logically related test cases into a single parameterized method
- Never generate multiple tests with identical logic that differ only by input values
## Report-safe test names and result validation
Apply this contract to both direct generation and delegated implementation or
validation, even when the caller supplies its own test style.
- **Separate metadata from data.** Give each case a stable, descriptive,
distinguishable ID/display name. Prefer an explicit safe `Name`/`Case` field;
a case index plus a short behavior label also works. Do not interpolate
arbitrary input, expected values, or output into test or suite names.
- Keep raw control characters, isolated UTF-16 surrogates, binary values, and
huge strings out of names. If an identifier needs an escaped value, use a
short literal backslash-u label such as `\u000C` (six printable characters),
not the actual control character. Normal Unicode labels and harmless numeric
interpolation are fine.
- Check framework-managed parameterized labels too: when automatic argument
rendering would expose unsafe data, use the framework's explicit case-ID or
display-name API (for example, pytest `ids` or MSTest `DisplayName`) rather
than assuming the runner/reporter escapes it safely.
- **Preserve the case.** Control characters and malformed strings are legitimate
test data. Fix unsafe metadata, not production values or expectations; never
sanitize the tested data, weaken assertions, or skip/remove edge cases to make
a report export succeed.
Before claiming tests passed:
1. Use the repository/CI configured runner and reporter at the narrowest scope
covering the change. Preserve the runner exit code through wrappers/pipelines;
a successful log-filter command is not a successful test run.
2. When result artifacts are required or configured, run the real report-export
path and parse the artifacts from that run with the existing consumer or an
appropriate format parser (for example, an XML parser for JUnit/TRX).
Console-green alone is insufficient if required export failed.
3. Confirm nonzero expected discovery and account for every discovered case's
pass/skip/failure outcome, including setup failures or incomplete execution.
Reject missing, empty, invalid, stale, or partial required artifacts; do not
infer success from an empty report or a summary that omits failures.
4. Report runner, export, and parsing failures explicitly with the command,
exit code, artifact path, and diagnostic; keep completion blocked until
required validation succeeds. Do not add reporter dependencies, a new report
format, coverage collection, or a full-suite rerun merely for naming checks
when reporting is not configured.
## Analysis Before Generation
Do this analysis privately; do not emit a plan or inventory unless the user
requested one. For focused work, stop gathering context once the target
behavior, expected results, dependencies, and local test conventions are known.
For broad work, inventory manifests and symbols first, batch independent file
reads where tools allow, and stop when every requested target has a test
location and behavior checklist.
Before writing tests:
1. **Analyze** the code line by line to understand what each section does
2. **Document** all parameters, their purposes, constraints, and valid/invalid ranges
3. **Identify** potential edge cases and error conditions
4. **Describe** expected behavior under different input conditions
5. **Note** dependencies that need mocking
6. **Consider** concurrency, resource management, or special conditions
7. **Identify** domain-specific validation or business rules
Apply this analysis to the requested scope, not adjacent modules.
## Coverage Types
| Type | Examples |
| --------------------- | ------------------------------------------------------------------- |
| **Happy Path** | Valid inputs produce expected outputs |
| **Edge Cases** | Empty values, boundaries, special characters, zero/negative numbers |
| **Error Cases** | Invalid inputs, null handling, exceptions, timeouts |
| **State Transitions** | Before/after operations, initialization, cleanup |
## Language-Specific Examples
### C# (MSTest)
```csharp
[TestClass]
public sealed class CalculatorTests
{
private readonly Calculator _sut = new();
[TestMethod]
[DataRow(2, 3, 5, DisplayName = "Positive numbers")]
[DataRow(-1, 1, 0, DisplayName = "Negative and positive")]
[DataRow(0, 0, 0, DisplayName = "Zeros")]
public void Add_ValidInputs_ReturnsSum(int a, int b, int expected)
{
// Act
var result = _sut.Add(a, b);
// Assert
Assert.AreEqual(expected, result);
}
[TestMethod]
public void Divide_ByZero_ThrowsDivideByZeroException()
{
// Act & Assert
Assert.ThrowsException<DivideByZeroException>(() => _sut.Divide(10, 0));
}
}
```
### TypeScript (Jest)
```typescript
describe("Calculator", () => {
let sut: Calculator;
beforeEach(() => {
sut = new Calculator();
});
it.each([
[2, 3, 5],
[-1, 1, 0],
[0, 0, 0],
])("add(%i, %i) returns %i", (a, b, expected) => {
expect(sut.add(a, b)).toBe(expected);
});
it("divide by zero throws error", () => {
expect(() => sut.divide(10, 0)).toThrow("Division by zero");
});
});
```
### Python (pytest)
```python
import pytest
from calculator import Calculator
class TestCalculator:
@pytest.fixture
def sut(self):
return Calculator()
@pytest.mark.parametrize("a,b,expected", [
(2, 3, 5),
(-1, 1, 0),
(0, 0, 0),
])
def test_add_valid_inputs_returns_sum(self, sut, a, b, expected):
assert sut.add(a, b) == expected
def test_divide_by_zero_raises_error(self, sut):
with pytest.raises(ZeroDivisionError):
sut.divide(10, 0)
```
## Output Requirements
- Tests must be **complete and buildable** with no placeholder code
- Follow the **exact conventions** discovered in the target codebase
- Include **appropriate imports** and setup code
- Add **brief comments** explaining non-obvious test purposes
- Place tests in the **correct location** following project structure
## Build and Verification
- **Scoped builds during development**: Build the specific test project during implementation for faster iteration
- **Final validation**: Run the narrowest command that compiles and executes the
changed tests. Add a solution/workspace command only for broad work, when the
repository contract requires it, or when the change can affect other projects.
- **API signature verification**: Before calling any method in test code, verify the exact parameter types, count, and order by reading the source code
- **Project reference validation**: Before writing test code, verify the test project references all source projects the tests will use. Read the matching language file relative to the supplied `code-testing-extensions` catalog (e.g., `dotnet.md` for .NET); do not invoke the reference-only catalog.
## Test Scope Guidelines
- **Write unit tests, not integration/acceptance tests**: Focus on testing individual classes and methods with mocked dependencies
- **No external dependencies**: Never write tests that call external URLs, bind to network ports, require service discovery, or depend on precise timing
- **Mock everything external**: HTTP clients, database connections, file systems, network endpoints — all should be mocked in unit tests
- **Fix assertions, not production code**: When tests fail, read the production code, understand its actual behavior, and update the test assertion
© managedcode · MIT · managedcode/dotnet-skills