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

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

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

Full Compiled Document

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

testing-best-practices