vouchfx-samples¶

Real-world working samples for vouchfx — the engine that compiles declarative .e2e.yaml integration tests into C#, orchestrates your full container topology with .NET Aspire, and proves a distributed system works end-to-end. Clone this repository, run one command, and watch vouchfx test a real polyglot system: REST API calls fanning out into database writes, broker events, cache entries, and outbound webhooks — all in one coherent business-transaction narrative, all proven end-to-end.

The Sample Catalogue¶

Application samples drive a business transaction through a real service and its database, broker or cache. Infrastructure-only samples exercise a dependency directly. Browse the providers and technology pairing for each:

Sample	Language / Stack	Transaction Under Test	vouchfx Providers Exercised
orders-dotnet	ASP.NET Core 8 + C#	Customer places order → Postgres row → Kafka event → outbound webhook callback	`http.rest`, `db-assert.postgres`, `mq-expect.kafka`, `webhook-listen.http`
orders-dotnet-compose	Shared ASP.NET Core 8 app + user-supplied Compose	The same five assertions with Compose-owned PostgreSQL, Kafka and callback routing; supported by the pinned source engine	`http.rest`, `db-assert.postgres`, `mq-expect.kafka`, `webhook-listen.http`
inventory-python	FastAPI + Python 3.12	Create item → MySQL row + Redis cache entry → RabbitMQ event	`http.rest`, `db-assert.mysql`, `cache-assert.redis`, `mq-expect.rabbitmq`
payments-java	Spring Boot 3.3 + Java 17	Authorise payment → SQL Server row → NATS JetStream event → SMTP receipt email	`http.rest`, `db-assert.sqlserver`, `mq-expect.nats`, `mail-expect.smtp`
ledger-jsonrpc	Node.js 22 + JSON-RPC 2.0	Ledger transactions (REST) → Postgres row → Kafka event → independent worker role consuming an injected adjustment	`rpc.json-rpc` (Community), `db-assert.postgres`, `mq-publish.kafka`, `mq-expect.kafka`, `script.csharp` — custom runner
kafka-mtls	Kafka + PEM certificates	Produce and consume over a mutually authenticated broker listener	`mq-publish.kafka`, `mq-expect.kafka`

Each sample's README.md walks through the transaction, the code, the suite design, and what success looks like.

Migrating from an existing test estate? migrations/ holds three worked porting examples — a Postman collection, a hand-rolled xUnit integration test, and a SpecFlow feature — each pairing the genuine before-artefact with a runnable .e2e.yaml port and a field-by-field mapping table. The guide is published at Migrating to vouchfx; run all three ported suites with scripts/run-migrations.sh (or .ps1).

Quick Start¶

Prerequisites: .NET 8 SDK (8.0.424+), Docker with Linux containers, Git. See docs/RUNNING.md for the full list and background.

This checkout selects the source commit in ENGINE_PIN. See the Core 1.0.7 source validation record for the current source results. The Core 1.0.6 acceptance record preserves historical source and official installed-package evidence. ledger-jsonrpc retains its custom source runner; source and installed-package runs are separate evidence.

Two commands from the repository root:

# 1. Fetch and build the pinned vouchfx engine (one-time)
./scripts/bootstrap.sh

# 2. Build a sample's Docker image and run its suite
./scripts/run-sample.sh orders-dotnet

On Windows (PowerShell):

.\scripts\bootstrap.ps1
.\scripts\run-sample.ps1 orders-dotnet

After bootstrapping, run all six samples sequentially in source mode. Supply a fresh disposable credential for the Compose variant:

unset VOUCHFX_SAMPLES_CLI VOUCHFX_SAMPLES_CLI_VERSION
read -rsp 'Isolated database password: ' VOUCHFX_COMPOSE_PASSWORD; printf '\n'
export VOUCHFX_COMPOSE_PASSWORD
./scripts/run-sample.sh all

all enumerates all six sample directories, including orders-dotnet-compose, which the pinned source engine supports. Installed CLI mode refuses ledger-jsonrpc because it needs its custom source runner, so installed all reports a nonzero result. Run that custom-provider sample separately in source mode; see candidate selection and custom-runner limits.

The Kafka mutual-TLS sample documents its certificate setup and broker prerequisites. The runner invokes its setup script before running the suite.

To validate an installed CLI candidate, set VOUCHFX_SAMPLES_CLI to its executable path or command name and VOUCHFX_SAMPLES_CLI_VERSION to the exact version declared by that candidate. Both runners check --version before setup or Docker, and bypass source bootstrap entirely. See installed candidate validation for commands and the custom-provider limitation. This mode does not use ENGINE_PIN.

Reports land in out/:

out/<sample>-results.xml — JUnit XML (for IDE test-result integrations and CI)
out/<sample>-report.html — self-contained HTML report; open directly in a browser

How the Samples Configure the System Under Test¶

Each suite declares the services it tests and the infrastructure it needs in its environment: block. Here's an excerpt from the orders-dotnet sample:

environment:
  services:
    orders-api:
      image: vouchfx-samples-orders-dotnet:local
      httpPort: 8080
      env:
        ConnectionStrings__orders: "${conn:ordersdb}"
        KAFKA_BOOTSTRAP: "${conn:broker}"

  dependencies:
    ordersdb:
      type: postgres
    broker:
      type: kafka

The engine resolves ${conn:<dependency>} and ${conn:<dependency>.<field>} tokens (e.g. .host, .port, .database, .username, .password) to container-reachable addresses at topology build time. Most samples use the inline environment model and, by default, the engine commit pinned in ENGINE_PIN. orders-dotnet-compose instead selects a user-supplied Docker Compose environment through environment.source, while retaining the same five business assertions and shared application. The pinned source engine supports its TCP bindings and native healthcheck readiness. Installed candidate execution uses the selected executable; consult docs/RUNNING.md for compatibility and prerequisites. SaaS and Kubernetes are not execution formats supplied by this checkout. A matching core source checkout also supplies the separate three-step examples/compose-orders HTTP/PostgreSQL control.

What "Proven" Means¶

The vouchfx engine separates four distinct verdicts — this is deliberate and is the single most important thing to understand when reading a test result. The full taxonomy, with exit-code mappings and what each verdict means for your product, is documented in the engine's blueprint § 12.1. In brief:

Pass — every assertion held; the system works as built.
Fail — an assertion failed; a genuine defect exists in the code.
Environment Error — infrastructure broke before the system under test was meaningfully exercised (a container failed to start, an image pull failed, a health check never turned green). This is not a code defect.
Inconclusive — the engine could not determine correctness in time (a timeout, a network partition, an upstream event that never arrived). Not a verdict on the code itself.

Fail always returns exit 1. The standard sample runner also gates EnvironmentError (exit 3) with --fail-on-env-error and Inconclusive (exit 4) with --fail-on-inconclusive. See docs/RUNNING.md for the complete exit-code table and how to interpret each result.

Directory Layout¶

.
|-- README.md                           (this file)
|-- CONTRIBUTING.md                     (how to add a new sample)
|-- LICENSE                             (Apache-2.0)
|-- ENGINE_PIN                          (the pinned vouchfx engine commit SHA)
|-- docs/
|   |-- RUNNING.md                      (prerequisites, quick start, reading results)
|   |-- migrating.md                    (the migration guide: Postman/xUnit/SpecFlow -> vouchfx)
|   `-- ...                             (other documentation)
|-- scripts/
|   |-- bootstrap.sh / bootstrap.ps1    (fetch and build the pinned engine)
|   |-- run-sample.sh / run-sample.ps1  (build a sample's image and run its suite)
|   |-- run-migrations.sh / .ps1        (run the three ported migration suites)
|   `-- ...
|-- migrations/
|   |-- from-postman/                   (Postman collection -> .e2e.yaml, source + ported + mapping)
|   |-- from-xunit/                     (xUnit integration test -> .e2e.yaml)
|   |-- from-specflow/                  (SpecFlow feature -> .e2e.yaml)
|   `-- README.md                       (the porting philosophy and how to run them)
|-- samples/
|   |-- orders-dotnet/
|   |   |-- app/                        (Dockerfile + ASP.NET Core service)
|   |   |-- tests/orders.e2e.yaml       (the test suite)
|   |   `-- README.md                   (sample documentation)
|   |-- inventory-python/
|   |   |-- app/                        (Dockerfile + FastAPI service)
|   |   |-- tests/inventory.e2e.yaml    (the test suite)
|   |   `-- README.md                   (sample documentation)
|   |-- payments-java/
|   |   |-- app/                        (Dockerfile + Spring Boot service)
|   |   |-- tests/payments.e2e.yaml     (the test suite)
|   |   `-- README.md                   (sample documentation)
|   |-- ledger-jsonrpc/
|   |   |-- app/                        (Dockerfile + Node.js service, dual-role)
|   |   |-- runner/                     (custom runner for Community providers)
|   |   |-- tests/ledger.e2e.yaml       (the test suite)
|   |   `-- README.md                   (sample documentation)
|   `-- ...
|-- out/                                (test results: HTML, JUnit XML)
|   `-- (generated after running samples)
`-- .vouchfx-src/                       (pinned engine source, created by bootstrap.sh)
    `-- (generated, not committed)

Key Documents¶

This Repository¶

README.md — overview, catalogue, quick start (you are here)
docs/RUNNING.md — prerequisites, how to read results, CI notes
docs/migrating.md — porting Postman / xUnit / SpecFlow assets onto vouchfx, with the three worked examples in migrations/
CONTRIBUTING.md — how to add a new sample, quality bar, DCO sign-off
Per-sample READMEs:
samples/orders-dotnet/README.md — ASP.NET Core e2e flow, webhook listener design, database assertions
samples/inventory-python/README.md — Python/FastAPI, MySQL + Redis + RabbitMQ integration, read-through cache proof
samples/payments-java/README.md — Spring Boot, SQL Server, NATS JetStream, SMTP email capture, stream-ownership design pattern
samples/ledger-jsonrpc/README.md — Node.js JSON-RPC 2.0, custom runner pattern for Community providers, multi-role containers, Kafka producer + consumer coordination

vouchfx Engine¶

Engine GitHub Repository — the system under test
Project Website — getting started guide, language reference, recipes, and architecture overview
Engine CONTRIBUTING.md — how to write a new provider
Technical Architecture & Blueprint — the five-layer design, memory model, Aspire integration, verdict taxonomy, provider contract
YAML DSL Specification — the .e2e.yaml grammar, step families, capture/placeholder syntax

vouchfx-providers — the community provider hub: the registry of community providers and hub-hosted provider source. Providers can earn the maintainer-awarded Vouched badge after rubric review.
vouchfx-telemetry-backend — the optional telemetry aggregation service (aggregate run-metadata only: verdict counts, timings, tool/engine versions, under a privacy allowlist with 90-day retention default).

Status¶

Samples: Six reference suites are maintained. The Samples CI workflow covers five source-engine samples; its matrix excludes orders-dotnet-compose. Docker-free runner regressions verify dispatch and failure handling separately.

Engine consumption: The default runner targets the source commit selected for the v1 release in ENGINE_PIN. Fresh public bootstrap requires that commit to be reachable on GitHub; source pinning and package publication are separate gates. Explicit installed mode validates a separately installed executable and its declared version without building engine source; passing source CI does not establish that an installed candidate works. ledger-jsonrpc requires its custom source runner and is rejected in installed mode.

Documentation: British English throughout. Samples are living documentation: every .e2e.yaml file is a worked example of the YAML DSL, and every sample's README cross-references the engine's architecture blueprint and language reference so authors can verify their understanding against the canonical source.

Licence¶

All contributions are made under the Apache-2.0 licence. By contributing to this repository, you agree your contribution is licensed under Apache-2.0 and you have the right to licence it as such.

The vouchfx engine, the Vouchfx.Sdk, and all related documentation are also Apache-2.0 licensed, as are all provider tiers in the vouchfx-providers community hub.

Questions? Open an issue here for questions about samples or running the tests. For questions about the engine itself, vouchfx providers, or the DSL, see the engine repository. Visit the project website for getting-started guides and architecture documentation.

Ready to contribute a sample? Read CONTRIBUTING.md — we welcome real-world examples that showcase new technology pairings or integration patterns.