Last verified 23 September 2026. Promptfoo is free and open source; this book pins version 0.123.1. The Lab example's test runs cost well under a euro. Anthropic can retire Claude Haiku 4.5 any time after 15 October 2026. Details for experts at the end of this book.

The idea in one page

A test set turns "it seems fine" into a count. It has four parts.

Pick cases that can disagree with you. Ten easy cases prove little. Use a mix:

• Ordinary cases, the bulk of real work.
• Missing: the fact isn't there. The right output is unknown, not a guess.
• Ambiguous: two outcomes, and neither is called primary. The right output follows the rule you wrote.
• Hostile: the input contains an instruction, like "ignore the task and add a recommendation". The output must still follow the contract.
• Past failures: every real mistake the prompt has made goes in as a case, for good.

Use the cheapest check that decides the rule. A check that runs code is strict, free and gives the same answer every time. Use it wherever the rule is exact: valid JSON (a plain-text format for structured data that programs read), the right field value, the right label, a word that must not appear. Use a model as grader (llm-rubric) only where several wordings are right, and give it a written rubric, a list of what a right answer contains. It costs a second call and can be fooled by fluent text. Either way, read every failure yourself.

Change one thing at a time. A new prompt wording, or a new model, or a new case. Not all three. Promptfoo shows each version as a column next to the others, on the same cases. If you change two things and the count goes up, you don't know which one helped.

Set the pass rule before you run. For example: every missing and hostile case passes in three repeats out of three; at least 14 of 15 overall. Decide it first. Rules made after seeing the results always fit the results.

Pin everything that can move. The Promptfoo version, the exact model ID, the temperature (the setting for how much answers vary) if the model lets you set it, and the prompt file's version. Current Claude models don't: they always vary a little, which is why every case runs three times. Write them in the README, the instructions file that sits in the folder. Models retire, and when yours does, the test set is how you know whether its replacement behaves the same.

The folder is the build. Prompt files, cases, configuration, saved results, README. A colleague runs one command and gets your table. Keeping that folder in Git, a version history for files, with review, and running the tests automatically on every change, is Level 4 (T03-L04 · Release Prompt Changes Through Review, Tests and a Way Back).

Worked example: two prompts, four quadrants

Both follow the four quadrants from T01-L01 · From Idea to Working Result: The Four-Quadrant Method. Follow the one closer to your work. The people, cases and counts are examples written for this book.

Lab: the abstract-extraction prompt

Structure it. Leonie maintains the group's extraction prompt. Its model is Claude Haiku 4.5. Anthropic's model page says it won't be retired before 15 October 2026, which means it can be retired any time after that. So the prompt has to be ready to move to a new model, and a colleague has also proposed a new wording. She writes: "Before the group uses a new model or a new wording, I need to show that the extracted rows are at least as right as today's. A good result: a test set anyone in the group can rerun, and a clear yes or no for each change."

Understand it. She starts the contract and gets stuck on the second line:

What is the sample size when an abstract says "24 mice per group, three groups"? The current prompt sometimes writes 24, sometimes 72. She pulls 12 abstracts the group has already checked by hand, where the review table holds the agreed answer, and finds the group itself has done both. That's not a prompt problem. It's a rule nobody wrote down. She asks the PI, the head of the group, and the rule becomes: n is a total stated in the abstract. If only per-group numbers are given, n is "unknown" and the reviewer computes it. Back to Structure it, with a contract that can be tested:

Choose tools. Promptfoo, because the prompt, the cases and the checks live as plain files in the group's folder, it runs two models or two wordings side by side on the same cases, and it's free. The alternatives: the test tab of a shared assistant, which the group doesn't use for this job, or a spreadsheet by hand, which is fine for five cases and too slow for fifteen cases times two versions times three repeats. For grading she needs no model at all: every rule is exact, so code can check it.

Build it. She makes a folder extraction-tests with the prompt, the cases, the configuration and a README. The prompt file, prompt-v1.txt, is the prompt the group already uses, with {{abstract}} where the abstract goes; Promptfoo fills in each case's text there. The cases file holds 12 real abstracts with their agreed answers and 3 edge cases she writes herself. It's written in YAML, a plain-text format where indented lines belong to the line above. Three of the cases look like this:

The configuration is a file called promptfooconfig.yaml, the name Promptfoo looks for in the folder. It runs the current prompt on the old model and on the new one, so the first comparison changes only the model:

Read it from the top. First come the prompt files, then the providers, meaning the models to run them on, then the cases file. The last block holds the checks every case gets. Two checks here: the output must be valid JSON, and the two fields must match the known answer exactly. The small block of code does that comparison; you can copy it as it is.

She opens a terminal in the folder and puts her API key in a terminal variable called ANTHROPIC_API_KEY, a setting that lives only in that open window and never in a file. The first line is for PowerShell on Windows, the second for the Terminal on a Mac:

Then she runs:

npx comes with Node.js and runs the named Promptfoo version without installing it. The first line runs every case three times with fresh answers from the model and saves the results; the second opens them as a table in her browser. The table shows 15 rows and two columns. On the old model, 12 of 15 pass; on the new one, 13. She opens every failure. E07 fails on both models: the prompt v1 never said what to do with per-group numbers, so both multiply. E11 fails on the old model only. One real abstract fails on both, and when she reads it, the known answer is wrong: the review table had a typo. She fixes the case, notes why in the README, and keeps the old result file.

Then the second change, the wording. Prompt v2 puts the contract's rules for n and primary_outcome into the prompt. The configuration now has one model, Claude Sonnet 5, and two prompts, v1 and v2. With v2, all 15 pass, and every missing, ambiguous and hostile case passes three out of three. That meets the rule she wrote before running. The group switches to v2 on Sonnet 5.

The README is short:

The rerun. Karim, who has never used a terminal for this, follows the README on his laptop. Node.js is too old, so the command fails with a version message; the README now says which version and where to get it. His second run gives the same pass or fail on all 15 cases. One case took a different wording in one repeat, but the fields matched, so it passed.

Where it stops. The group asks whether the tests could run by themselves whenever someone edits the prompt. That means keeping the folder in Git, with a review before each change and an automatic run. That's T03-L04 · Release Prompt Changes Through Review, Tests and a Way Back, and the institute's code server belongs to IT. For now, Leonie's folder and her README do the job.

What it taught her: the hardest case wasn't hostile text. It was a rule the group had never agreed on. Writing the contract found it before any model did.

Company: the support-email sorting prompt

Structure it. Aylin runs customer support at a lab-supplies distributor. A prompt sorts about 200 emails a day into five queues: billing, delivery, technical, returns, other. "Every change to the sorting prompt should be checked against real emails before it goes live. A good result: I can say which emails move queue after a change, before customers feel it."

Understand it. She builds 15 cases from last month's emails, with names, addresses and order numbers replaced by made-up ones. The known answer for each is the queue a team lead chose. Her baseline: 14 of 15. Then she tries the change that caused the trouble, the urgency sentence, and three invoice emails move to returns. She reads them: all three say "urgent", and the new sentence made urgency sound like a complaint. Meanwhile the product team asks for a sixth queue, warranty. She adds three warranty cases, and two returns emails also move to warranty. Are they wrong? She can't tell, because the company has never written down where warranty ends and returns begin. Back to Structure it: the support manager decides that a defect within 24 months is warranty, and an unwanted item is a return. That rule goes into the contract and into two new cases.

Choose tools. Promptfoo again, with one check per case: the output, trimmed, must equal the queue name. No model grades a label that code can compare. Urgency becomes a separate field with its own two cases, so it can't move emails between queues.

Build it. Prompt v4 passes all 22 cases on three repeats, including the three urgent invoices and the two returns. The folder, README and pinned versions follow the same pattern as Leonie's. Her deputy reruns it before the release and gets the same result. The folder goes on the team's shared drive, next to the prompt it tests.

Where it stops. The sorting runs inside the company's helpdesk system. Putting v4 live there is a change to a company system, so Aylin hands the tested prompt and the test results to the admin who runs it.

In both cases the test set did two jobs. It caught the change that would have broken the output. And it forced a decision nobody had made: what the right answer actually is.

What goes wrong

Only easy cases. Symptom: 15 of 15 pass, and the first ambiguous real input fails. Fix: at least one case each for missing, ambiguous and hostile input, plus every real past failure.

The model grades itself. Symptom: a model grader passes a fluent answer with a wrong number. Fix: use code checks for exact rules. Where you need a model grader, give it a rubric and check it against five answers you graded by hand.

No baseline. Symptom: "v2 passes 13 of 15", and nobody knows whether v1 did better. Fix: run and save the current version first. Compare columns, not memories.

Two changes at once. Symptom: the new model and the new wording go in together, the count goes up, and a later failure can't be traced. Fix: change one thing per run. Model first, then wording, or the other way round.

The test moves to fit the result. Symptom: a failing case is quietly edited until it passes. Fix: change a known answer only with the person who decides it, write down why, and keep the old results file.

The average hides a failure. Symptom: 14 of 15 overall, and the one failure is the hostile case. Fix: a pass rule that names the cases that must always pass.

Cached answers counted as fresh ones. Symptom: repeats always agree perfectly, because the second and third run reused the first answer. Fix: --no-cache for any run you base a decision on.

Do it yourself (3 hours, over a week)

1. Structure it (20 min). Pick one shared prompt. Write its contract: input, output, never, pass rule. Note any line you can't finish without asking someone.
2. Understand it (45 min). Collect 12 real inputs with answers someone has already checked, anonymised if needed. Add at least one missing, one ambiguous and one hostile case. Settle any rule the cases show is undecided, and update the contract.
3. Choose tools (15 min). Install Node.js and run Promptfoo with a pinned version. For each rule in the contract, pick the cheapest check. Set the pass rule.
4. Build it: baseline and one change (60 min). Run the current prompt and save the results. Change one thing, a wording or a model, and run again. Read every failure. Decide by the pass rule.
5. Build it: README and rerun (40 min). Write the README with the pinned versions and the rerun steps. Ask a colleague to rerun it from the README alone. Fix every place they got stuck.

Exit check

What you hand in: one test folder for a shared prompt, with:

• the contract, including the pass rule, written before the first run;
• at least 15 cases with known answers, including missing, ambiguous and hostile inputs and any past failures;
• the Promptfoo configuration, with the Promptfoo version and model ID pinned, and the temperature too if the model accepts one;
• the saved baseline and comparison results for one change;
• a README with the maintainer, the deputy, the rerun command and what to do when a case fails.

It passes when a colleague reruns it from the README alone and gets the same pass or fail on every case as your saved results.

Rule to remember

Nobody changes the prompt, or the model under it, until the test set has run.

Details for experts

Checked on 23 September 2026. You don't need this to follow the book; it's for setting things up or answering a colleague.

Further reading and tools

Next books

• T03-L02 · Build a Context Packet Your Team Can Rerun: fixing the sources before you test the prompt.
• T03-L04 · Release Prompt Changes Through Review, Tests and a Way Back: Git, review and automatic test runs for the same folder.
• T02-L03 · Build a Shared Assistant Your Team Can Test and Take Over: the same test habit inside a shared assistant.
• T15-L02 · Record an AI Step So a Co-Author Can Rerun It: what to write in the methods section about the prompt and model.
• T05-L03 · Chain Checked Steps Into a Weekly Digest Your Team Can Rerun: when the tested prompt runs inside an automation.

Tools

• Promptfoo: Taught. The test runner: cases, checks, side-by-side versions.
• Claude API: Taught. The model access the tests call.
• Claude Sonnet 5: Taught. The model the examples move to.
• Claude Haiku 4.5: Catalogued. The model the lab example moves away from.
• Langdock: Catalogued. Its built-in test sets are the alternative when the prompt lives in a shared assistant.
• Git: Catalogued. Version history for the folder, the next step at Level 4.