Pre-commit and CI

Two commands do the work in both places.

Pre-commit with lefthook

Add this to lefthook.yml in the repository that holds your workflows, then run npx lefthook install.

pre-commit:
  commands:
    workflow-tests-current:
      run: npx workflow-tester gen --check
    workflow-tests:
      run: npx workflow-tester run

When gen --check fails, run workflow-tester gen and commit the result.

GitHub Actions

name: workflow tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npx workflow-tester gen --check
      - run: npx workflow-tester run --format github-actions

--format github-actions puts each failure on the pull request as an annotation.

GitHub code scanning

      - run: npx workflow-tester run --format sarif > workflow-tester.sarif
        continue-on-error: true
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: workflow-tester.sarif

Each SARIF result names the workflow file and, when the case failed at a node, that node (a logical location and the line on which the workflow JSON names it). Results carry a partialFingerprints entry so GitHub keeps one alert per case across runs; the run records the workflow-tester version, an invocation with start and end times, and the node descriptions it ran against.

Other CI systems

npx workflow-tester run --format junit > results.xml

The JUnit file has one <testsuite> per workflow with its own counts and time, time on every case, and properties naming the workflow-tester version and the n8n node descriptions the run used.

Checking captures on a schedule

If you use captures, sync --once exits 1 when your n8n instance has run a workflow more recently than its committed capture.

      - run: npx workflow-tester sync --once --instance https://n8n.example.com
        env:
          N8N_API_KEY: ${{ secrets.N8N_API_KEY }}