Skip to content

The vouchfx ecosystem

vouchfx is a coordinated ecosystem of five repositories, each with an associated documentation site. This page maps the landscape, so you can find what you need and understand how the pieces fit together.

Overview

vouchfx is one engine and four companion repositories. The engine lives in the main repository and is the declarative YAML platform itself. The companions host reusable providers, production-grade sample applications, an opt-in telemetry backend, and an MCP server for AI-assisted test authoring.

Repository What it is Site Source
vouchfx (main) The engine: compiler, orchestration, CLI, provider SDK, core providers, and documentation https://vouchfx.io/ github.com/tomas-rampas/vouchfx
vouchfx-providers Community provider hub: registry, Vouched badge, conformance testing, examples https://providers.vouchfx.io/ github.com/tomas-rampas/vouchfx-providers
vouchfx-samples Four production-grade sample applications with complete test suites in C#, Python, Node.js and Java, plus worked migration examples (Postman, xUnit, SpecFlow) https://samples.vouchfx.io/ github.com/tomas-rampas/vouchfx-samples
vouchfx-telemetry-backend Opt-in telemetry backend: schema, deployment, verification, self-hosting guide https://telemetry.vouchfx.io/ github.com/tomas-rampas/vouchfx-telemetry-backend
vouchfx-mcp Model Context Protocol (MCP) server for AI-assisted test authoring: schema validation, step-type catalogue lookup, suite execution, and event-stream diagnostics https://vouchfx-mcp.vouchfx.io/ github.com/tomas-rampas/vouchfx-mcp

The vouchfx engine

The main repository — where the platform lives.

The engine comprises the YAML→AST→C#→Roslyn compiler, the Aspire/Testcontainers orchestration layer, the five-layer architecture, twenty-five Core providers across eleven families (HTTP, databases, message publishing and consumption, caches, storage, metrics, traces, mail, webhooks, scripts), the CLI, and the full set of design documentation.

Start here: - Getting started — 60-minute path to your first PASS - Recipes — Task-oriented, runnable patterns - Technical Architecture Blueprint — The five layers, orchestration, memory model, and the frozen provider contract - YAML DSL Specification — The .e2e.yaml grammar and VSCode extension

The community provider hub

For when you need a provider the engine doesn't bundle.

Two governance tiers (Core and Community) plus the maintainer-awarded Vouched badge. Submit your own provider via pull request and have it conformance-tested and listed.

Start here: - Consuming a provider — How to use a community provider in your suites - Implementing a provider — The complete journey from contract to conformance - Provider hub — Registry of all listed providers

Sample applications

Four production-grade services to learn from and fork.

Real microservices in C#, Python, Node.js and Java with complete end-to-end test suites demonstrating vouchfx patterns across multiple providers and technologies. Clone, run one command, see a complete suite execute.

The samples: - Orders (C# + ASP.NET) — REST, PostgreSQL, Kafka, webhooks - Inventory (Python + FastAPI) — HTTP, MySQL, RabbitMQ, Redis - Payments (Java + Spring Boot) — REST, SQL Server, NATS, email - Ledger (Node.js + JSON-RPC) — Custom community provider (rpc.json-rpc), PostgreSQL, Kafka

Start here: - Run a sample — Clone and run any sample in minutes - Migrating to vouchfx — Worked examples porting a Postman collection, an xUnit integration test and a SpecFlow feature, each with a field-by-field mapping table - Custom runner — How the Ledger sample uses a custom runner to consume the Community provider

The telemetry backend

Opt-in, privacy-first usage analytics — optional and self-hostable.

The telemetry system is privacy-first and OFF by default. When enabled, it collects anonymous aggregate counts (tool versions, verdict tallies, which Core step kinds ran, startup timings, a count of unreadable event-stream lines) — never your test contents, secrets, URLs, or data.

A reference backend implementing the frozen ingest contract is open-source and available for self-hosting.

Start here: - Why telemetry? — What is collected, what is never collected, the privacy guarantees - Self-hosting — Deploy your own telemetry backend - Verify what would be sent — Inspect your local outbox before any data leaves your machine - Privacy — Data retention, deletion, and consent model

For configuration details and backend availability, see Telemetry & privacy in the main engine documentation.

The MCP companion

AI-assisted test authoring — published local server, available as the Vouchfx.Mcp .NET tool.

A local, stdio-first Model Context Protocol (MCP) server that integrates vouchfx into AI coding agents and other MCP clients (such as Claude Code), with an optional HTTP transport. It exposes eighteen tools, four prompts, four concrete resources and seven URI templates covering six families, so agents can work with .e2e.yaml suites and run evidence through structured interfaces.

validate_suite, normalize_suite, search_docs and explain_diagnostic need no CLI. get_schema serves the embedded schema offline and optionally cross-checks a matching CLI. The live catalogue tools (list_step_types, describe_step_type), plan_coverage, scaffold_suite and run_suite require the pinned CLI. Run diagnostics, events, timelines and artefact inspection read existing run evidence; status and listing read the run registry, and cancellation requests an existing in-process run to stop. These inspection tools do not start another CLI run. See the server's overview for the full tool/resource inventory and its runtime requirements for each dependency class.

CLI-backed tools refuse an installed version that does not match the pinned engine release (ENGINE_PIN); authoring tools and evidence readers retain their documented CLI-free behaviour. The server runs suites out-of-process and bounds subprocess execution. It relays the engine's already-redacted event evidence with documented sanitisation and size bounds, without resolving ${secret:...} references itself or echoing its process environment into tool results, progress notifications or resources.

The server is published on NuGet as the .NET tool Vouchfx.Mcp, which provides the vouchfx-mcp command and wraps the published vouchfx CLI at a pinned engine release. Install the latest stable tool with dotnet tool install --global Vouchfx.Mcp; see Install & register for the full setup.

Start here: - MCP Server documentation — Installation, tools and resources, troubleshooting - Overview — What the server wraps, how it is pinned, and its current status - Install & register — Set up the server for use with Claude Code or other MCP clients - Tools & resources — Reference for all eighteen tools, four concrete resources and seven URI templates - Troubleshooting — Debugging common issues - GitHub repository — Source, development status, and roadmap

Where to ask questions