# Truquence: Catch an n8n Run That Says Success but Gets It Wrong

> An n8n run can finish green with a wrong total. Write what each node should output, then check the exported run with Truquence: PASS, FAIL or UNKNOWN.

Source: https://learn.ynteractive.com/content/truquence-n8n-workflow-success-but-wrong-output · Updated 2026-10-21 · Free from Stepthrough (https://learn.ynteractive.com)

## Practice it step by step

[Start the free practice](https://learn.ynteractive.com/modules/truquence-n8n-acceptance)

[Take the free module: why it matters, practice and a quick check →](https://learn.ynteractive.com/courses/n8n-jump-start/22)

You do every step yourself in a practice copy of Truquence. It checks your work as you go, and “Do it for me” finishes any step you get stuck on. Free, about 11 minutes, and nothing touches your real accounts. [Open full screen](https://learn.ynteractive.com/modules/truquence-n8n-acceptance)

Free · Live now · [n8n Automation Toolkit](https://learn.ynteractive.com/content/course/n8n-automation-toolkit) · Truquence · n8n · ~11 min · 15 steps · Advanced

Updated October 21, 2026. Built against the tool’s current screens and checked step by step. [How we check this lesson](https://learn.ynteractive.com/content/about#how-we-check)

An [n8n](https://learn.ynteractive.com/content/tool/n8n) run that finishes with status success only tells you every node ran. It does not tell you the [invoice](https://learn.ynteractive.com/content/glossary/invoice) total is right. Truquence (github.com/cplj/truquence-public) is a free, open-source command-line tool that reads an exported [n8n execution](https://learn.ynteractive.com/content/glossary/execution) offline and compares each node's real output with a contract you wrote beforehand, then answers PASS, FAIL or UNKNOWN. In this free lesson you help a made-up accounting firm whose invoice run said success while the Total node output 12.0 instead of 120.0. You install Truquence, make the contract, write the expected output yourself and run the check. Every command comes from Truquence's own docs. This is my own lesson, not an official Truquence course.

## At a glance

| Question | Answer |
| --- | --- |
| What you build | A business case for a small firm whose n8n invoice run said success while the total was wrong: write down what each node should output, check the exported run with Truquence offline, and read PASS, FAIL or UNKNOWN. |
| Tools | Truquence |
| Time | About 11 minutes, 15 steps in 6 parts |
| Level | Advanced |
| Cost | Free |
| Ways to learn it | [Practice it step by step](https://learn.ynteractive.com/modules/truquence-n8n-acceptance), read the guide with screenshots |

### The 6 parts, in short

1. Green is not the same as right: The run says success, Put a price on it, Meet Truquence.
2. Set Truquence up once: Get the code, Install it in its own environment.
3. Write down what right looks like: Two files from n8n, Make the contract, Find the empty expectation, Write what Total should output.
4. Check the run: Run the check, FAIL: the total is wrong.
5. Fix it and check again: Fix it, then check again, Read the three answers.
6. What it saves: What this saves you, What it takes.

**Start here first:** [n8n: What Is n8n? Build Your First Workflow](https://learn.ynteractive.com/content/n8n-tutorial-for-beginners-first-workflow) (module 1 of n8n Automation Toolkit)

**In the course:** [Part 9 · n8n Automation Toolkit](https://learn.ynteractive.com/content/course/part-9-n8n-automation-toolkit) (Module 88 of the [full course](https://learn.ynteractive.com/content/course))

**Part of:** [Business Automations with n8n](https://learn.ynteractive.com/content/paths/business-automations-n8n) (step 22 of 22)

**Part of:** [n8n Jump Start](https://learn.ynteractive.com/content/paths/n8n-jump-start) (step 23 of 23)

**Part of:** [AI Apps Worth Knowing](https://learn.ynteractive.com/content/paths/partner-tools-ai-apps) (step 73 of 77)

**Part of:** [n8n Intermediate: Real Business Workflows](https://learn.ynteractive.com/content/paths/n8n-intermediate) (step 17 of 17)

## Truquence: Catch an n8n Run That Says Success but Gets It Wrong: step-by-step guide with screenshots

**About the screenshots.** They come from Stepthrough’s simulated practice environment (a practice copy of Truquence), not the live tool, so no real account appears. The buttons and labels match the real screens the lesson was built against. Practice it yourself free at learn.ynteractive.com.

- Tools: Truquence
- Time: about 11 minutes, 15 steps in 6 parts
- Level: advanced

### Part 1: Green is not the same as right

#### Step 1: The run says success

Meet Priya. She runs a small accounting firm. An [n8n workflow](https://learn.ynteractive.com/content/glossary/workflow) builds her client invoices. Last month, the run said success. Every node was green. But the total said twelve, where it should have said a hundred and twenty. Green means it ran. Not that it's right.

![Truquence in Stepthrough’s practice copy, step 1 of 15 (The run says success): the cursor is on “run”, highlighted.](https://learn.ynteractive.com/content/guide/truquence-n8n-acceptance/step-01.webp)

**Step 1 of 15.** Priya Nair runs Cedar Row Accounting (made up). An n8n workflow builds each client's monthly invoice. Last month's run finished with **status: success**, every node green. But the **Total** node passed along **12.0** where the invoice should say **120.0**. A green check means the node ran, not that the result is right. Click the **run**.

#### Step 2: Put a price on it

So Priya checks every invoice by hand. Forty a month, four minutes each. That's over two and a half hours. Skip it, and an invoice goes out for twelve dollars instead of a hundred and twenty. Use your own numbers here.

![Truquence in Stepthrough’s practice copy, step 2 of 15 (Put a price on it): the cursor is on “cost”, highlighted.](https://learn.ynteractive.com/content/guide/truquence-n8n-acceptance/step-02.webp)

**Step 2 of 15.** To stay safe, Priya spot-checks every invoice by hand: about 40 client invoices a month, 4 minutes each to spot-check the total by hand, so over 2.5 hours a month. If she skips it, the risk is an invoice that goes out for $12.00 instead of $120.00. These are example numbers, so swap in your own. Click the **cost**.

#### Step 3: Meet Truquence

Truquence is a free, open-source command-line tool. You give it an exported n8n run, and a file that says what each node should produce. It reads both offline. Then it answers pass, fail, or unknown. Nothing gets installed in your n8n.

![Truquence in Stepthrough’s practice copy, step 3 of 15 (Meet Truquence): the cursor is on “Truquence”, highlighted.](https://learn.ynteractive.com/content/guide/truquence-n8n-acceptance/step-03.webp)

**Step 3 of 15.** Truquence (github.com/cplj/truquence-public) is a free, open-source command-line tool. You give it an **exported n8n execution** and a file that says what each node **should** have produced. It reads both **offline** and answers **PASS**, **FAIL** or **UNKNOWN**. Nothing is installed in your n8n, and no input causes a network call or a workflow run. Every command ahead is copied from its own docs. Click the **Truquence** card.

### Part 2: Set Truquence up once

#### Step 4: Get the code

First, get the code. You need Git, Python three point ten or newer, and a terminal. Clone the Truquence repository, then move into its folder.

![Truquence in Stepthrough’s practice copy, step 4 of 15 (Get the code): the cursor is on “git clone”, highlighted.](https://learn.ynteractive.com/content/guide/truquence-n8n-acceptance/step-04.webp)

**Step 4 of 15.** Truquence's README lists what you need: **Git**, **Python 3.10 or newer** with venv and pip, and a **POSIX shell**, such as the Terminal on a Mac or Linux. Then: **git clone https://github.com/cplj/truquence-public.git** and **cd truquence-public**. Click the **git clone** line.

#### Step 5: Install it in its own environment

Now install it. One line makes a private Python environment, turns it on, and installs Truquence inside it. If you get an error, turn the environment on, and run the install again.

![Truquence in Stepthrough’s practice copy, step 5 of 15 (Install it in its own environment): the cursor is on “install”, highlighted.](https://learn.ynteractive.com/content/guide/truquence-n8n-acceptance/step-05.webp)

**Step 5 of 15.** Still from the README: **python3 -m venv .venv && . .venv/bin/activate && python3 -m pip install .** This makes a private Python environment, turns it on and installs Truquence into it. If you see *externally-managed-environment* or *command not found*, activate **.venv** and run the install again there. Click the **install** line.

### Part 3: Write down what right looks like

#### Step 6: Two files from n8n

Truquence needs two files from n8n. The exported workflow. And the full export of the run, with every node's output. A partial export comes back unknown.

![Truquence in Stepthrough’s practice copy, step 6 of 15 (Two files from n8n): the cursor is on “two files”, highlighted.](https://learn.ynteractive.com/content/guide/truquence-n8n-acceptance/step-06.webp)

**Step 6 of 15.** Truquence needs two files. **workflow.json** is the exported workflow: one workflow object, not a list. **execution.json** is the **full** execution export: one JSON object with **finished**, the **workflowData** snapshot and every node's output under **data.resultData.runData**. A workflow-only export, a copy of the console or a partial export comes back **UNKNOWN**. The docs' local n8n walkthrough (docs/local-n8n.md) shows one way to export a full run. Click the **two files**.

#### Step 7: Make the contract

Now make the contract. That's where you write down what right looks like. Init adds a check for every enabled node. Each one starts empty, as null.

![Truquence in Stepthrough’s practice copy, step 7 of 15 (Make the contract): the cursor is on “init”, highlighted.](https://learn.ynteractive.com/content/guide/truquence-n8n-acceptance/step-07.webp)

**Step 7 of 15.** Run **truquence init --workflow workflow.json --out contract.json**. The **contract** is where you write down what right looks like. *init* adds one check for **every enabled node**, and each starts with **x-expect_items: null**, meaning not decided yet. Click the **init** line.

#### Step 8: Find the empty expectation

Each check names a node, how many times it runs, and what it should output.

![Truquence in Stepthrough’s practice copy, step 8 of 15 (Find the empty expectation): the cursor is on “contract.json”, highlighted.](https://learn.ynteractive.com/content/guide/truquence-n8n-acceptance/step-08.webp)

**Step 8 of 15.** Open **contract.json**. Each check names a node, how many times it should run (**x-expect_runs**) and the items it should output (**x-expect_items**). The **x-workflow_sha256** line is a fingerprint of the workflow's settings, so a changed workflow cannot pass against an old contract. Click **null** on the **Total** check.

#### Step 9: Write what Total should output

Replace null with what Total should output. A total of a hundred and twenty. Work it out yourself, from the timesheet. Never copy it from the run you're checking. Do the same for every node, then save.

![Truquence in Stepthrough’s practice copy, step 9 of 15 (Write what Total should output): the cursor is on “new line”, highlighted.](https://learn.ynteractive.com/content/guide/truquence-n8n-acceptance/step-09.webp)

**Step 9 of 15.** Replace **null** with the items Total should output: **[{"total": 120.0}]**. Run counts, item counts, values and order must match exactly. Truquence's docs are firm: write the expected output **yourself**, for example from the client's timesheet, and **never copy it from the run you are checking**. An empty list **[]** means the node should output nothing. Do the same for every other node, then save. Click the **new line**.

### Part 4: Check the run

#### Step 10: Run the check

Now run the check. Accept compares every node's real output with your contract. It writes a report, and never overwrites an old one.

![Truquence in Stepthrough’s practice copy, step 10 of 15 (Run the check): the cursor is on “accept”, highlighted.](https://learn.ynteractive.com/content/guide/truquence-n8n-acceptance/step-10.webp)

**Step 10 of 15.** Run **truquence accept --format n8n --contract contract.json --execution execution.json --out run**. Truquence compares every node's real output with your contract, offline. It writes **run.json** and **run.md** and never overwrites an earlier report, so use a new name such as *run-2* next time. Click the **accept** line.

#### Step 11: FAIL: the total is wrong

Fail. Two checks passed, and one failed. The Total node. n8n said success. Truquence says the invoice is wrong, and tells you which node.

![Truquence in Stepthrough’s practice copy, step 11 of 15 (FAIL: the total is wrong): the cursor is on “Total”, highlighted.](https://learn.ynteractive.com/content/guide/truquence-n8n-acceptance/step-11.webp)

**Step 11 of 15.** **FAIL**, with exit code **1**. Two checks passed and one failed: **Total**, because the *exact JSON output items differ from expected*. n8n said success; Truquence says the invoice is wrong, and names the node. This is the run from Truquence's own docs example. Click the **Total** line.

### Part 5: Fix it and check again

#### Step 12: Fix it, then check again

Fix the node in n8n, run it again, and export the new run. If you changed the workflow, make a fresh contract, and fill it in again. With the right total, you get pass.

![Truquence in Stepthrough’s practice copy, step 12 of 15 (Fix it, then check again): the cursor is on “PASS”, highlighted.](https://learn.ynteractive.com/content/guide/truquence-n8n-acceptance/step-12.webp)

**Step 12 of 15.** Fix the Total node in n8n, run the workflow again and export the new execution. One rule from the docs: if you changed the **workflow itself**, its fingerprint changes too, so you need a **newly reviewed contract**: run *init* again and re-enter your expected items. Never just paste in the new fingerprint. With the right total, the check returns **PASS**, exit code **0**. Click **PASS**.

#### Step 13: Read the three answers

Pass is zero. Fail is one. Unknown is two, which means not enough to decide. Fail and unknown both block the invoice. And a person still signs off.

![Truquence in Stepthrough’s practice copy, step 13 of 15 (Read the three answers): the cursor is on “UNKNOWN”, highlighted.](https://learn.ynteractive.com/content/guide/truquence-n8n-acceptance/step-13.webp)

**Step 13 of 15.** **PASS** is exit 0. **FAIL** is exit 1. **UNKNOWN** is exit 2: not enough to decide, for example an expectation still **null**, an unfinished run or a missing snapshot. FAIL and UNKNOWN both **block acceptance**, so neither should let the invoice go out. And the report's **business_acceptance** is always *UNKNOWN*: Truquence checks the run against your contract, and a person still signs off. Click **UNKNOWN**.

### Part 6: What it saves

#### Step 14: What this saves you

![Truquence in Stepthrough’s practice copy, step 14 of 15 (What this saves you): the cursor is on “What this saves you”, highlighted.](https://learn.ynteractive.com/content/guide/truquence-n8n-acceptance/step-14.webp)

**Step 14 of 15.** Click **What this saves you**.

#### Step 15: What it takes

Truquence is open source, and runs on your own computer, with no account. It reads only the files you give it. Branching workflows still need a person to review.

![Truquence in Stepthrough’s practice copy, step 15 of 15 (What it takes): the cursor is on “card”, highlighted.](https://learn.ynteractive.com/content/guide/truquence-n8n-acceptance/step-15.webp)

**Step 15 of 15.** Truquence is open source under the **Apache-2.0** license, on GitHub at **github.com/cplj/truquence-public**. It runs on your own computer with no account, and reads only the files you give it. The n8n adapter covers JSON-only, single-branch nodes; workflows with untaken branches or binary items come back UNKNOWN and need a person. Click the **card**.

**Part of these free courses:** [n8n Jump Start](https://learn.ynteractive.com/courses/n8n-jump-start), [AI Apps Worth Knowing](https://learn.ynteractive.com/courses/ai-apps-worth-knowing), [n8n Intermediate: Real Business Workflows](https://learn.ynteractive.com/courses/n8n-intermediate), [AI Automation with n8n: From First Workflow to AI Agents](https://learn.ynteractive.com/courses/ai-automation-with-n8n)

### Now do it yourself, free

Reading the steps is a start. Doing them is how it sticks. The interactive lesson puts you in a practice copy of Truquence: you do every step yourself, it checks your work, and “Do it for me” finishes any step you get stuck on. Nothing touches your real accounts.

[Practice “Truquence: Catch an n8n Run That Says Success but Gets It Wrong” step by step](https://learn.ynteractive.com/modules/truquence-n8n-acceptance?after=guide)

## The business case: success is not the same as right

Picture Priya Nair, who runs Cedar Row Accounting, a made-up firm. An n8n workflow builds about 40 client invoices a month. Last month's run finished with status success and a green check on every node, but the Total node passed along 12.0 where the invoice should have said 120.0. To stay safe she spot-checks every total by hand, about 4 minutes each, so over 2.5 hours a month. These are example numbers, so use your own.

A green check means the node ran, not that the result is right. Truquence adds the missing question: did each node output exactly what you said it should?

## Step 1: install Truquence

Truquence's README lists Git, Python 3.10 or newer with venv and pip, and a POSIX shell. Clone the repository with git clone https://github.com/cplj/truquence-public.git, move into it with cd truquence-public, then run python3 -m venv .venv && . .venv/bin/activate && python3 -m pip install . to install it in its own environment. If you see externally-managed-environment or a missing command, activate .venv and install there again. The samples run offline without an account.

## Step 2: export the workflow and the full run

Truquence needs two files. workflow.json is one exported workflow object, not a list. execution.json is the full execution export: one JSON object with finished, an optional status, the workflowData snapshot and every node's output under data.resultData.runData. Workflow-only exports, console transcripts and incomplete exports come back UNKNOWN. The docs' local n8n walkthrough shows one way to export a complete run.

## Step 3: make the contract and write the answer key

Run truquence init --workflow workflow.json --out contract.json. The contract adds one check for every enabled node, each with x-expect_runs and x-expect_items set to null, plus x-workflow_sha256, a fingerprint of the workflow's runtime settings.

Replace each null with the items that node should output, for example [{"total": 120.0}] for Total. Run counts, item counts, values and order must match exactly, and an empty list means the node should output nothing. Truquence's docs are clear: do not generate the expected output from the execution you are accepting. Work it out from the source, such as the timesheet.

## Step 4: run the check and read the answer

Run truquence accept --format n8n --contract contract.json --execution execution.json --out run. In the docs' example, the execution reports status success but Total outputs 12.0 where the contract expects 120.0, and Truquence returns FAIL with exit code 1, counts of 2 PASS and 1 FAIL, and the reason that the exact JSON output items differ from expected. The same contract against a run with the right total returns PASS, exit code 0.

It writes run.json and run.md and never overwrites earlier files, so use a fresh prefix each time. No input causes a network call or a workflow run.

## Step 5: fix the workflow and check again

Fix the node in n8n, run it again and export the new execution. If you changed the workflow's runtime configuration, its fingerprint changes, and the docs say a changed configuration needs a newly reviewed contract: run init again and fill in your expected items again. Editor positions, notes and colors are ignored.

## Mistakes to avoid

- Treating UNKNOWN as fine. FAIL and UNKNOWN both block acceptance.
- Copying the expected output from the run you are checking. A wrong run will then pass.
- Leaving an expectation as null. It stays UNKNOWN.
- Checking a workflow-only export or a console transcript instead of a full execution export.
- Pasting a new fingerprint into an old contract after changing the workflow, instead of reviewing a new contract.
- Expecting Truquence to decide business acceptance. The report's business_acceptance is always UNKNOWN; a person still signs off.

## Links

- [Truquence on GitHub](https://github.com/cplj/truquence-public): the open-source tool this lesson teaches (Apache-2.0): README, quick start and exit codes.
- [Truquence workflow docs (n8n)](https://github.com/cplj/truquence-public/blob/main/docs/workflows.md): the n8n contract shape, what a full execution export needs, and the success-but-wrong example this lesson follows.
- [Truquence local n8n walkthrough](https://github.com/cplj/truquence-public/blob/main/docs/local-n8n.md): a full recipe that runs a small workflow in an isolated local n8n, exports the run and checks it.

## Try it yourself, free

Reading the steps is a start. Doing them is how it sticks. The interactive module walks you through every click in a practice copy of Truquence, checks each step, and never touches your real accounts.

[Start “Truquence: Catch an n8n Run That Says Success but Gets It Wrong”](https://learn.ynteractive.com/modules/truquence-n8n-acceptance)

## Frequently asked questions

**Is this an official Truquence course?**

No. This is my own lesson. Truquence is a separate, open-source project at github.com/cplj/truquence-public. Every command and output excerpt in the lesson comes from its README and docs.

**Does Truquence install anything in n8n?**

No. It reads the exported workflow and execution files offline on your own computer. No input causes a network call or a workflow run, and it never retries an action.

**What do PASS, FAIL and UNKNOWN mean?**

PASS (exit 0) means the run agrees with your contract. FAIL (exit 1) means it contradicts it, such as a wrong total. UNKNOWN (exit 2) means there is not enough to decide, such as an expectation left as null or an incomplete export. Exit 3 is an output error.

**Why did my run come back UNKNOWN?**

Common reasons from the docs: an expectation still null, a run that is unfinished or waiting, a missing workflow snapshot or node output, multiple output branches, binary items, or a file over 1 MiB. Conditional workflows with untaken branches need a person to review.

**Does it work with Make?**

Truquence has a Make scenario-log adapter, but it checks only the log's ID, reported status and operation count, not the outputs. This lesson covers the n8n adapter.

**What do I need to run it?**

Git, Python 3.10 or newer with venv and pip, and a POSIX shell, such as the macOS or Linux Terminal. No account is needed.

[Start this module free](https://learn.ynteractive.com/modules/truquence-n8n-acceptance)

- Previous in n8n Automation Toolkit: [n8n + Signatoro: AI Drafts Every Reply, Signatoro Signs It](https://learn.ynteractive.com/content/n8n-signatoro-ai-email-reply-signature)
- Next in n8n Automation Toolkit: [n8n + Felo: A Monday Research Brief With a Source for Every Answer](https://learn.ynteractive.com/content/n8n-felo-api-weekly-research-brief)

## More in n8n Automation Toolkit

- [n8n: What Is n8n? Build Your First Workflow](https://learn.ynteractive.com/content/n8n-tutorial-for-beginners-first-workflow): What n8n is and how it thinks, then your first workflow: a client inquiry form that catches every request and writes a one-line summary. No code, no accounts to connect.
- [AI Workflow Automation for Beginners: Sort Every Client Inquiry and Draft the Reply using n8n](https://learn.ynteractive.com/content/ai-workflow-automation-for-beginners): AI workflow automation for beginners: a form catches each client inquiry, an AI step sorts it and drafts the reply, and an If rule flags the urgent ones. Real n8n, free…
- [n8n: Items, JSON and Expressions, Explained by Doing](https://learn.ynteractive.com/content/n8n-items-json-expressions-tutorial): See how n8n holds data: pin five fake invoices, read them as items, Table and JSON, then write one reminder per invoice and a late fee with drag-and-drop expressions.
- [n8n: Run a Workflow on a Schedule (Every Monday at 8am)](https://learn.ynteractive.com/content/n8n-schedule-trigger-tutorial): Use the n8n Schedule Trigger to run a workflow by itself: every Monday at 8am, a timesheet reminder. Set the interval, test it now, and check the time zone.
- [n8n: Send Form Answers Straight to Google Sheets](https://learn.ynteractive.com/content/n8n-form-to-google-sheets): Build a consultation request form in n8n (required fields, email, dropdown), test it, and add every answer as a new row in Google Sheets. No webhook, no form tool to…
- [n8n: Summarize Customer Emails with OpenAI](https://learn.ynteractive.com/content/n8n-openai-summarize-emails): Your first AI step in n8n: send each customer email to OpenAI with one prompt and get a one-line summary plus the next step. No agent needed, about a cent of API use.

[All 25 modules in n8n Automation Toolkit](https://learn.ynteractive.com/content/course/n8n-automation-toolkit)

## From the blog

- [Truquence for n8n FAQ: Contracts, PASS, FAIL, UNKNOWN](https://learn.ynteractive.com/content/blog/truquence-n8n-check-faq): Plain answers about Truquence for n8n: why a green run can be wrong, what a contract is, which files to export and what PASS, FAIL and UNKNOWN mean.
- [Truquence for n8n: 8 Acceptance Check Mistakes](https://learn.ynteractive.com/content/blog/truquence-n8n-check-mistakes): Truquence mistakes that let a wrong n8n run through: copying the answer from the run, a partial export, treating UNKNOWN as fine and reusing old contracts.

[All blog posts](https://learn.ynteractive.com/content/blog)

## Terms in this lesson

Plain-English definitions, each with an example from a free lesson.

[Acceptance testing](https://learn.ynteractive.com/content/glossary/acceptance-testing) · [Golden dataset](https://learn.ynteractive.com/content/glossary/golden-dataset) · [Edge case](https://learn.ynteractive.com/content/glossary/edge-case) · [LLM observability](https://learn.ynteractive.com/content/glossary/llm-observability) · [Regression testing](https://learn.ynteractive.com/content/glossary/regression-testing) · [Invoice](https://learn.ynteractive.com/content/glossary/invoice)

[The full AI glossary](https://learn.ynteractive.com/content/glossary)

## Browse related tutorials

[n8n Automation Toolkit (25)](https://learn.ynteractive.com/content/course/n8n-automation-toolkit)