When should you use it?
- Your agent creates bookings, orders or records, and a duplicate would cost money or trust
- You fixed a double-write bug once and want proof it stays fixed through future edits
- Tests you wrote earlier keep breaking when someone renames a node or changes the reply text
Not for: Checking whether the agent's answers are helpful; this covers only the plumbing around writes; Workflows with no request key or log to count from; add those first; Teams looking for full end-to-end coverage of a live vendor system
What do you need, and what do you get?
You need
- A request key attached to every write your agent makes
- An append-only event log or table of write attempts
- A stand-in backend that can delay or reject on command
- A way to run the test workflow after each change, by hand or in CI
You get
- One test workflow that runs in seconds with no model calls
- Three pass or fail checks: one write, repeat skipped, timeout escalated
- Failure messages that name the broken promise rather than a node
- A record of regressions caught before customers saw them
How does it work, step by step?
- Stub the backendReplace the real booking or order system with a stand-in that can answer normally, stall past your timeout or refuse on demand.
- Send the same key twiceFire two identical requests with one request key through your real orchestration path.
- Count from the logRead the append-only log, not the tool's reply, and expect exactly one completed write.
- Treat the repeat as successExpect the second attempt to finish as a skip. If the duplicate path throws an error, callers will escalate forever.
- Force a timeoutMake the stub stall and confirm the attempt is logged as unknown and handed to staff, never confirmed to the customer.
- Leave out what may changeDo not check message wording, response times or schema details, so renames and refactors leave the test untouched.
The prompt
Our own prompt, inspired by ccch713 and written to work in n8n, Custom agent, ChatGPT and others. Values in lime are placeholders.
Fill in the blanks (optional; the copied prompt uses your values)
Help me write a contract test for the write path of my agent workflow in {platform}. The write tool is {write_tool} and every call carries {request_key_field}. Design a test that uses a stand-in backend (no live system and no model calls) and checks three things from {event_log}: two identical requests create exactly one record; the second request is reported as a deliberate skip rather than a failure; a forced timeout is recorded as unknown and sent to {staff_queue}, never confirmed. Leave out reply wording, timing and schema details. Give each check a failure message that names the broken rule in plain words, and show how to run the test after every change.
Inspired by ccch713: n8n Community: the acceptance workflow, what it asserts, what it ignores, why it survived three refactors. The prompt above is written by playbooks.bot in our own words; nothing from the original is quoted.
What can go wrong?
- Checking the precise wording of what the agent says makes the test fragile, and fragile tests get switched off.
- If running the check requires a model key and several minutes, people stop running it. Keep the model out of this path.
- Counting writes from the tool's own response can hide duplicates. Count from a log nobody can edit.
- Naming the failing node instead of the broken promise makes red runs hard to read months later.
Our take
This is the third post in a series we have followed, and it is the one we would print out. The first two explained what went wrong and how to log it. This one explains how to make sure nobody undoes the fix by accident. The central idea is easy to say and hard to practice: test the promise, not the implementation. Most teams test what is easy to see, like the reply text or which node ran, and then wonder why their tests break every week. Counting writes from a log that only grows, and treating a skipped repeat as a success rather than an error, are two details that separate a test that lasts from one that gets deleted. Keeping the model out of the test path is just as smart, because the promise lives in the plumbing. Our caution is scope. This guards one contract and nothing else, so you still need other ways to judge the quality of the agent's replies. In our dry run, the mock caught a planted second write and passed once the request key check was restored.
Where the time goes back: One check that runs in seconds replaces careful manual review of every refactor that touches the write path, and it catches duplicates before a customer or staff member does.
FAQ
How does this relate to the other two guides from this author?
Has it caught anything?
Do I need special test tooling in n8n?
Source and credit
Inspired by ccch713. We describe the idea in our own words, link to the original, and wrote the prompt ourselves; nothing is quoted.
- Inspired by
- n8n Community: the acceptance workflow, what it asserts, what it ignores, why it survived three refactors
- Creator
- ccch713
- Published on
- n8n Community
- Original date
- Nov 11, 2026
- License
- Not openly licensed (the poster keeps all rights), so we quote nothing and link to the original
- Originally for
- n8n
- AI dry run
- Nov 11, 2026: passed. Dry-run tested by our AI test agent on sample input. Planted duplicate caught with plain-language rule names; restored path passed all three checks.
AI dry run on sample data; not run with live connected accounts. The playbooks.bot test agent filled the prompt with synthetic inputs, produced the output and checked it against the page's stated outputs and guardrails. - Verified
- Nov 11, 2026: source link resolves to the original, the credited creator published it, our excerpt or prompt matches it, and the license allows our use.
Are you the creator? Claim or correct this page.