Master

A written policy for the frontend suite

The suite needs rules a person can apply without a conversation. The policy names which tests gate which releases, what a new assertion must carry, and what makes a test eligible for removal. Written down, the suite stays a suite instead of becoming a pile.

What you will see

exit=0 with every assertion marked. Add an unmarked assertion and it must fail.

About 1 min of reading

Try It

Write the policy and enforce it

1

Write the three rules

printf '1. document-tier assertions gate every release; browser-tier gate frontend releases\n2. every assertion carries a tier marker and a one-line reason\n3. delete an assertion only when its feature is gone or it duplicates another\n' | tee docs/fe-policy.md

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

What it prints
Three lines. Each one is a decision a person will face again.
2

Mark the tier on each assertion

grep -cE 'tier: (document|browser)' FULLTEST/fe.test.js; grep -cE 'assert|check\(' FULLTEST/fe.test.js

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

What it prints
The two counts equal. An assertion with no tier marker is unclassified.
3

Enforce the marker in the gate

printf 'missing=$(grep -cE "assert|check\\(" FULLTEST/fe.test.js)\nmarked=$(grep -cE "tier: (document|browser)" FULLTEST/fe.test.js)\n[ "$missing" = "$marked" ] || { echo "FAIL unmarked assertion"; exit 1; }\n' | tee -a fe-gate.sh

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

What it prints
The gate fails when an assertion has no tier. The rules cannot rot quietly.
4

Run the gate

./fe-gate.sh; echo "exit=$?"

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

What it prints
exit=0 with every assertion marked. Add an unmarked assertion and it must fail.
Do not let an unmarked assertion into the suite. An unmarked assertion runs in the wrong gate or in none, and that is the drift the policy exists to stop.

Data Flow

Assertion to a policy verdict
1 New assertion is added
↓
2 Check it carries a tier and a reason
↓
3 Gate selects by tier
↓
4 Deletion requires a stated cause
Why this works
Where the policy lives

Next to the suite, in one file. A policy in a person's head is not a policy, and a suite without rules drifts within a month.

How to keep the policy true

The policy is checked by the same gate that runs the suite. A tier marker missing on an assertion fails the gate, so the rules cannot silently rot.

Examples

Three rules are enough

Which gate runs which suite, what a new assertion must include, and when an assertion may be deleted. Three rules cover the decisions that come up most.

Rules name the fast and slow tiers

Document assertions gate every release, browser assertions gate frontend releases. The tier is a property of the assertion, written where it is declared.

Deletion is a policy decision

An assertion is deleted when its feature is gone or when it duplicates another. Anything else is a judgement that belongs in a discussion, not in a commit.

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.

← Choosing what the suite asserts when everything cannot be asserted
Previous Lesson
Choosing what the suite asserts when everything cannot be asserted