# vero

> vero runs declarative API test plans as a graph, and keeps tasks that share a rate limit from overlapping.

vero is a test runner for HTTP, GraphQL, WebSocket, gRPC, SQL and exec steps, driven by YAML plans (vero.plan/v1). Every link below is the markdown copy of a page on https://vero.stneto.dev; https://vero.stneto.dev/llms-full.txt is all of them in one file.

## Start

- [Getting started](https://vero.stneto.dev/guides/getting-started.md): Run a checked-in plan against a disposable sample API, then write a small plan for a service you control. Commands below use a POSIX shell from the repository root.
- [How a run works](https://vero.stneto.dev/guides/how-a-run-works.md): vero run plan.yaml does four things in order: it loads the plan and refuses it whole if anything is wrong, it builds a graph of the tasks, it schedules that graph across --jobs workers, and it…

## Example plans

- [Example plans](https://vero.stneto.dev/examples.md): Plans to copy. A test in the repository runs each one against the fixture server.
- [exec.yaml](https://vero.stneto.dev/examples/exec.yaml.md): An exec migration step uses an argv list, no shell, its own process group, and capped output.
- [fixture.yaml](https://vero.stneto.dev/examples/fixture.yaml.md): Seed reference data no API creates, then read it back.
- [graphql.yaml](https://vero.stneto.dev/examples/graphql.yaml.md): A graphql step posts a query with variables and reads the data back; a second task expects an error and says so by reading body.errors, which is what turns the step's own errors check off.
- [grpc.yaml](https://vero.stneto.dev/examples/grpc.yaml.md): One unary gRPC call and one server stream against the Orders service that examples/grpc/*.proto describe.
- [orders.yaml](https://vero.stneto.dev/examples/orders.yaml.md): Log in, create an order, check it, and delete it in teardown.
- [playwright.yaml](https://vero.stneto.dev/examples/playwright.yaml.md): Log in, drive Chromium through Playwright on vero-testserver's /checkout page, then check the placed order with an http step.
- [postgres.yaml](https://vero.stneto.dev/examples/postgres.yaml.md): Check the persisted order with a read-only Postgres role and READ ONLY transactions.
- [rate-limit.yaml](https://vero.stneto.dev/examples/rate-limit.yaml.md): Four requests spend a budget of three; the fourth must be refused.
- [scripts.yaml](https://vero.stneto.dev/examples/scripts.yaml.md): Node (global fetch) and Python 3 script steps run against vero-testserver on its default address.
- [sqlite.yaml](https://vero.stneto.dev/examples/sqlite.yaml.md): An HTTP 201 is followed by a read-only SQL check that the order was persisted for the right tenant.
- [wait-for-api.yaml](https://vero.stneto.dev/examples/wait-for-api.yaml.md): Wait for a service to come up, then use it.
- [ws.yaml](https://vero.stneto.dev/examples/ws.yaml.md): A ws step sends two messages and collects the echoes; a second task collects what a server pushes on its own and reads when each message arrived.

## Reference

- [vero.plan/v1 reference](https://vero.stneto.dev/plan-format.md): A plan is one YAML file: one run, one target. vero plan plan.yaml checks it and sends nothing to the target; vero run plan.yaml runs it. This reference describes the format vero implements.
- [Templates](https://vero.stneto.dev/reference/templates.md): A template is {{ path }} inside a string value of the plan. Inside the braces is a path, never an expression: env.<key>, tasks.<name>.results.<key> or run.id. No filters, calls or arithmetic.
- [Assertions](https://vero.stneto.dev/reference/assertions.md): An assertion is an expression string that must be a boolean at compile time. body.ok alone is refused; write body.ok == true.
- [Command line](https://vero.stneto.dev/reference/cli.md): vero has five commands.
- [States and exit codes](https://vero.stneto.dev/reference/states-and-exit-codes.md): A task ends in one of seven states, and the run's exit code is computed from them in one place.

## Steps

- [The http step](https://vero.stneto.dev/steps/http.md): An http step sends one request and reads the whole response, or, with repeat, sends the same request several times.
- [The graphql step](https://vero.stneto.dev/steps/graphql.md): A graphql step is an http step with the request written as a query.
- [The ws step](https://vero.stneto.dev/steps/ws.md): A ws step opens one WebSocket, sends its messages, collects what comes back until a count or a timeout says stop, and closes.
- [The grpc step](https://vero.stneto.dev/steps/grpc.md): A grpc step makes one call: unary or streaming, described by .proto files that vero compiles when the plan loads.
- [The sql step](https://vero.stneto.dev/steps/sql.md): A sql step runs one read-only query against a database the plan declares in connections, and puts the rows in front of the assertions.
- [The fixture step](https://vero.stneto.dev/steps/fixture.md): A fixture step writes reference data no API creates, such as country codes, through a connection declared writes: true, and commits it.
- [The exec step](https://vero.stneto.dev/steps/exec.md): An exec step runs a program: a migration tool, a seeding script, a CLI whose output is the check.
- [The waitFor step](https://vero.stneto.dev/steps/wait-for.md): A waitFor step polls an HTTP endpoint until a condition holds, then lets the task go on. It is for a service that is still coming up, a job that has not finished, a cache that has not filled.
- [The script step](https://vero.stneto.dev/steps/script.md): A script step runs a program you wrote, in your own Node or Python, and reads back what it reports over vero.script/v1.

## Guides

- [Running the examples](https://vero.stneto.dev/guides/running-examples.md): Start with the checkout, POSIX shell, and build in Getting started. Run commands from the repository root.
- [Running in CI](https://vero.stneto.dev/guides/ci.md): A CI job needs three things from a test runner: one number that says whether to stop the pipeline, files the CI system can show, and no surprises between the laptop and the runner.
- [Secrets](https://vero.stneto.dev/guides/secrets.md): A secret in vero is a value vero knows is one.
- [Diagnosing a failing plan](https://vero.stneto.dev/guides/diagnosing.md): A plan goes wrong in one of three places: it does not load, it loads and a task does not pass, or it passes and did not check what you meant.
- [Script steps](https://vero.stneto.dev/guides/script-steps.md): A script step runs a program you wrote, in your own Node or Python, and reads back what it reports.
- [A browser through the script step](https://vero.stneto.dev/guides/playwright.md): examples/playwright/checkout.mjs drives real Chromium with Playwright: it signs in on vero-testserver's /checkout page, places an order through the form, and returns the order id the page shows.
- [Importing Postman, Hurl and curl](https://vero.stneto.dev/import.md): vero import turns a Postman collection, a Hurl file or a curl command into a plan on stdout, keeping the source's request order and writing no holds.
- [Reading a flake report and the --jobs hint](https://vero.stneto.dev/flake-hints.md): vero run --repeat N plan.yaml runs the plan N times and reports, per task, how often it passed.

## Contracts

- [vero.events/v1](https://vero.stneto.dev/contracts/events-v1.md): The native output of vero run (chapter 8.3): newline-delimited JSON, one event per line, written as the run happens and flushed line by line, so a run that is killed leaves a file whose every…
- [vero.script/v1](https://vero.stneto.dev/contracts/script-v1.md): The protocol between vero and a script step's child process (chapter 9.2). It is deliberately dull: one JSON object in, newline-delimited JSON events out, stderr as logs.

## Evidence

- [The rate-limit case against a real limiter](https://vero.stneto.dev/evidence/real-rate-limiter.md): Chapter 10.4 calls this the most valuable experiment the dossier did not run: its 3% came from a token bucket with no time window, and a real limiter with a window and a burst allowance might be…
- [The rate-limit fixture in Hurl, k6 and Karate](https://vero.stneto.dev/evidence/prior-art-ports.md): Chapter 1.3 described Hurl, k6 and Karate from their documentation; none was installed or run.
- [The ws and grpc steps against servers vero did not write](https://vero.stneto.dev/evidence/real-streams.md): G05, run on 2026-10-01 between 02:38Z and 02:50Z on host worker, against k3s.