unit-test-guide
Guide for writing excellent unit tests based on "The Art of Unit Testing" principles. Use this skill when: (1) Writing new unit tests, (2) Reviewing test code quality, (3) Refactoring existing tests, (4) Designing testable code, (5) Setting up test structure and organization. Covers test naming (USE pattern), AAA pattern, mocks vs stubs, the three pillars (trustworthiness, maintainability, readability), avoiding test logic, handling async code, and common anti-patterns.
Onweekendd · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Onweekendd/ScreenWright --skill unit-test-guide技能说明
name: unit-test-guide description: | Guide for writing excellent unit tests based on "The Art of Unit Testing" principles. Use this skill when: (1) Writing new unit tests, (2) Reviewing test code quality, (3) Refactoring existing tests, (4) Designing testable code, (5) Setting up test structure and organization. Covers test naming (USE pattern), AAA pattern, mocks vs stubs, the three pillars (trustworthiness, maintainability, readability), avoiding test logic, handling async code, and common anti-patterns.
Unit Test Guide
Guide for writing excellent unit tests based on "The Art of Unit Testing" principles.
Core Concepts
Three Pillars of Good Tests
Every test must have these three properties:
- Trustworthiness - Tests should fail only when there's a real bug. No false positives.
- Maintainability - Tests shouldn't require frequent changes for minor production code updates.
- Readability - Anyone should understand what's being tested just by reading the test.
Entry Points and Exit Points
- Entry Point: The function/method you call to trigger the work unit
- Exit Points (3 types):
- Return value - The function returns something
- State change - Observable state modification
- Third-party call - Calling external dependencies (use mocks)
Test Structure
AAA Pattern (Arrange-Act-Assert)
test('verifyPassword, given failing rule, returns errors', () => {
// Arrange - setup inputs and dependencies
const fakeRule = () => ({ passed: false, reason: 'too short' });
// Act - call the entry point
const errors = verifyPassword('abc', [fakeRule]);
// Assert - check the exit point
expect(errors[0]).toContain('too short');
});
USE Naming Convention
Test names should include three parts:
- Unit under test - What function/class is being tested
- Scenario - The input or condition
- Expected result - The expected behavior
// Good: All three parts present
test('verifyPassword, given failing rule, returns errors', () => {});
// Bad: Missing context
test('it works', () => {});
Structured with describe/it
describe('PasswordVerifier', () => {
describe('with a failing rule', () => {
it('returns errors containing the rule reason', () => {
// test code
});
it('returns exactly one error', () => {
// test code
});
});
});
Mocks vs Stubs
When to Use Each
| Type | Purpose | Verify? |
|---|---|---|
| Stub | Provide fake input data | NO |
| Mock | Verify output interactions | YES |
Key Rules
- Use stubs for input dependencies (data coming IN)
- Use mocks for output dependencies (calls going OUT)
- Only ONE mock per test (testing one requirement)
- Multiple stubs per test is OK
- Never verify calls on stubs - that's implementation detail
// Stub example - fake input
const fakeConfig = { getLogLevel: () => 'info' };
// Mock example - verify output
const mockLogger = { info: jest.fn() };
// ... later
expect(mockLogger.info).toHaveBeenCalledWith('message');
Anti-Patterns to Avoid
1. Logic in Tests
Never use these in tests:
if/elsestatementsfor/whileloopstry/catchblocks- String concatenation in assertions
// BAD - logic duplicates production code
expect(result).toBe("hello" + name);
// GOOD - hardcoded expected value
expect(result).toBe("hello abc");
2. Multiple Asserts on Different Concerns
// BAD - tests multiple things
test('login works', () => {
expect(result.token).toBeDefined();
expect(result.user.name).toBe('John');
expect(loggerMock).toHaveBeenCalled();
});
// GOOD - one concern per test
test('login returns token', () => {
expect(result.token).toBeDefined();
});
3. Overusing beforeEach
Causes "scroll fatigue" - reader must scroll to understand test context.
// BAD - state scattered across beforeEach
describe('tests', () => {
let verifier, errors;
beforeEach(() => { /* setup hidden here */ });
it('does something', () => {
// Where does verifier come from?
});
});
// GOOD - factory functions keep context visible
const makeVerifier = () => new PasswordVerifier();
it('does something', () => {
const verifier = makeVerifier();
// Clear where verifier comes from
});
4. Testing Implementation Details
// BAD - testing internal state
expect(calculator._lastResult).toBe(5);
// GOOD - testing public behavior
expect(calculator.getResult()).toBe(5);
Writing Maintainable Tests
Use Factory Functions
const makeVerifier = () => new PasswordVerifier();
const makeFailingRule = (reason: string) =>
() => ({ passed: false, reason });
const makePassingRule = () =>
() => ({ passed: true, reason: '' });
test('with failing rule, returns error', () => {
const verifier = makeVerifier();
verifier.addRule(makeFailingRule('too short'));
const errors = verifier.verify('abc');
expect(errors[0]).toContain('too short');
});
Use Partial String Matching
// BAD - brittle to formatting changes
expect(error).toBe('Error: password too short');
// GOOD - focuses on essential content
expect(error).toContain('too short');
Parameterized Tests
describe('uppercase rule', () => {
test.each([
['Abc', true],
['aBc', true],
['abc', false],
])('given %s, returns %s', (input, expected) => {
const result = hasUppercase(input);
expect(result).toBe(expected);
});
});
Async Testing
Prefer async/await Over Callbacks
// BAD - callback style, harder to read
test('fetches data', (done) => {
fetchData().then((result) => {
expect(result).toBe('data');
done();
});
});
// GOOD - async/await, follows AAA pattern
test('fetches data', async () => {
const result = await fetchData();
expect(result).toBe('
阅读完整来源 ↗