v1.41.0 ·
A criterion that names its test
Acceptance criteria in AIDLC were free prose with an ID. Some were testable and some were wishes, and the only way to tell them apart was to read them. Bug fixes were worse. The requirements said what to fix but not what to leave alone, so a regression right next to the fix went unchecked.
What changed
Criteria that describe a behaviour now take one of four sentence shapes: "WHEN the user presses Save, THE SYSTEM SHALL write the draft to disk", or the same with WHILE, IF ... THEN, or WHERE. Each one says what to set up and what to check, so the test for it is already half written. A criterion that is not a behaviour, like a page-load budget or a docs change, stays a plain sentence. Nothing rejects it.
Bug fixes now say what must not change. A bugfix's requirements have three parts: what happens today, what the fix makes happen, and what works next to the fix and must keep working. Every line in the last two parts is a numbered criterion. The existing check that every criterion has a test now covers the neighbours of a fix too. The testing guidance says how to test each shape, including that a "must not change" test passes both before and after the fix.
Why this way
Three decisions, each about not making the rule more expensive than the problem.
I did not enforce the shape. A check that rejects any criterion not written as "WHEN ..., THE SYSTEM SHALL ..." would catch vague wishes. It would also reject "the page loads in under two seconds", which is a perfectly good criterion that is not a behaviour. So the shape is taught when requirements are written and never checked. Every criterion still needs a test, which was already true, and that is what gives the shape its teeth.
The "must not change" lines could have lived in the bug's reproduction file. I put them in the requirements file instead. The check that pairs criteria with tests reads only the requirements file, so a line in the reproduction file would have been advice nobody checks. In requirements, numbered like any other criterion, it gets a test or the work does not finish.
The last decision was how to know the new criteria would not vanish. The parser that finds criteria accepts anything after the number and colon, so nothing should break. I did not want to trust that. The tests feed it every shape in every bullet style, plus this change's own requirements file, which was written in the new shapes before the tests existed. Then I broke the parser on purpose, and every one of those tests failed.
What it costs
$7.76 to build. No new check was added, so there is no new gate for later work to trip over. Every criterion written before this release still reads the same.
What it does not do is judge whether a criterion is any good. The sentence shape makes a vague wish easier to spot. It does not stop you writing one.