testing-best-practices

name	testing-best-practices
description	Unit testing, integration testing, and test-driven development principles. Use when writing tests, reviewing test code, improving test coverage, or setting up testing strategy. Triggers on "write tests", "review tests", "testing best practices", or "TDD".
license	MIT
metadata	{"author":"agent-skills","version":"2.0.0"}

Testing Best Practices

Unit testing, integration testing, and TDD principles for reliable, maintainable test suites. Contains 34 rules across 7 categories using TypeScript with Jest/Vitest.

Metadata

• Version: 2.0.0
• Rule Count: 34 rules across 7 categories
• License: MIT

When to Apply

Reference these guidelines when:

• Writing unit or integration tests
• Reviewing test code quality
• Improving test coverage strategy
• Setting up testing infrastructure
• Debugging flaky or slow tests

Test Expansion Discipline

• For bug fixes, start with the narrowest failing regression test before changing production code.
• When asked for "more tests" or "more coverage", target a real branch, edge case, or defect-prone path instead of optimizing for the headline percentage first.
• Set up only the dependencies the code under test actually touches.
• Follow the nearest existing repository test style before introducing a new test pattern.
• Prefer small local test doubles or inline collaborators when they keep the setup obvious and avoid unnecessary fixture sprawl.

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Test Structure	CRITICAL	struct-
2	Test Isolation	CRITICAL	iso-
3	Assertions	HIGH	assert-
4	Test Data	HIGH	data-
5	Mocking	MEDIUM	mock-
6	Coverage	MEDIUM	cov-
7	Performance	LOW	perf-

Quick Reference

1. Test Structure (CRITICAL)

• struct-aaa-pattern - Arrange, Act, Assert pattern
• struct-descriptive-names - Descriptive test names
• struct-one-assertion - One logical assertion per test
• struct-describe-it - Organized test suites with describe/it
• struct-given-when-then - BDD style when appropriate
• struct-setup-teardown - Proper setup and teardown

2. Test Isolation (CRITICAL)

• iso-independent-tests - Tests run independently
• iso-no-shared-state - No shared mutable state
• iso-deterministic - Same result every run
• iso-no-order-dependency - Run in any order
• iso-cleanup - Clean up after tests
• iso-test-doubles - Strategic use of test doubles

3. Assertions (HIGH)

• assert-specific - Use specific assertions
• assert-meaningful-messages - Helpful failure messages
• assert-expected-actual - Expected value first
• assert-no-magic-numbers - Use named constants
• assert-custom-matchers - Custom matchers for domain logic

4. Test Data (HIGH)

• data-factories - Use factories for test data
• data-builders - Builder pattern for complex objects
• data-faker - Generate realistic fake data
• data-minimal - Minimal test data
• data-realistic - Realistic edge cases
• data-fixtures - Manage test fixtures

5. Mocking (MEDIUM)

• mock-boundaries - Mock only at boundaries
• mock-verify-interactions - Verify important mock calls
• mock-minimal - Don't over-mock
• mock-realistic - Realistic mock behavior with MSW

6. Coverage (MEDIUM)

• cov-meaningful - Focus on meaningful coverage
• cov-edge-cases - Cover edge cases and boundary values
• cov-unhappy-paths - Test error scenarios
• cov-not-100-percent - 100% coverage isn't the goal

7. Performance (LOW)

• perf-fast-unit - Keep unit tests fast (<50ms each)
• perf-parallel - Run tests in parallel
• perf-test-organization - Organize tests for fast feedback

Essential Guidelines

Regression-First Bug Fixes

// Prefer this sequence:
// 1. isolate the bug in the smallest failing test
// 2. confirm it fails for the right reason
// 3. change production code
// 4. rerun the same test until it passes
// 5. widen validation only if the change touches shared behavior

AAA Pattern (Arrange, Act, Assert)

it('calculates total with discount', () => {
  // Arrange
  const cart = new ShoppingCart();
  cart.addItem({ name: 'Book', price: 20 });
  cart.applyDiscount(0.1);

  // Act
  const total = cart.getTotal();

  // Assert
  expect(total).toBe(18);
});

Descriptive Test Names

// ✅ Describes behavior and scenario
describe('UserService.register', () => {
  it('creates user with hashed password', () => {});
  it('throws ValidationError when email is invalid', () => {});
  it('sends welcome email after successful registration', () => {});
});

Test Isolation

// ✅ Each test sets up its own data
beforeEach(() => {
  mockRepository = { save: vi.fn(), find: vi.fn() };
  service = new OrderService(mockRepository);
});

How to Use

Read individual rule files for detailed explanations:

rules/struct-aaa-pattern.md
rules/iso-independent-tests.md
rules/mock-boundaries.md
rules/cov-meaningful.md

References

• Vitest Documentation
• Jest Documentation
• Testing Library
• MSW (Mock Service Worker)

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md