@blucca/n8n-check 0.0.0-stage → 0.1.7

package/examples/vapi-tool-contract/success.case.json

@@ -0,0 +1,118 @@
+{
+  "version": 1,
+  "name": "Vapi tool contract: success",
+  "input": {
+    "node": "Vapi webhook",
+    "items": [
+      {
+        "body": {
+          "message": {
+            "type": "tool-calls",
+            "toolCallList": [
+              {
+                "id": "call-order-A",
+                "type": "function",
+                "function": {
+                  "name": "lookupOrders",
+                  "arguments": {
+                    "customerId": "customer-A"
+                  }
+                }
+              },
+              {
+                "id": "call-order-B",
+                "type": "function",
+                "function": {
+                  "name": "lookupOrders",
+                  "arguments": {
+                    "customerId": "customer-B"
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    ]
+  },
+  "stopAfter": "Build Vapi response",
+  "mocks": [
+    {
+      "node": "Lookup orders",
+      "url": "/lookup/{{ $json.customerId }}",
+      "routes": [
+        {
+          "method": "POST",
+          "path": "/lookup/customer-A",
+          "responses": [
+            {
+              "status": 200,
+              "json": {
+                "orders": [
+                  {
+                    "id": "order-A-101",
+                    "status": "shipped"
+                  }
+                ]
+              }
+            }
+          ],
+          "expect": {
+            "count": 1,
+            "bodies": [
+              {
+                "customerId": "customer-A",
+                "toolCallId": "call-order-A"
+              }
+            ]
+          }
+        },
+        {
+          "method": "POST",
+          "path": "/lookup/customer-B",
+          "responses": [
+            {
+              "status": 200,
+              "json": {
+                "orders": [
+                  {
+                    "id": "order-B-202",
+                    "status": "processing"
+                  }
+                ]
+              }
+            }
+          ],
+          "expect": {
+            "count": 1,
+            "bodies": [
+              {
+                "customerId": "customer-B",
+                "toolCallId": "call-order-B"
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ],
+  "assertions": [
+    {
+      "node": "Build Vapi response",
+      "equals": [
+        {
+          "results": [
+            {
+              "toolCallId": "call-order-A",
+              "result": "{\"orders\":[{\"id\":\"order-A-101\",\"status\":\"shipped\"}]}"
+            },
+            {
+              "toolCallId": "call-order-B",
+              "result": "{\"orders\":[{\"id\":\"order-B-202\",\"status\":\"processing\"}]}"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/examples/vapi-tool-contract/workflow.json

@@ -0,0 +1,143 @@
+{
+  "name": "Vapi tool-call contract \u2014 synthetic order lookup",
+  "nodes": [
+    {
+      "id": "vapi-webhook",
+      "name": "Vapi webhook",
+      "type": "n8n-nodes-base.webhook",
+      "typeVersion": 2.1,
+      "position": [
+        0,
+        0
+      ],
+      "parameters": {
+        "httpMethod": "POST",
+        "path": "vapi-tool-contract",
+        "responseMode": "responseNode",
+        "options": {}
+      }
+    },
+    {
+      "id": "split-tool-calls",
+      "name": "Split tool calls",
+      "type": "n8n-nodes-base.code",
+      "typeVersion": 2,
+      "position": [
+        220,
+        0
+      ],
+      "parameters": {
+        "mode": "runOnceForAllItems",
+        "jsCode": "const message = $input.first().json.body.message;\nif (message.type !== 'tool-calls' || !Array.isArray(message.toolCallList) || !message.toolCallList.length) throw new Error('Expected a non-empty tool-calls message');\nconst seen = new Set();\nreturn message.toolCallList.map(call => {\n  if (typeof call.id !== 'string' || !call.id || seen.has(call.id)) throw new Error('Each tool call needs a unique ID');\n  seen.add(call.id);\n  if (call.function?.name !== 'lookupOrders' || typeof call.function.arguments?.customerId !== 'string' || !/^[a-zA-Z0-9-]+$/.test(call.function.arguments.customerId)) throw new Error('Expected lookupOrders with a customerId');\n  return {json: {toolCallId: call.id, customerId: call.function.arguments.customerId}, pairedItem: {item: 0}};\n});"
+      }
+    },
+    {
+      "id": "lookup-orders",
+      "name": "Lookup orders",
+      "type": "n8n-nodes-base.httpRequest",
+      "typeVersion": 4.2,
+      "position": [
+        440,
+        0
+      ],
+      "parameters": {
+        "method": "POST",
+        "url": "=https://orders.example.invalid/lookup/{{ $json.customerId }}",
+        "sendBody": true,
+        "specifyBody": "json",
+        "jsonBody": "={{ {customerId: $json.customerId, toolCallId: $json.toolCallId} }}",
+        "options": {
+          "timeout": 5000,
+          "response": {
+            "response": {
+              "fullResponse": true,
+              "neverError": true,
+              "responseFormat": "json"
+            }
+          }
+        }
+      }
+    },
+    {
+      "id": "build-vapi-response",
+      "name": "Build Vapi response",
+      "type": "n8n-nodes-base.code",
+      "typeVersion": 2,
+      "position": [
+        660,
+        0
+      ],
+      "parameters": {
+        "mode": "runOnceForAllItems",
+        "jsCode": "const results = $input.all().map((item, index) => {\n  const { toolCallId } = $('Split tool calls').itemMatching(index).json;\n  if (item.json.statusCode === 503) return {toolCallId, error: 'Order service temporarily unavailable. Please try again later.'};\n  if (item.json.statusCode !== 200) return {toolCallId, error: 'Order lookup failed.'};\n  if (!Array.isArray(item.json.body?.orders)) return {toolCallId, error: 'Order service returned an invalid response.'};\n  return {toolCallId, result: JSON.stringify({orders: item.json.body.orders})};\n});\nreturn [{json: {results}}];"
+      }
+    },
+    {
+      "id": "respond-to-vapi",
+      "name": "Respond to Vapi",
+      "type": "n8n-nodes-base.respondToWebhook",
+      "typeVersion": 1.4,
+      "position": [
+        880,
+        0
+      ],
+      "parameters": {
+        "respondWith": "json",
+        "responseBody": "={{ $json }}",
+        "options": {
+          "responseCode": 200
+        }
+      }
+    }
+  ],
+  "connections": {
+    "Vapi webhook": {
+      "main": [
+        [
+          {
+            "node": "Split tool calls",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Split tool calls": {
+      "main": [
+        [
+          {
+            "node": "Lookup orders",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Lookup orders": {
+      "main": [
+        [
+          {
+            "node": "Build Vapi response",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Build Vapi response": {
+      "main": [
+        [
+          {
+            "node": "Respond to Vapi",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    }
+  },
+  "settings": {
+    "executionOrder": "v1"
+  },
+  "active": false
+}

package/examples/vapi-tool-contract/wrong-id.json

@@ -0,0 +1,143 @@
+{
+  "name": "Vapi tool-call contract \u2014 synthetic order lookup \u2014 wrong ID control",
+  "nodes": [
+    {
+      "id": "vapi-webhook",
+      "name": "Vapi webhook",
+      "type": "n8n-nodes-base.webhook",
+      "typeVersion": 2.1,
+      "position": [
+        0,
+        0
+      ],
+      "parameters": {
+        "httpMethod": "POST",
+        "path": "vapi-tool-contract",
+        "responseMode": "responseNode",
+        "options": {}
+      }
+    },
+    {
+      "id": "split-tool-calls",
+      "name": "Split tool calls",
+      "type": "n8n-nodes-base.code",
+      "typeVersion": 2,
+      "position": [
+        220,
+        0
+      ],
+      "parameters": {
+        "mode": "runOnceForAllItems",
+        "jsCode": "const message = $input.first().json.body.message;\nif (message.type !== 'tool-calls' || !Array.isArray(message.toolCallList) || !message.toolCallList.length) throw new Error('Expected a non-empty tool-calls message');\nconst seen = new Set();\nreturn message.toolCallList.map(call => {\n  if (typeof call.id !== 'string' || !call.id || seen.has(call.id)) throw new Error('Each tool call needs a unique ID');\n  seen.add(call.id);\n  if (call.function?.name !== 'lookupOrders' || typeof call.function.arguments?.customerId !== 'string' || !/^[a-zA-Z0-9-]+$/.test(call.function.arguments.customerId)) throw new Error('Expected lookupOrders with a customerId');\n  return {json: {toolCallId: call.id, customerId: call.function.arguments.customerId}, pairedItem: {item: 0}};\n});"
+      }
+    },
+    {
+      "id": "lookup-orders",
+      "name": "Lookup orders",
+      "type": "n8n-nodes-base.httpRequest",
+      "typeVersion": 4.2,
+      "position": [
+        440,
+        0
+      ],
+      "parameters": {
+        "method": "POST",
+        "url": "=https://orders.example.invalid/lookup/{{ $json.customerId }}",
+        "sendBody": true,
+        "specifyBody": "json",
+        "jsonBody": "={{ {customerId: $json.customerId, toolCallId: $json.toolCallId} }}",
+        "options": {
+          "timeout": 5000,
+          "response": {
+            "response": {
+              "fullResponse": true,
+              "neverError": true,
+              "responseFormat": "json"
+            }
+          }
+        }
+      }
+    },
+    {
+      "id": "build-vapi-response",
+      "name": "Build Vapi response",
+      "type": "n8n-nodes-base.code",
+      "typeVersion": 2,
+      "position": [
+        660,
+        0
+      ],
+      "parameters": {
+        "mode": "runOnceForAllItems",
+        "jsCode": "const results = $input.all().map((item, index) => {\n  const { toolCallId } = $('Split tool calls').itemMatching(index).json;\n  if (item.json.statusCode === 503) return {toolCallId, error: 'Order service temporarily unavailable. Please try again later.'};\n  if (item.json.statusCode !== 200) return {toolCallId, error: 'Order lookup failed.'};\n  if (!Array.isArray(item.json.body?.orders)) return {toolCallId, error: 'Order service returned an invalid response.'};\n  return {toolCallId, result: JSON.stringify({orders: item.json.body.orders})};\n});\nresults[1].toolCallId = results[0].toolCallId;\nreturn [{json: {results}}];"
+      }
+    },
+    {
+      "id": "respond-to-vapi",
+      "name": "Respond to Vapi",
+      "type": "n8n-nodes-base.respondToWebhook",
+      "typeVersion": 1.4,
+      "position": [
+        880,
+        0
+      ],
+      "parameters": {
+        "respondWith": "json",
+        "responseBody": "={{ $json }}",
+        "options": {
+          "responseCode": 200
+        }
+      }
+    }
+  ],
+  "connections": {
+    "Vapi webhook": {
+      "main": [
+        [
+          {
+            "node": "Split tool calls",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Split tool calls": {
+      "main": [
+        [
+          {
+            "node": "Lookup orders",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Lookup orders": {
+      "main": [
+        [
+          {
+            "node": "Build Vapi response",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Build Vapi response": {
+      "main": [
+        [
+          {
+            "node": "Respond to Vapi",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    }
+  },
+  "settings": {
+    "executionOrder": "v1"
+  },
+  "active": false
+}

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).