@blucca/n8n-check 0.0.0-stage → 0.1.6

package/examples/stop-after/observed-results.json

@@ -0,0 +1,162 @@
+{
+  "description": "Synthetic full Sheets-to-Slack exports; only the fixture and business transformation run. Real n8n, loopback-only network.",
+  "files": {
+    "fixed.json": "a20e75366252c5cd165821eeca8b54671b69df51242fe6e6c3f847bc7d651ec6",
+    "broken.json": "899bb0f39ce8f494b9f44e9b4b79874f93065b4bc379fab970aad90ee907ed14",
+    "case.json": "81fe5dcca0b261ca97fb7cff1d27ce5a177ffbb61aeec7c75cb1c63fb28f0ded"
+  },
+  "runs": {
+    "fixed": {
+      "runnerVersion": "0.1.5",
+      "n8nVersion": "2.41.7",
+      "nodeVersion": "v26.10.0",
+      "startedAt": "2026-10-06T22:13:13.515Z",
+      "status": "passed",
+      "exitCode": 0,
+      "checks": [
+        {
+          "name": "n8n execution succeeds",
+          "passed": true,
+          "actual": {
+            "cliExitCode": 0,
+            "lastNode": "Prepare notification",
+            "executionFound": true
+          }
+        },
+        {
+          "name": "Prepare notification: output 0",
+          "passed": true,
+          "expected": [
+            {
+              "invoiceId": "INV-42",
+              "text": "Invoice INV-42: $650.00"
+            },
+            {
+              "invoiceId": "INV-43",
+              "text": "Invoice INV-43: $120.50"
+            }
+          ],
+          "actual": [
+            {
+              "invoiceId": "INV-42",
+              "text": "Invoice INV-42: $650.00"
+            },
+            {
+              "invoiceId": "INV-43",
+              "text": "Invoice INV-43: $120.50"
+            }
+          ]
+        },
+        {
+          "name": "mock: all requests match routes",
+          "passed": true,
+          "actual": []
+        },
+        {
+          "name": "mock: request limits and server",
+          "passed": true,
+          "actual": []
+        }
+      ],
+      "network": {
+        "mode": "loopback-only",
+        "enforced": true,
+        "interfaces": [
+          "lo"
+        ]
+      },
+      "preparation": {
+        "inputNode": "Read invoices",
+        "changes": [
+          {
+            "node": "Read invoices",
+            "change": "replace with fixture JSON items"
+          },
+          {
+            "node": "Prepare notification",
+            "change": "stop this branch after the node; remove outgoing connections; retain independently reachable branches"
+          }
+        ],
+        "omittedNodes": [
+          "Start",
+          "Notify team"
+        ]
+      },
+      "requests": []
+    },
+    "broken": {
+      "runnerVersion": "0.1.5",
+      "n8nVersion": "2.41.7",
+      "nodeVersion": "v26.10.0",
+      "startedAt": "2026-10-06T22:13:22.755Z",
+      "status": "failed",
+      "exitCode": 1,
+      "checks": [
+        {
+          "name": "n8n execution succeeds",
+          "passed": true,
+          "actual": {
+            "cliExitCode": 0,
+            "lastNode": "Prepare notification",
+            "executionFound": true
+          }
+        },
+        {
+          "name": "Prepare notification: output 0",
+          "passed": false,
+          "expected": [
+            {
+              "invoiceId": "INV-42",
+              "text": "Invoice INV-42: $650.00"
+            },
+            {
+              "invoiceId": "INV-43",
+              "text": "Invoice INV-43: $120.50"
+            }
+          ],
+          "actual": [
+            {
+              "invoiceId": "INV-42",
+              "text": "Invoice INV-42: $650.00"
+            }
+          ]
+        },
+        {
+          "name": "mock: all requests match routes",
+          "passed": true,
+          "actual": []
+        },
+        {
+          "name": "mock: request limits and server",
+          "passed": true,
+          "actual": []
+        }
+      ],
+      "network": {
+        "mode": "loopback-only",
+        "enforced": true,
+        "interfaces": [
+          "lo"
+        ]
+      },
+      "preparation": {
+        "inputNode": "Read invoices",
+        "changes": [
+          {
+            "node": "Read invoices",
+            "change": "replace with fixture JSON items"
+          },
+          {
+            "node": "Prepare notification",
+            "change": "stop this branch after the node; remove outgoing connections; retain independently reachable branches"
+          }
+        ],
+        "omittedNodes": [
+          "Start",
+          "Notify team"
+        ]
+      },
+      "requests": []
+    }
+  }
+}

package/examples/version-matrix/README.md

@@ -0,0 +1,65 @@
+# Check the workflow before upgrading n8n
+
+**Keep the workflow and expected behavior fixed. Change the n8n version. Inspect what changes.**
+
+n8n-check's Action accepts `n8n-version`, starting with v0.1.4. A GitHub matrix runs your case against the release you deploy today and the release you want to adopt. Each job produces its own version-labelled summary and JSON/JUnit artifacts.
+
+## Use your own workflow
+
+1. Export the workflow and [build a case](https://blucca.github.io/n8n-check/) with synthetic inputs, HTTP responses, and expected behavior.
+2. Copy [`upgrade-check.yml`](upgrade-check.yml) to `.github/workflows/n8n-upgrade.yml` in your repository.
+3. Set the two `matrix.n8n` versions and the `workflow` / `case` file paths.
+4. Commit and inspect both jobs. `fail-fast: false` preserves the other result when one version fails.
+
+The supplied workflow treats every failed contract as a failed job. Both artifact names include the version, so the reports stay separate. Review a mismatch against your intended behavior before changing the expectation. A failing deployed baseline identifies an existing workflow or engine behavior worth addressing before the upgrade.
+
+The HTTP responses remain controlled local fixtures. Real credentials, provider behavior, triggers, and production data remain separate integration checks. Node types and parameters must exist in each selected n8n release. Data Table initialization adapters in other examples retain their own explicit version bounds.
+
+## A real version difference: a missing PROPFIND body
+
+The author of [n8n #39395](https://github.com/n8n-io/n8n/issues/39395) supplied a Nextcloud workflow on **2.38.4**, where PROPFIND silently drops the request's XML body. Upstream [PR #24151](https://github.com/n8n-io/n8n/pull/24151) adds body handling for this method; **2.41.7** preserves it.
+
+The [workflow and exact-body case](../propfind-body/) use the author's HTTP Request 4.5 parameters and complete 698-character diagnostic XML. The fixture replaces connection information with synthetic values and redirects the URL to a local capture server. This compares the actual released engines with the same export and expected body.
+
+### Observed on October 7, 2026
+
+| Same export and expected XML | n8n 2.38.4 | n8n 2.41.7 |
+|---|---|---|
+| Engine execution | Success | Success |
+| PROPFIND requests | 1 | 1 |
+| Captured body | Empty (`null`) | All 698 characters |
+| Contract | **5/6 · exit 1** | **6/6 · exit 0** |
+
+[Actual GitHub matrix run](https://github.com/blucca/n8n-check/actions/runs/37524798259) · [Versioned JSON record, requests and assertions](observed-results.json)
+
+Both jobs used n8n-check 0.1.4, the same file hashes, and loopback-only networking. The record also includes a separate n8n **2.37.9** smoke check: the object-valued JSON request case passes 6/6 with two complete requests and outputs. This checks the selected runtime path; each project's own nodes and contracts supply its upgrade coverage.
+
+To run the recorded comparison in your fork:
+
+1. Fork n8n-check and enable Actions.
+2. Choose **Compare n8n versions on a real PROPFIND regression → Run workflow**.
+3. Inspect the contract step summary and download `propfind-n8n-2.38.4` and `propfind-n8n-2.41.7`.
+
+[Comparison workflow source](../../.github/workflows/compare-versions.yml)
+
+This demonstration allows the known older-version contract failure, then asserts the specific missing-body difference. The copyable `upgrade-check.yml` above keeps ordinary strict pass/fail gating for your project.
+
+## Local version selection
+
+```sh
+git clone --branch v0.1.4 https://github.com/blucca/n8n-check.git
+cd n8n-check
+docker build --build-arg N8N_VERSION=2.38.4 -t n8n-check:2.38.4 .
+docker run --rm --network none -v "$PWD:/work" n8n-check:2.38.4 \
+  examples/propfind-body/workflow.json examples/propfind-body/case.json \
+  --out /work/results/2.38.4
+# Expected: exit 1, with the request-body assertion failing.
+```
+
+Repeat with `2.41.7` for the complete-body contract. Linux users with a UID other than 1000 can add `--user "$(id -u):$(id -g)"` to `docker run`.
+
+Runtime images come from `ghcr.io/n8n-io/n8n`. The default is 2.41.7; supply an exact available release. Every report records the actual `n8nVersion`, `runnerVersion`, and `nodeVersion`.
+
+---
+
+**Have a client upgrade to ship?** The [$650 implementation pilot](https://blucca.github.io/n8n-release-checks/) supplies an agreed fixture pack and handoff for one workflow or slice. Send the deployed version, target version, workflow purpose, and release date to [belgialucca@gmail.com](mailto:belgialucca@gmail.com?subject=n8n%20upgrade%20check).

package/examples/version-matrix/observed-results.json

@@ -0,0 +1,307 @@
+{
+  "recordedAt": "2026-10-06T20:17:00Z",
+  "sourceCommit": "77e496f65105d5633374a65f63da990ab76ff4de",
+  "runUrl": "https://github.com/blucca/n8n-check/actions/runs/37524798259",
+  "sourceIssue": "https://github.com/n8n-io/n8n/issues/39395",
+  "inputs": {
+    "examples/propfind-body/workflow.json": "f365021255ae250b287848de1bb14c47ed2a244127957268044643ab956156e8",
+    "examples/propfind-body/case.json": "e37304adb5eacfad5ca773a77510505a8c3c89f1be451854d3b61e63a7029add"
+  },
+  "runs": [
+    {
+      "name": "Issue 39395 - PROPFIND transmits its XML body",
+      "startedAt": "2026-10-06T20:14:31.865Z",
+      "n8nVersion": "2.38.4",
+      "runnerVersion": "0.1.4",
+      "nodeVersion": "v26.7.0",
+      "network": {
+        "mode": "loopback-only",
+        "enforced": true,
+        "interfaces": [
+          "lo"
+        ]
+      },
+      "status": "failed",
+      "exitCode": 1,
+      "checks": [
+        {
+          "name": "n8n execution succeeds",
+          "passed": true,
+          "actual": {
+            "cliExitCode": 0,
+            "lastNode": "HTTP Request",
+            "executionFound": true
+          }
+        },
+        {
+          "name": "HTTP Request: output 0",
+          "passed": true,
+          "expected": [
+            {
+              "received": true
+            }
+          ],
+          "actual": [
+            {
+              "received": true
+            }
+          ]
+        },
+        {
+          "name": "mock: all requests match routes",
+          "passed": true,
+          "actual": []
+        },
+        {
+          "name": "mock: request limits and server",
+          "passed": true,
+          "actual": []
+        },
+        {
+          "name": "HTTP Request: PROPFIND /dav request count",
+          "passed": true,
+          "expected": 1,
+          "actual": 1
+        },
+        {
+          "name": "HTTP Request: PROPFIND /dav request bodies",
+          "passed": false,
+          "expected": [
+            "<?xml version=\"1.0\"?>\n<invalid>\n<d:propfind xmlns:d=\"DAV:\" xmlns:oc=\"http://owncloud.org/ns\" xmlns:nc=\"http://nextcloud.org/ns\">\n    <d:prop>\n        <d:creationdate />\n        <nc:upload_time />\n        <d:getlastmodified />\n        <d:getetag />\n        <d:getcontenttype />\n        <d:resourcetype />\n        <d:quota-used-bytes />\n        <d:quota-available-bytes />\n        <d:displayname />\n        <nc:has-preview />\n        <oc:id />\n        <oc:fileid />\n        <oc:permissions />\n        <oc:size />\n        <oc:favorite />\n        <oc:tags />\n        <oc:comments-unread />\n        <oc:owner-id />\n        <oc:owner-display-name />\n        <oc:share-types />\n    </d:prop>\n</d:propfind>"
+          ],
+          "actual": [
+            null
+          ]
+        }
+      ],
+      "requests": [
+        {
+          "node": "HTTP Request",
+          "method": "PROPFIND",
+          "path": "/dav",
+          "body": null,
+          "matched": true,
+          "status": 200,
+          "response": {
+            "received": true
+          }
+        }
+      ]
+    },
+    {
+      "name": "Issue 39395 - PROPFIND transmits its XML body",
+      "startedAt": "2026-10-06T20:14:26.062Z",
+      "n8nVersion": "2.41.7",
+      "runnerVersion": "0.1.4",
+      "nodeVersion": "v26.7.0",
+      "network": {
+        "mode": "loopback-only",
+        "enforced": true,
+        "interfaces": [
+          "lo"
+        ]
+      },
+      "status": "passed",
+      "exitCode": 0,
+      "checks": [
+        {
+          "name": "n8n execution succeeds",
+          "passed": true,
+          "actual": {
+            "cliExitCode": 0,
+            "lastNode": "HTTP Request",
+            "executionFound": true
+          }
+        },
+        {
+          "name": "HTTP Request: output 0",
+          "passed": true,
+          "expected": [
+            {
+              "received": true
+            }
+          ],
+          "actual": [
+            {
+              "received": true
+            }
+          ]
+        },
+        {
+          "name": "mock: all requests match routes",
+          "passed": true,
+          "actual": []
+        },
+        {
+          "name": "mock: request limits and server",
+          "passed": true,
+          "actual": []
+        },
+        {
+          "name": "HTTP Request: PROPFIND /dav request count",
+          "passed": true,
+          "expected": 1,
+          "actual": 1
+        },
+        {
+          "name": "HTTP Request: PROPFIND /dav request bodies",
+          "passed": true,
+          "expected": [
+            "<?xml version=\"1.0\"?>\n<invalid>\n<d:propfind xmlns:d=\"DAV:\" xmlns:oc=\"http://owncloud.org/ns\" xmlns:nc=\"http://nextcloud.org/ns\">\n    <d:prop>\n        <d:creationdate />\n        <nc:upload_time />\n        <d:getlastmodified />\n        <d:getetag />\n        <d:getcontenttype />\n        <d:resourcetype />\n        <d:quota-used-bytes />\n        <d:quota-available-bytes />\n        <d:displayname />\n        <nc:has-preview />\n        <oc:id />\n        <oc:fileid />\n        <oc:permissions />\n        <oc:size />\n        <oc:favorite />\n        <oc:tags />\n        <oc:comments-unread />\n        <oc:owner-id />\n        <oc:owner-display-name />\n        <oc:share-types />\n    </d:prop>\n</d:propfind>"
+          ],
+          "actual": [
+            "<?xml version=\"1.0\"?>\n<invalid>\n<d:propfind xmlns:d=\"DAV:\" xmlns:oc=\"http://owncloud.org/ns\" xmlns:nc=\"http://nextcloud.org/ns\">\n    <d:prop>\n        <d:creationdate />\n        <nc:upload_time />\n        <d:getlastmodified />\n        <d:getetag />\n        <d:getcontenttype />\n        <d:resourcetype />\n        <d:quota-used-bytes />\n        <d:quota-available-bytes />\n        <d:displayname />\n        <nc:has-preview />\n        <oc:id />\n        <oc:fileid />\n        <oc:permissions />\n        <oc:size />\n        <oc:favorite />\n        <oc:tags />\n        <oc:comments-unread />\n        <oc:owner-id />\n        <oc:owner-display-name />\n        <oc:share-types />\n    </d:prop>\n</d:propfind>"
+          ]
+        }
+      ],
+      "requests": [
+        {
+          "node": "HTTP Request",
+          "method": "PROPFIND",
+          "path": "/dav",
+          "body": "<?xml version=\"1.0\"?>\n<invalid>\n<d:propfind xmlns:d=\"DAV:\" xmlns:oc=\"http://owncloud.org/ns\" xmlns:nc=\"http://nextcloud.org/ns\">\n    <d:prop>\n        <d:creationdate />\n        <nc:upload_time />\n        <d:getlastmodified />\n        <d:getetag />\n        <d:getcontenttype />\n        <d:resourcetype />\n        <d:quota-used-bytes />\n        <d:quota-available-bytes />\n        <d:displayname />\n        <nc:has-preview />\n        <oc:id />\n        <oc:fileid />\n        <oc:permissions />\n        <oc:size />\n        <oc:favorite />\n        <oc:tags />\n        <oc:comments-unread />\n        <oc:owner-id />\n        <oc:owner-display-name />\n        <oc:share-types />\n    </d:prop>\n</d:propfind>",
+          "matched": true,
+          "status": 200,
+          "response": {
+            "received": true
+          }
+        }
+      ]
+    }
+  ],
+  "additionalRuntimeSmoke": {
+    "name": "Two render requests preserve object options",
+    "startedAt": "2026-10-06T20:12:16.116Z",
+    "n8nVersion": "2.37.9",
+    "runnerVersion": "0.1.4",
+    "nodeVersion": "v26.5.1",
+    "network": {
+      "mode": "loopback-only",
+      "enforced": true,
+      "interfaces": [
+        "lo"
+      ]
+    },
+    "status": "passed",
+    "exitCode": 0,
+    "checks": [
+      {
+        "name": "n8n execution succeeds",
+        "passed": true,
+        "actual": {
+          "cliExitCode": 0,
+          "lastNode": "Render",
+          "executionFound": true
+        }
+      },
+      {
+        "name": "Render: output 0",
+        "passed": true,
+        "expected": [
+          {
+            "id": "render-42"
+          },
+          {
+            "id": "render-43"
+          }
+        ],
+        "actual": [
+          {
+            "id": "render-42"
+          },
+          {
+            "id": "render-43"
+          }
+        ]
+      },
+      {
+        "name": "mock: all requests match routes",
+        "passed": true,
+        "actual": []
+      },
+      {
+        "name": "mock: request limits and server",
+        "passed": true,
+        "actual": []
+      },
+      {
+        "name": "Render: POST /renders request count",
+        "passed": true,
+        "expected": 2,
+        "actual": 2
+      },
+      {
+        "name": "Render: POST /renders request bodies",
+        "passed": true,
+        "expected": [
+          {
+            "shortId": 42,
+            "renderOptions": {
+              "color": "#112233",
+              "fontSize": 31
+            }
+          },
+          {
+            "shortId": 43,
+            "renderOptions": {
+              "color": "#aabbcc",
+              "fontSize": 47
+            }
+          }
+        ],
+        "actual": [
+          {
+            "shortId": 42,
+            "renderOptions": {
+              "color": "#112233",
+              "fontSize": 31
+            }
+          },
+          {
+            "shortId": 43,
+            "renderOptions": {
+              "color": "#aabbcc",
+              "fontSize": 47
+            }
+          }
+        ]
+      }
+    ],
+    "requests": [
+      {
+        "node": "Render",
+        "method": "POST",
+        "path": "/renders",
+        "body": {
+          "shortId": 42,
+          "renderOptions": {
+            "color": "#112233",
+            "fontSize": 31
+          }
+        },
+        "matched": true,
+        "status": 200,
+        "response": {
+          "id": "render-42"
+        }
+      },
+      {
+        "node": "Render",
+        "method": "POST",
+        "path": "/renders",
+        "body": {
+          "shortId": 43,
+          "renderOptions": {
+            "color": "#aabbcc",
+            "fontSize": 47
+          }
+        },
+        "matched": true,
+        "status": 200,
+        "response": {
+          "id": "render-43"
+        }
+      }
+    ]
+  }
+}

package/examples/version-matrix/upgrade-check.yml

@@ -0,0 +1,32 @@
+# Save as .github/workflows/n8n-upgrade.yml in your own repository.
+# Replace both releases and both file paths with your project's values.
+name: n8n upgrade contract
+on: [push, pull_request, workflow_dispatch]
+permissions:
+  contents: read
+jobs:
+  contract:
+    name: n8n ${{ matrix.n8n }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        n8n: ['2.38.4', '2.41.7']
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: blucca/n8n-check@v0.1.4
+        with:
+          n8n-version: ${{ matrix.n8n }}
+          workflow: workflows/workflow.json
+          case: tests/workflow.case.json
+          out: results/contract
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: n8n-contract-${{ matrix.n8n }}
+          path: |
+            results/contract/report.json
+            results/contract/junit.xml

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@blucca/n8n-check",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.6",
+  "description": "Run n8n workflow regression checks with fixtures, local HTTP mocks and JUnit reports.",
+  "type": "module",
+  "bin": {
+    "n8n-check": "bin/n8n-check.mjs"
+  },
+  "exports": "./src/runner.mjs",
+  "files": [
+    "bin",
+    "src",
+    "examples",
+    "Dockerfile",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "author": "blucca",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blucca/n8n-check.git"
+  },
+  "homepage": "https://github.com/blucca/n8n-check#readme",
+  "bugs": "https://github.com/blucca/n8n-check/issues",
+  "keywords": [
+    "n8n",
+    "testing",
+    "workflow",
+    "regression",
+    "junit",
+    "mock"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}