Best Practices

The practice is the suite's rules: the AAA structure (the Arrange, the Act, the Assert), the isolation (the no cross-test state, the fixture's fresh), the no-sleep (the wait-for over the time.sleep), the name-the-behavior (the test_word_count_spaced over the test_1), and the test-the-boundary (the edge, the error, not just the happy). The suite is the fast (the -x the loop), the frequent (the every commit), and the focused (the one behavior the test) - the 3F - and the mock's boundary (the mock the dependency, the no mock the logic). This chapter covers the AAA, the isolation, the naming, the no-sleep, the mock's boundary, and the suite's health (the coverage's floor, the flaky's triage, the xfail's strict).

The AAA Structure and the Naming

# the AAA: the ARRANGE (the setup), the ACT (the
#   the call), the ASSERT (the check) - the one
#   behavior the test
from texttools import word_count

def test_word_count_counts_spaced():
    # the ARRANGE (the input, the expected):
    text = "  spaced   out  "
    expected = 2
    # the ACT (the one call, the result):
    result = word_count(text)
    # the ASSERT (the check, the value):
    assert result == expected

# the NAMING: the BEHAVIOR (the the function's name
#   + the case, the failure reads as the bug)
def test_word_count_counts_spaced(): ...   # the GOOD
def test_1(): ...                          # the BAD
def test_word(): ...                       # the WEAK

The AAA is the test's shape: the Arrange (the input, the expected - the fixture the repeated), the Act (the one call, the result), and the Assert (the check, the value) - the three blocks the read, the comment-free, and the one behavior the test (the test_word_count_counts_spaced the name the behavior plus the case, the test_1 the index the no meaning, the test_word the weak the which-word). The naming is the behavior: the test_<function>_<case> (the test_cipher_empty_raises, the test_palindrome_reversed) so the failure's name is the bug's description, and the rule is the one: the one test the one behavior, the AAA the shape, the name the behavior plus the case - the suite reads as the spec the code implements.

The Isolation and the No-Sleep

# the ISOLATION (the no cross-test state, the
#   fixture's the fresh):
#   the BAD (the global, the test's leak):
counter = 0
def test_a():
    global counter
    counter += 1   # the test_b sees the 1

#   the GOOD (the fixture, the fresh per test):
import pytest

@pytest.fixture
def counter():
    return 0

def test_a(counter):
    assert counter == 0   # the fresh

# the NO-SLEEP (the WAIT-FOR over the time.sleep,
#   the flaky's the avoid):
def test_no_sleep():
    # the BAD (the sleep, the fixed wait):
    # time.sleep(2)   # the fast pass, the CI fail

    # the GOOD (the wait-for, the condition, the
    #   the timeout):
    import time
    deadline = time.time() + 5
    while not ready():
        if time.time() > deadline:
            raise AssertionError("the not ready")
        time.sleep(0.1)

The isolation is the no cross-test state: the global (the counter the module's, the test_a the test_b sees the 1) is the flaky's source, and the fixture (the counter the fresh per test) is the fix - the state the declared, the per-test, the no leak. The time.sleep is the flaky's second source: the fixed wait (the sleep(2)) is the fast machine's pass and the slow CI's fail, and the wait-for (the loop over the ready() condition, the deadline the timeout) is the fix - the condition the poll, the timeout the bound. The mock's boundary is the third: the mock the dependency (the HTTP, the DB, the clock) and the no mock the logic (the word_count the real, the fetch the stub) - the stub the boundary, the test the behavior, and the next section's suite health is the practice's metric.

The Suite's Health

# the HEALTH (the suite's three metrics):
#   the COVERAGE (the floor, the no regression):
pytest --cov=texttools --cov-fail-under=80

#   the FLAKY (the triage, the name + the track):
pytest --reruns 2 -p randomly   # the shuffle the
                                #   order's reveal
#   the xfail the documented, the fix the tracked

#   the XFAIL (the strict, the no stale mark):
# [tool.pytest.ini_options]
# xfail_strict = true
#   the XPASS the failure (the cleanup forced)

The suite's health is the three metrics. The coverage's floor is the --cov-fail-under=80 (the no regression below, the coverage.xml the artifact, the badge the guard) - the metric the reports, not the goal the chases. The flaky's triage is the pytest-rerunfailures (the --reruns 2 the transient's no-fail) plus the pytest-randomly (the shuffle the order's reveal) - the flaky named (the test_x the flaky mark), the xfail the documented, the fix the tracked. The xfail's strict is the xfail_strict = true (the XPASS the failure, the no stale mark the suite rots) - the three are the suite's guard: the floor the coverage, the triage the flaky, the strict the xfail, and the next chapter's conftest plus the ini is where the project versions them.

The Working Rules

The AAA is the shape, the name the behavior plus the case. The Arrange the input (the fixture the repeated), the Act the one call, the Assert the check - the test_word_count_counts_spaced the name the failure reads, the test_1 the no.
The isolation is the no cross-test state, the fixture the fresh. The global the flaky's source (the counter the test_b sees the 1), the fixture the per-test, and the wait-for (the loop, the deadline) over the time.sleep (the fixed, the CI's fail).
The mock is the boundary, the no mock the logic. The mock the dependency (the HTTP, the DB, the clock), the real the logic (the word_count) - the stub the boundary, the test the behavior, and the autospec the signature the guard.
The health is the three: the floor, the triage, the strict. The --cov-fail-under=80 the coverage's floor, the --reruns 2 plus the randomly the flaky's triage, the xfail_strict = true the xfail's no-stale - the suite's guard, the ini the versioned.

Summary

The practice is the suite's rules: the AAA structure (the Arrange the input, the Act the one call, the Assert the check) with the name the behavior plus the case (the test_word_count_counts_spaced the failure reads as the bug), the isolation (the no cross-test state, the fixture the fresh, the wait-for over the time.sleep), and the mock's boundary (the mock the dependency, the no mock the logic). The suite's health is the three metrics: the coverage's floor (the --cov-fail-under=80 the no regression, the badge the guard), the flaky's triage (the --reruns 2 the transient, the randomly the order's reveal, the flaky mark the named), and the xfail's strict (the xfail_strict = true the XPASS the failure, the no stale). The 3F is the goal (the fast, the frequent, the focused), and the conftest plus the ini is where the project versions the rules - the tutorial's texttools suite is the pattern: the test_* the name, the fixture the setup, the parametrize the case, the mock the boundary, the mark the lane, and the CI the gate.