unit-test_skill

Overview

This skill provides concise guidelines for writing and reviewing unit tests focused on clarity, determinism, and reviewer responsibilities. It codifies the AAA pattern, meaningful naming, mocking strategies, and anti-patterns to prevent flaky or brittle tests. Use it to raise the quality and trustworthiness of test suites when adding, changing, or reviewing *.test.* files.

How this skill works

The skill inspects test code for structure and practices: it verifies Arrange-Act-Assert organization, checks that each test targets a single behavior, and flags weak assertions or reliance on global state. It looks for determinism controls like time/randomness mocking and warns about testing implementation details. For PR reviews, it guides reviewers on validating that tests fail when the system under test is broken and on choosing correct matchers.

When to use it

• When writing new unit tests for any module or component
• When reviewing PRs that add or modify *.test.* files
• When refactoring tests to improve clarity, isolation, or coverage
• When diagnosing flaky tests or intermittent CI failures
• When establishing or enforcing team testing conventions

Best practices

• Follow AAA (Arrange, Act, Assert) in every test for readability
• Give tests meaningful names that describe expected behavior, not implementation
• Test one behavior per test and isolate tests from each other
• Mock time, randomness, and external systems to ensure determinism
• Use precise matchers; avoid weak assertions like toBeTruthy or toBeDefined

Example use cases

• Adding unit tests for a new utility function and ensuring names describe outcomes
• Reviewing a test PR and rejecting tests that rely on real time or global state
• Refactoring a brittle test suite by introducing jest.useFakeTimers and deterministic mocks
• Validating that a failing code change also causes related tests to fail (test the test)
• Replacing weak matchers with explicit assertions to increase test signal