n8n-workflow-test

Validate an n8n workflow without running it. Catches the mistakes that normally only show up in production: broken connections, duplicate node names, orphan nodes that never run, and missing triggers.

Framework-agnostic. Zero runtime dependencies. Does not require n8n to be installed.

The problem

When you change an n8n workflow, the only real way to check you did not break it is to run the whole thing live. That means real Slack messages get sent, real rows get written, real emails go out, on real client data. If something is broken, the client often notices before you do.

n8n-workflow-test reads the workflow's JSON and checks it for structural problems at your desk, before it ever runs.

Install

npm install --save-dev n8n-workflow-test

Use

import { validateWorkflow } from "n8n-workflow-test";

const result = validateWorkflow(myWorkflowJson);

if (!result.valid) {
  console.log(result.errors);   // things that are broken
}
console.log(result.warnings);   // things that look suspicious

In a test (so a bad workflow fails CI)

import { assertValidWorkflow } from "n8n-workflow-test";
import workflow from "./workflows/onboarding.json" with { type: "json" };

test("onboarding workflow is structurally valid", () => {
  assertValidWorkflow(workflow); // throws, with a readable message, if broken
});

What it checks

Errors (these make a workflow invalid):

• The input is actually a workflow object with nodes and connections.
• The workflow is not empty.
• Every node has a name and a type.
• No two nodes share the same name (n8n keys connections by name).
• Every connection starts from and points to a node that actually exists.

Warnings (suspicious, but might be intentional):

• A node that is connected to nothing and will never run.
• A workflow with no trigger node, which cannot start on its own.

What this does NOT do (yet)

Kept deliberately small for v1. Planned for later:

• Mock running: executing the workflow's logic with fake stand-ins for the outside world, so you can confirm behaviour with zero real side effects.
• A CLI for running validation directly in CI without writing a test file.
• Deep parameter checks per node type.

License

MIT. See LICENSE.