Skip to content
Skills Library
Programming · Testing

write-clean-tests

/write-clean-tests

Use when writing or reviewing tests — F.I.R.S.T. properties, one concept per test, state coverage not line coverage, and a regression test for every bug fix.

Licence
MIT
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when writing or reviewing tests — F.I.R.S.T. properties, one concept per test, state coverage not line coverage, and a regression test for every bug fix.

Original author description

Use when writing or reviewing tests — F.I.R.S.T. properties, one concept per test, state coverage not line coverage, and a regression test for every bug fix.

How it works

  1. F.I.R.S.T.
  2. 1. Audit (change nothing)
  3. 2. One concept per test
  4. 3. State coverage over line coverage
  5. 4. A regression test for every fix
  6. Verify
  7. When to deviate
Original SKILL.md headings · 56 lines, 446 words
SKILL.md preview
---
name: write-clean-tests
description: Use when writing or reviewing tests — F.I.R.S.T. properties, one concept per test, state coverage not line coverage, and a regression test for every bug fix.
---

# Write Clean Tests

Tests are first-class code: they must be as readable as production and must fail for the right reason.
Production testing boundary is set by [engineering-principles.md](../../core/_shared/engineering-principles.md).

## F.I.R.S.T.

- **Fast** — a slow suite stops being run. Keep unit tests in memory; push the slow ones out of the unit layer.
- **Independent** — one test must not depend on another's order or state; run them in any order.
- **Repeatable** — same result in any environment; no flakiness from time, network or shared state.
- **Self-validating** — a boolean pass/fail, never a human reading the output.
- **Timely** — written just before or with the production code, not weeks later.

## 1. Audit (change nothing)

```bash
cat .claude/stack-profile.md 2>/dev/null | head -20
find . \( -name "*_test.*" -o -name "*_spec.*" -o -name "*.test.*" -o -name "*.spec.*" -o -name "*Test.*" -o -name "*Tests.*" -o -name "test_*.*" -o -path "*__tests__*" \) 2>/dev/null | head -20
```

Read the tests for three failures: tests that mirror the implementation (they break on every refactor and
catch nothing), tests with several unrelated asserts (one failure hides another), and tests that assert
internals instead of behaviour.

## 2. One concept per test

- One assert per behaviour, one concept per test. A test named "it works" asserts nothing; name it
  "returns zero when the list is empty".
- Test the public behaviour, not the private shape. A test coupled to internals fails when the code
  improves.
- Use the arrange/act/assert shape; keep the arrange minimal so the reader sees the one thing under test.

## 3. State coverage over line coverage

- Cover the *states and transitions that pay* (the boundary conditions, the error paths, the money path),
  not a percentage. A line covered is not a bug caught.
- Saboteur-test the tests: break the production code and confirm a test fails — a test that cannot fail
  tests nothing.

## 4. A regression test for every fix

- A bug is a missing test. Write the test that fails on the old code, then the fix — the test is the proof
  the bug cannot return.
- Use real data (and a synthetic edge case) over an exhaustive mock of reality.

## Verify

`pnpm test` (or the profile's runner) is green, each test states one behaviour, and breaking the code
under test fails exactly one test with a message that names the cause. State the new coverage in the note.

## When to deviate

- A prototype with a one-week life: a couple of smoke tests, not a full suite.
- A bug cheap to fix and loud (an internal dashboard): a thin regression test is enough.

Versions

The database has no other skills named write-clean-tests.

Database snapshot: 13.11.2026 · package version cb200304b3d9 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 86write-tests
    Use when the user asks to write, add or extend tests for some code (unit tests, regression test for a bug, coverage of a new feature).
  • 90write-tests
    Write unit or integration tests for a function, module, endpoint or bug fix, in the project's existing test framework. Use when the user says "add tests", "write tests for this", "increase coverage", "test this bug fix", or "why isn't this tested".
  • 100write-tests
    Write or review unit tests for code in this repo. Use when writing new tests, reviewing existing tests, or adding test coverage.
  • 100mobiai-write-tests
    Use when the user asks to write tests for mobile code, or after applying a fix that needs regression tests.
  • 90test-writer
    Write test code. 100% coverage, SSR tests, edge cases. Use when writing tests, adding test coverage.
  • 100unit-tests
    Write or review unit tests through exported behavior. Use for new tests, bug-fix regression tests, coverage, replacing brittle implementation checks, or a test that went red because behaviour changed on purpose.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.