Master

Choosing what the suite asserts when everything cannot be asserted

The suite cannot assert everything, so the choice has to be explainable. The rule is to assert the properties that break most often and that users depend on most, and to leave the rest to the audit list. The reason is written next to the assertion so the next person can disagree with it.

What you will see

The deferred list exists and is dated. An empty list is fine, an absent list is not.

About 1 min of reading

Quick check

Before this new lesson, one small question about the lesson you just finished. Recall it, do not look it up.

Try It

Decide and record for three gaps

1

Take the top gap

head -1 docs/fe-gaps.md

Before you run it, say out loud what it will print. Then open the answer.

What it prints
One page. Work one gap at a time so each decision is visible.
2

Estimate the break rate

grep -lE 'class="tutorial-card' views/*.ejs views/partials/*.ejs | head -5

Before you run it, say out loud what it will print. Then open the answer.

What it prints
How many files would break that assertion. Many files means the assertion is fragile and belongs lower.
3

Write the assertion with its reason

printf '// asserts: cards render on the lessons page (every visitor depends on this) ' | tee -a FULLTEST/fe.test.js

Before you run it, say out loud what it will print. Then open the answer.

What it prints
A reason line above the check. The next person can disagree without guessing.
4

Record the deferrals

printf 'deferred: /downloads form test (few users, low break rate, 2026-10) ' | tee -a docs/fe-deferred.md

Before you run it, say out loud what it will print. Then open the answer.

What it prints
The deferred list exists and is dated. An empty list is fine, an absent list is not.
Do not assert everything that seems interesting. A suite of interesting-but-unreachable checks is slow and protects the wrong things.

Data Flow

Gap to an asserted or deferred decision
1 Take the top gap
↓
2 Ask how often it breaks
↓
3 Ask how many users hit it
↓
4 Assert or defer, and write the reason
Why this works
The two lists to keep

The asserted list and the deferred list. The deferred list is not abandoned work, it is work someone agreed to do later, and it has to be visible.

When to retire an assertion

When the feature it asserts on is gone. A green assertion on a removed feature is a lie about the suite, so removal is part of the change.

Examples

Break rate decides order

The markup that changed since the last release is the likely breakage. Assert what changed first, then what has been stable.

User dependence decides weight

One assertion on the page most users load is worth more than three on a page few reach. Weight by reach, not by how interesting the check is.

Write the reason beside it

A comment naming why the assertion exists. Without it, the suite grows by duplication and nobody can remove a stale check.

Words this lesson uses

Each one is defined here on this site. Open the entry for the full definition and the other words it points at.

← Auditing the frontend suite for what it does not cover
Previous Lesson
Auditing the frontend suite for what it does not cover
Next Lesson
A written policy for the frontend suite
A written policy for the frontend suite →