Testing Best Practices Skill

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

Agent Skills: Testing Best Practices

Install this agent skill to your local

Skill Files