writing-tests_skill

Overview

This skill teaches principles for writing effective, maintainable tests that catch bugs and document expected behavior. It focuses on outcome-oriented naming, strong assertions, single-concept tests, and systematic edge-case coverage. The guidance is practical and actionable for Python projects and test reviews.

How this skill works

The skill inspects test names, assertions, and structure to ensure they describe outcomes and verify specific values. It recommends one concept per test, matching assertions to titles, and avoiding implementation coupling. It provides comprehensive edge-case checklists (numbers, strings, collections, dates, null/undefined, domain constraints) to broaden coverage and surface clustered bugs.

When to use it

• Writing new tests or expanding coverage
• During TDD RED phase to create clear failing tests
• Reviewing or refactoring existing tests
• Deciding test names and assertion strategies
• Investigating a discovered bug to add regression tests

Best practices

• Name tests as specifications: "[outcome] when [condition]" (e.g., "returns empty list when input is null").
• Assert exact expected values instead of broad truthy/defined checks; match assertions to the test title.
• Test only one behavior per test; split tests if you need an "and" in the title.
• Avoid asserting implementation details (mocks, query strings); assert observable behavior instead.
• When a bug appears, add related tests for similar inputs, other endpoints, and shared developer assumptions.
• Use the provided edge-case checklist for numbers, strings, collections, dates, nulls, and domain constraints before declaring a function covered.

Example use cases

• Add a failing test in TDD: name it as the expected outcome and assert the precise value to drive implementation.
• Review a pull request: rewrite vague test names to read like specifications and strengthen weak assertions.
• When a bug is reported (e.g., off-by-one), add tests for boundaries and related functions to catch clustered issues.
• Design tests for input parsing: cover empty, whitespace, unicode, and injection patterns from the strings checklist.
• Validate date handling: add tests for leap days, DST transitions, time zone boundaries, and epoch extremes.