Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 38 ยท CI and Best Practices

Test Design and Best Practices

Write tests that stay valuable: Arrange-Act-Assert, one behavior per test, good names, testing behavior instead of implementation, the test pyramid, and common anti-patterns with fixes.

Writing a test is easy. Writing a test that is still useful two years later, when someone else is changing the code, is a skill. Good tests act as a safety net and as documentation. Bad tests are a tax: they fail for irrelevant reasons, they are hard to read, and in the end people delete them or stop trusting them.

This lesson collects the design rules that experienced teams converge on. Each is small; together they decide whether your suite is an asset.

Arrange, Act, Assert

Structure every test in three visible parts: Arrange the objects and data, Act by calling the one thing you are testing, Assert on the outcome. Separate them with blank lines (or comments in longer tests). A test that interleaves setup, calls and checks is much harder to read.

flowchart LR
    A["Arrange<br/>build inputs, fakes"] --> B["Act<br/>call the code once"] --> C["Assert<br/>check the result"]

If a test needs two Act steps, it is probably two tests.

One behavior per test, named like a sentence

A test should fail for exactly one reason, so a red test name tells you what broke. Name tests after the behavior, not the function: test_expired_coupon_is_rejected beats test_coupon_2. A failing report then reads like a bug report:

TEXT
FAILED test_cart.py::test_discount_is_not_applied_to_gift_cards

Group related tests in a class (class TestCheckout:) or module only when it helps navigation. Do not pile many unrelated assertions into one test; when the first fails, the rest never run.

Test behavior, not implementation

A test coupled to how the code works breaks on every refactor even though nothing visible changed. A test coupled to what it does survives. Compare these two tests for the same function:

Python Brittle versus robust tests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

If you later change _items to a dictionary, the brittle test fails although the cart works perfectly, while the others keep passing. Note also pytest.approx for floating-point comparisons: 0.1 * 3 is not exactly 0.3 in binary floating point.

Make failures easy to read

  • Plain assert. pytest rewrites assertions to show both sides and a diff. Avoid wrapping in assertTrue-style helpers.
  • Add a message only when it adds information: assert user.is_active, f"user {user.id} should be active after signup".
  • Compare whole values (assert result == {"id": 1, "name": "Ada"}) rather than many field checks; the diff shows everything.
  • Use pytest.raises(ErrorType, match="...") so the test fails if the wrong error (or message) appears.
  • Keep fixtures' names meaningful (logged_in_admin, not user2) so a test reads as a story.

The test pyramid

flowchart TB
    E["Few end-to-end tests<br/>slow, real system, high confidence"]
    I["Some integration tests<br/>real database / API boundaries"]
    U["Many unit tests<br/>fast, isolated, precise"]
    U --> I --> E

Most tests should be fast and local; a few should prove that the parts work together.

Unit tests give fast, precise feedback. Integration tests check boundaries (database, HTTP, files). A handful of end-to-end tests protect the most valuable user journeys. An inverted pyramid, with mostly slow browser tests, is slow and flaky. Use markers (unit, integration, e2e) to run each layer separately.

Test doubles: use the right one, and little

Double What it is Example
Dummy Placeholder never used None passed as an unused argument
Stub Returns canned answers A fake client returning fixed JSON
Fake Simplified working implementation In-memory repository, SQLite for PostgreSQL
Mock Records calls so you can assert on them Mock().send.assert_called_once_with(...)
Spy Real object that also records calls mocker.spy(...)

Prefer fakes and stubs (they check results) over mocks (they check interactions). Heavy mocking makes tests mirror the implementation line by line. A good rule: mock the boundary of your system (network, clock, payment provider), not your own classes. Passing collaborators as arguments (dependency injection) usually removes the need to patch anything, as the mocking lessons showed.

Anti-patterns to avoid

Python Refactoring a tangled test

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The giant test even hides a bug: its try/except ValueError: pass would also pass if withdraw(1000) raised nothing at all. pytest.raises fails when no exception occurs. Other habits to drop:

  • Tests that depend on each other or on order. Each test must set up its own world.
  • Logic in tests. Loops and if statements in a test body can contain their own bugs; prefer parametrization and literal expected values.
  • Copying the production formula to compute the expected value. Use a hand-calculated literal.
  • Assertion-free tests and except: pass. A test that cannot fail is worse than none.
  • Testing the framework or Python itself (assert len([1, 2]) == 2).
  • Chasing a coverage number with meaningless tests.
  • Slow sleeps, real clocks and the real network in unit tests.
  • Silencing failures with xfail or skip and never coming back. Always give a reason= and a ticket.

A habit worth adopting: write the failing test first

When you find a bug, write a test that reproduces it before fixing it. Watching it fail proves the test can catch the problem; watching it pass afterwards proves the fix; and the bug can never silently return. The same rhythm (red, green, refactor) is the heart of test-driven development, which you will practice in the shopping-cart project.

A review checklist

Before you commit a test, ask:

  1. Does the name say what behavior is expected?
  2. If it fails, will the message tell me what broke?
  3. Does it test one behavior through the public interface?
  4. Is it independent, deterministic and fast?
  5. Would a harmless refactor break it? (If yes, it is too tied to implementation.)
  6. Could the assertion fail at all?

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What do the three letters in AAA stand for?

    Arrange the inputs, Act by calling the code once, then Assert on the outcome. Keeping the order visible makes tests easy to read.
  2. 2. Which test is more robust against refactoring?

    Tests of observable behavior survive internal changes; tests tied to implementation details do not.
  3. 3. In which situation is a mock more appropriate than a fake or stub?

    Mocks verify interactions. Prefer stubs and fakes when you can check results instead.
  4. 4. Why is try: f() except ValueError: pass a weak way to test that f raises?

    pytest.raises fails the test if no exception occurs; the try/except version silently passes.

Summary

  • Structure tests as Arrange, Act, Assert; one behavior per test with a sentence-like name.
  • Test public behavior, not implementation, and compare floats with pytest.approx.
  • Follow the pyramid: many fast unit tests, fewer integration tests, a handful of end-to-end tests.
  • Prefer fakes and stubs to mocks; mock only the boundaries of your system.
  • Avoid order dependence, logic in tests, assertion-free tests and silent skips; reproduce bugs with a failing test first.

Next: Project: Test-Driven Shopping Cart