Test Code Writing Guide | Understand the Basics of Unit Test Structure with the Arrange-Act-Assert (AAA) Pattern

When you start writing tests with pytest, a common question is: “How should I actually structure my test code?” The answer is the Arrange-Act-Assert (AAA) pattern. By organizing every test into three clear phases — set up, execute, verify — you can write test code that is easy to read and easy to maintain.

📌 Who This Article Is For

When I first started writing tests, I wrote code like this:

# ❌ No structure — it's not clear what's being tested
def test_calc():
    assert add(1, 2) == 3
    assert add(-1, 1) == 0
    assert add(0, 0) == 0
    result = add(100, 200)
    assert result == 300
    assert add(1.5, 2.5) == 4.0

It looks fine at first glance — but when one of those assertions fails, it’s not immediately obvious which test case broke or why. The intent is also buried under a pile of assertions. The Arrange-Act-Assert pattern solves exactly this problem.

What Is the Arrange-Act-Assert (AAA) Pattern?

The AAA pattern is a way of structuring test code into three distinct phases. It works with any programming language and any test framework, and is widely considered the de facto standard in the testing world.

The AAA Pattern in Practice

Here’s what the earlier test looks like rewritten with the AAA pattern:

# ✅ Rewritten with the AAA pattern
def test_add_returns_correct_sum_with_positive_numbers():
    # Arrange: prepare the data needed for the test
    a = 2
    b = 3

    # Act: run the behavior being tested
    result = add(a, b)

    # Assert: verify the result matches expectations
    assert result == 5


def test_add_returns_zero_when_adding_opposite_numbers():
    # Arrange
    a = -1
    b = 1

    # Act
    result = add(a, b)

    # Assert
    assert result == 0

Each Phase in Detail

① Arrange: Build the Test’s Preconditions

The Arrange phase is where you prepare everything the test needs — variables, objects, or mock data. When Arrange starts getting long, pytest fixtures are the right tool to clean it up.

def test_user_full_name():
    # Arrange: create the object needed for the test
    user = User(first_name="Alice", last_name="Smith")

    # Act
    result = user.get_full_name()

    # Assert
    assert result == "Alice Smith"

② Act: Run the Behavior You’re Testing

The Act phase is where you execute the behavior under test. Ideally it focuses on one specific thing, but in practice — logging in before taking an action, adding items to a cart then checking the total — multiple steps are perfectly normal. What matters is that the purpose of the test stays clear.

# ⚠️ Arrange and Act are mixed together — hard to tell what's being tested
def test_bad_example():
    cart = ShoppingCart()
    cart.add_item("apple", price=100)
    cart.add_item("banana", price=150)
    cart.apply_discount(10)       # ← Are we testing the discount? The total?
    result = cart.total()
    assert result == 225

# ✅ Clear structure — the test's purpose is explicit
def test_total_is_correct_after_adding_two_items():
    # Arrange (precondition: two items in the cart)
    cart = ShoppingCart()
    cart.add_item("apple", price=100)
    cart.add_item("banana", price=150)

    # Act (what we're verifying: the total calculation)
    result = cart.total()

    # Assert
    assert result == 250

③ Assert: Verify the Result

The Assert phase is where you compare actual results against expected values using assert. Aim for 1–3 assertions per test function. pytest automatically shows a detailed diff when an assertion fails, so you can keep your assert statements simple and readable — no special assertion libraries needed.

# ✅ Simple, readable assertions (recommended)
assert result == 5
assert result is not None
assert "error" not in response_body
assert status_code in (200, 201)

# ✅ With an error message (easier to diagnose failures)
assert result == 5, f"Expected 5, got {result}"

# ❌ Too many assertions in one function
def test_user():
    user = create_user("Alice", "alice@example.com")
    assert user.name == "Alice"
    assert user.email == "alice@example.com"
    assert user.is_active is True
    assert user.role == "user"
    assert user.created_at is not None  # 5 assertions — which one failed?

Writing Readable Test Function Names

Test function names are just as important as the AAA structure. When a test fails in CI/CD, the function name is often the first thing you look at. A good name tells you what was tested, under what condition, and what was expected — without opening the code.

Recommended Pattern: test_[what]_[condition]_[expected outcome]

The names look long, but when test results scroll past in a terminal, the function name is the only context you have. Clear names save real debugging time.

import pytest

@pytest.mark.parametrize("a, b, expected", [
    (2,  3,   5),   # normal case
    (0,  0,   0),   # boundary
    (-1, 1,   0),   # negative numbers
])
def test_add_returns_correct_sum(a, b, expected):
    result = add(a, b)          # Act
    assert result == expected   # Assert

Practice: Common Test Scenarios with the AAA Pattern

Example ①: Testing a Function

def add(a: float, b: float) -> float:
    return a + b


def test_add_returns_correct_sum_with_positive_numbers():
    # Arrange
    a = 3
    b = 4

    # Act
    result = add(a, b)

    # Assert
    assert result == 7


def test_add_returns_negative_when_both_negative():
    # Arrange
    a = -3
    b = -4

    # Act
    result = add(a, b)

    # Assert
    assert result == -7

Example ②: Testing That an Exception Is Raised

import pytest


def divide(a: float, b: float) -> float:
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b


def test_divide_raises_value_error_when_divisor_is_zero():
    # Arrange
    a = 10
    b = 0

    # Act & Assert (exception tests naturally merge these two phases)
    with pytest.raises(ValueError, match="Cannot divide by zero"):
        divide(a, b)

Example ③: Testing a Class Method

class ShoppingCart:
    def __init__(self) -> None:
        self._items: list[dict] = []

    def add_item(self, name: str, price: int) -> None:
        self._items.append({"name": name, "price": price})

    def total(self) -> int:
        return sum(item["price"] for item in self._items)


def test_total_returns_sum_of_all_item_prices():
    # Arrange
    cart = ShoppingCart()
    cart.add_item("apple", price=100)
    cart.add_item("banana", price=200)

    # Act
    result = cart.total()

    # Assert
    assert result == 300


def test_total_returns_zero_when_cart_is_empty():
    # Arrange
    cart = ShoppingCart()

    # Act
    result = cart.total()

    # Assert
    assert result == 0

Common Pitfalls with the AAA Pattern

Frequently Asked Questions

Summary

The AAA pattern isn’t a difficult technique — it’s a courtesy to the people who will read your tests. Writing tests that anyone on the team can understand at a glance is the foundation of a maintainable test suite. Start applying it to the very next test function you write.