Skip to content

The vouchfx ecosystem

vouchfx is a coordinated ecosystem of four repositories and associated documentation sites. 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 three companion repositories. The engine lives in the main repository and is the declarative YAML platform itself. The three companions host reusable providers, production-grade sample applications, and an opt-in telemetry backend.

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

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

Where to ask questions