AAA Pattern, Test Naming, and File Organisation

1import { calculateTax } from './tax-calculator';
2
3test('applies 20% VAT to a positive price', () => {
4  // Arrange
5  const price = 100;
6  const vatRate = 0.20;
7
8  // Act
9  const result = calculateTax(price, vatRate);
10
11  // Assert
12  expect(result).toBe(120);
13});

1// BAD: multiple Acts — two things being tested in one test
2test('user operations', () => {
3  const user = createUser('Alice');           // Act 1
4  expect(user.name).toBe('Alice');            // Assert 1
5  const updated = updateUser(user, 'Bob');    // Act 2
6  expect(updated.name).toBe('Bob');           // Assert 2
7});
8// When this test fails on line 4, you do not know if createUser or updateUser broke.
9
10// GOOD: one Act per test
11test('createUser sets the name from the argument', () => {
12  const user = createUser('Alice');
13  expect(user.name).toBe('Alice');
14});
15
16test('updateUser replaces the name', () => {
17  const user = createUser('Alice'); // Arrange — setup, not Act
18  const updated = updateUser(user, 'Bob'); // Act
19  expect(updated.name).toBe('Bob');
20});

1describe('passwordValidator', () => {
2  it('should return valid when password has 8+ characters and a number', () => { ... });
3  it('should return invalid when password is shorter than 8 characters', () => { ... });
4  it('should return invalid when password has no numeric digit', () => { ... });
5  it('should throw TypeError when input is not a string', () => { ... });
6});

1describe('ShoppingCart', () => {
2  describe('given an empty cart', () => {
3    it('when an item is added, then the cart has one item', () => { ... });
4    it('when subtotal is calculated, then it returns 0', () => { ... });
5  });
6
7  describe('given a cart with items', () => {
8    it('when an existing item is added again, then quantity increases', () => { ... });
9    it('when an item is removed, then cart length decreases by 1', () => { ... });
10  });
11});

1// BAD: vague — what does 'works' mean?
2test('works', () => { ... });
3
4// BAD: implementation detail — 'calls the function' adds no value
5test('calls calculateTax with price and rate', () => { ... });
6
7// BAD: 'test' prefix is redundant — Jest already knows it's a test
8test('test that discount is applied', () => { ... });
9
10// GOOD: behaviour-focused, specific
11test('returns 0 discount when coupon code is expired', () => { ... });
12test('throws InvalidCouponError when code does not exist in registry', () => { ... });

1// ACCEPTABLE: multiple expects for a single logical outcome
2// If any one fails, the test name 'creates user with correct initial state' still precisely describes the failure
3test('creates user with correct initial state', () => {
4  const user = createUser({ name: 'Alice', email: '[email protected]' });
5
6  expect(user.id).toBeDefined();          // all three describe
7  expect(user.name).toBe('Alice');        // the same single outcome:
8  expect(user.active).toBe(true);         // 'user is correctly initialised'
9  expect(user.createdAt).toBeInstanceOf(Date);
10});
11
12// BAD: two unrelated outcomes in one test
13test('user creation and deletion', () => {
14  const user = createUser({ name: 'Alice', email: '[email protected]' });
15  expect(user.id).toBeDefined(); // outcome 1: creation
16
17  deleteUser(user.id);
18  expect(findUser(user.id)).toBeNull(); // outcome 2: deletion
19  // These are independent behaviours — split them
20});

1// 'and' in name = split signal
2test('creates user and sends welcome email', () => { ... }); // SPLIT THIS
3
4// Split correctly:
5test('creates user with a generated UUID', () => { ... });
6test('sends a welcome email after user creation', () => { ... });

1src/
2├── modules/
3│   ├── auth/
4│   │   ├── auth.service.ts
5│   │   ├── auth.service.test.ts   ← same directory
6│   │   ├── auth.controller.ts
7│   │   └── auth.controller.test.ts
8│   └── cart/
9│       ├── cart.utils.ts
10│       └── cart.utils.test.ts

1src/
2├── __tests__/
3│   ├── integration/
4│   │   └── auth-flow.test.ts
5│   └── setup/
6│       └── jest.setup.ts
7├── modules/
8│   └── auth/
9│       ├── auth.service.ts
10│       └── auth.service.test.ts  ← still co-located

1const config: Config = {
2  testMatch: [
3    '**/*.test.ts',
4    '**/*.spec.ts',
5    '**/__tests__/**/*.ts',
6  ],
7  testPathIgnorePatterns: [
8    '/node_modules/',
9    '/dist/',
10    '/__tests__/setup/',  // setup files are not tests
11  ],
12};

1// test-helpers/factories.ts
2import { User } from '../src/types';
3
4// Factory with sensible defaults — override only what matters per test
5export function buildUser(overrides: Partial<User> = {}): User {
6  return {
7    id: 'user-001',
8    name: 'Test User',
9    email: '[email protected]',
10    role: 'student',
11    active: true,
12    createdAt: new Date('2024-01-01'),
13    ...overrides,
14  };
15}
16
17// Usage: each test declares only what it cares about
18test('inactive users cannot enrol in courses', () => {
19  const user = buildUser({ active: false }); // only the relevant property
20  expect(() => enrolUser(user, 'course-1')).toThrow('Account is inactive');
21});
22
23test('admin users can enrol without payment', () => {
24  const admin = buildUser({ role: 'admin' });
25  const result = enrolUser(admin, 'course-1');
26  expect(result.requiresPayment).toBe(false);
27});
28
29test('users get a confirmation email on enrolment', () => {
30  const user = buildUser({ email: '[email protected]' });
31  const emailSpy = jest.spyOn(emailService, 'send');
32  enrolUser(user, 'course-1');
33  expect(emailSpy).toHaveBeenCalledWith(
34    expect.objectContaining({ to: '[email protected]' })
35  );
36});