name: aaa-pattern
description: Use when writing tests. Use when test structure is unclear. Use when arrange/act/assert phases are mixed.

AAA Pattern (Arrange-Act-Assert)

Overview

Every test has three phases: Arrange, Act, Assert. Keep them separate.

Clear structure makes tests readable, maintainable, and debuggable. When phases blur together, tests become confusing.

When to Use

• Writing any test
• Test logic is hard to follow
• Unclear what's being tested
• Multiple actions or assertions mixed together

The Iron Rule

EVERY test must have clearly separated Arrange, Act, and Assert phases.

No exceptions:
- Not for "it's a simple test"
- Not for "it's more concise this way"
- Not for "the phases are obvious"

Detection: Mixed Phases Smell

If arrange/act/assert blend together, STOP:

// ❌ VIOLATION: Phases mixed together
it('adds items to cart', () => {
  const cart = new Cart();
  cart.add({ id: '1', price: 10 });
  expect(cart.items.length).toBe(1);  // Assert in the middle
  cart.add({ id: '2', price: 20 });   // More acting
  expect(cart.total).toBe(30);        // Another assert
  expect(cart.items.length).toBe(2);  // And another
});

Problems:
- What exactly is being tested?
- Which action caused which result?
- Hard to name the test accurately

The Correct Pattern: Clear Separation

// ✅ CORRECT: Clear AAA structure
it('calculates total price of all items in cart', () => {
  // Arrange
  const cart = new Cart();
  cart.add({ id: '1', name: 'Apple', price: 10 });
  cart.add({ id: '2', name: 'Banana', price: 20 });

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

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

it('tracks number of items in cart', () => {
  // Arrange
  const cart = new Cart();

  // Act
  cart.add({ id: '1', name: 'Apple', price: 10 });
  cart.add({ id: '2', name: 'Banana', price: 20 });

  // Assert
  expect(cart.itemCount).toBe(2);
});

The Three Phases

Arrange

Set up the test scenario:
- Create objects
- Configure mocks
- Prepare input data
- Set initial state

Act

Execute the behavior being tested:
- Single action (usually)
- Call the method
- Trigger the event
- Make the request

Assert

Verify the outcome:
- Check return values
- Verify state changes
- Confirm mock interactions
- Validate side effects

Advanced: Given-When-Then

For BDD-style tests, same concept:

describe('Cart', () => {
  describe('when adding items', () => {
    it('should update the total', () => {
      // Given (Arrange)
      const cart = new Cart();
      const item = { id: '1', price: 25 };

      // When (Act)
      cart.add(item);

      // Then (Assert)
      expect(cart.total).toBe(25);
    });
  });
});

One Assert Per Test?

Guideline, not rule. Multiple asserts are fine if they verify ONE behavior:

// ✅ OK: Multiple asserts for one logical behavior
it('creates user with correct properties', () => {
  // Arrange
  const input = { email: '[email protected]', name: 'Alice' };

  // Act
  const user = createUser(input);

  // Assert - all verify the creation behavior
  expect(user.id).toBeDefined();
  expect(user.email).toBe('[email protected]');
  expect(user.name).toBe('Alice');
  expect(user.createdAt).toBeInstanceOf(Date);
});

// ❌ BAD: Multiple behaviors in one test
it('user operations', () => {
  const user = createUser({ name: 'Alice' });
  expect(user.name).toBe('Alice');

  updateUser(user.id, { name: 'Bob' });
  expect(user.name).toBe('Bob');  // Different behavior!

  deleteUser(user.id);
  expect(getUser(user.id)).toBeNull();  // Yet another behavior!
});

Pressure Resistance Protocol

1. "It's More Concise"

Pressure: "Combining phases makes the test shorter"

Response: Short but confusing is worse than longer but clear.

Action: Separate the phases. Add comments if needed.

2. "It's a Simple Test"

Pressure: "For trivial tests, AAA is overkill"

Response: Consistency matters. All tests should follow the same pattern.

Action: Use AAA even for simple tests. It costs nothing.

3. "I Need Multiple Actions"

Pressure: "The behavior requires multiple steps"

Response: Multiple setup steps go in Arrange. Only the behavior being tested goes in Act.

Action: If you need multiple Acts, you probably need multiple tests.

Red Flags - STOP and Reconsider

• expect() calls between actions
• No clear single "act"
• Assertions scattered throughout
• Hard to describe what test verifies
• Test name doesn't match structure

All of these mean: Restructure with clear AAA.

Quick Reference

Common Rationalizations (All Invalid)

The Bottom Line

Arrange. Act. Assert. In that order. Clearly separated.

Every test sets up (Arrange), does one thing (Act), and verifies (Assert). When phases are clear, tests are readable, debuggable, and maintainable.