Running tests

Your test suite, unchanged, against a sandbox.

Your test suite runs unchanged, and veris run routes its outbound calls to the matching twin.

veris names every command, lists every exit code, and carries the flag tables for run, up, env create, sandbox clock set and baseline promote; veris <command> --help prints what that command takes. The full entry for each variable those commands read is in Environment variables. The Veris plugin works the commands out for you: setup installs the CLI, records the test command and the image it runs in under .veris/twin.yaml, and writes the full veris run line into .veris/NOTES.md.

Runs happen on your own machine. The container tier is the usual one, and it is what needs Docker: your command runs in a test image with the proxy in its own container beside it. Setup takes the direct tier instead when your code already reads each vendor’s URL from an environment variable production sets, and that tier needs no container and no proxy. Setup picks the tier.

The run

veris up deploys a sandbox and remembers it for this folder, veris run puts your command in front of it and prints the receipt, and veris down deletes it.


veris up
veris run --require-service stripe -- pytest -q
veris down

A bare veris run, with no --, runs the command recorded as run.command in .veris/twin.yaml, in the image recorded as proxy.image. Anything you pass after -- replaces the recorded command.


veris run                                     # the recorded test command
veris run -- pytest -x tests/test_billing.py  # a different command
veris run -- pytest -q --maxfail=1            # flags reach your test command

veris run --fresh does all three in one process — deploy, run, delete — which is the shape for CI:


veris run --fresh --require-service stripe -- pytest -q

Sandbox selection

Attach to a sandbox that already exists when the run has to meet state you seeded or a fault you armed.

Flag	Sandbox	After the run	On an empty receipt
none	This folder’s, from `veris up`	Left running	Exit 3 with a requirement in play, a warning without one
`--fresh`	Deployed for this run	Deleted	Exit 3
`--sandbox <id>`	One that already exists	Left running	Exit 3 with a requirement in play, a warning without one

Each reading assumes the CLI could read the sandbox’s own request log: where it could not, an empty receipt is undecided rather than failed and the run exits 4, and the warning — a line on stderr, which --quiet suppresses — needs a log that was read in full.

A requirement is in play when --require-service is on the command line, or proxy.require_service is recorded in .veris/twin.yaml. Setup records it, so a repository setup wired fails on an empty receipt whichever row it is on.

--keep leaves a --fresh sandbox running afterwards, as this folder’s. VERIS_SANDBOX_ID names a sandbox the way --sandbox does, and the flag wins over it.

The receipt

Each run prints what the sandbox received. The opening line names the proxy’s own container, so it appears when the run is containerised: --image on the command line, or the proxy.image recorded in .veris/twin.yaml.


veris: interception live in veris-proxy-35681
veris: sandbox ready sandbox_id=sbx_9f2c1e
veris: the sandbox received 14 request(s):
  stripe                      14

Test output is identical whether or not the suite reached its dependency, so the receipt is what separates a real run from a suite that quietly stopped calling out. A run that deploys the sandbox it routes at fails an empty receipt on its own, with no requirement in play: veris run --fresh exits 3, and so does --environment <id>, which deploys and deletes a sandbox of its own around an --image run. A requirement fails any run, deployed sandbox or not, when the sandbox did not receive that service’s traffic, whether it came from --require-service on the command line or from proxy.require_service in .veris/twin.yaml. A run attached to a sandbox that outlives it, with no requirement in play, prints a warning instead, and your command’s own exit code stands:


veris: ! the sandbox recorded no service request since the watermark

--require-service stripe:2 asserts a minimum request count for a named twin. Requests to /veris/* are counted separately and do not satisfy it.

Empty receipt causes

The suite did not call the dependency: mocks still active, tests filtered out, wrong test path.
The traffic reached the real vendor. That host has no twin in the environment.
TLS trust failed inside the container, so no request completed. See Certificates and SDK trust.

Test image requirements

Runs your tests. An existing test image usually works unchanged.
Contains no Veris configuration. Credentials, certificates and proxy settings are supplied at run time.
Does not run as uid 14741, which is reserved.

A package registry is not a service the sandbox provides, so a dependency install during the run reaches the real registry. --strict, or proxy.strict in .veris/twin.yaml, refuses a host the sandbox has no twin for, registries included.

Databases

Postgres twins speak the Postgres wire protocol rather than HTTP, so the connection string reaches your command as an environment variable instead, named by the twin and usually DATABASE_URL:


veris: postgres: not proxied; handed DATABASE_URL=postgresql://app:app@10.0.0.5:5432/sb?sslmode=require