Testing Best Practices

Unit testing, integration testing, and TDD principles for reliable, maintainable test suites. Guidelines for writing effective tests that provide confidence and documentation.

When to Apply

Reference these guidelines when:

• Writing unit tests
• Writing integration tests
• Reviewing test code
• Improving test coverage
• Setting up testing strategy

Rule Categories by Priority

Quick Reference

1. Test Structure (CRITICAL)

• struct-aaa – Arrange, Act, Assert pattern
• struct-naming – Descriptive test names
• struct-one-assert – One logical assertion per test
• struct-describe-it – Organized test suites
• struct-given-when-then – BDD style when appropriate

2. Test Isolation (CRITICAL)

• iso-independent – 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

3. Assertions (HIGH)

• assert-specific – Specific assertions
• assert-meaningful-messages – Helpful failure messages
• assert-expected-first – Expected value first
• assert-no-magic-numbers – Use named constants

4. Test Data (HIGH)

• data-factories – Use factories/builders
• data-minimal – Minimal test data
• data-realistic – Realistic edge cases
• data-fixtures – Manage test fixtures

5. Mocking (MEDIUM)

• mock-only-boundaries – Mock at boundaries
• mock-verify-interactions – Verify important calls
• mock-minimal – Don’t over-mock
• mock-realistic – Realistic mock behavior

6. Coverage (MEDIUM)

• cov-meaningful – Focus on meaningful coverage
• cov-edge-cases – Cover edge cases
• cov-unhappy-paths – Test error scenarios
• cov-not-100-percent – 100% isn’t the goal

7. Performance (LOW)

• perf-fast-unit – Unit tests run fast
• perf-slow-integration – Integration tests can be slower
• perf-parallel – Run tests in parallel

Essential Guidelines

For detailed examples, see the rule files in the rules/ directory.

AAA Pattern (Arrange, Act, Assert)

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

  // Act - execute the code under test
  const total = cart.getTotal();

  // Assert - verify the result
  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', () => {});
});

// ❌ Vague names
it('test1', () => {});
it('should work', () => {});

Test Isolation

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

// ❌ Shared state between tests
let globalOrder: Order; // Tests depend on each other

Test Pyramid

        /\
       /  \      E2E Tests (few)
      /----\     - Test critical user flows
     /      \    - Slow, expensive
    /--------\   Integration Tests (some)
   /          \  - Test component interactions
  /------------\ - Database, API calls
 /              \ Unit Tests (many)
/----------------\ - Fast, isolated
                   - Test single units

Output Format

When reviewing tests, output findings:

file:line - [category] Description of issue

Example:

tests/user.test.ts:15 - [struct] Missing Arrange/Act/Assert separation
tests/order.test.ts:42 - [iso] Test depends on previous test's state
tests/cart.test.ts:28 - [assert] Multiple unrelated assertions in one test

How to Use

Read individual rule files for detailed explanations:

rules/struct-aaa-pattern.md
rules/iso-independent-tests.md
rules/data-factories.md

References

This skill is built on testing best practices from:

• Jest: https://jestjs.io
• Vitest: https://vitest.dev
• Testing Library: https://testing-library.com
• Kent C. Dodds’ testing principles
• TDD by Kent Beck
• Working Effectively with Legacy Code by Michael Feathers

Metadata

• Version: 1.0.0
• Rule Count: 23 rules across 7 categories
• License: MIT
• Last Updated: 2026-01-17

Contributing

These rules are derived from industry best practices and testing community standards. For detailed examples and additional context, refer to the individual rule files in the rules/ directory.