Venom runs integration tests written as YAML, and the executors do the talking

Tests that live next to the code, not in a separate tool

Venom is described as a CLI that aims to create, manage and run your integration tests with efficiency, and the framing sentence is the argument for the whole project: Venom allows you to handle integration tests the same way you code your application.

The mechanism is that testcases are managed as code, and the reason is given as readability. The readability of the tests means that the tests are part of the code reviews, and thanks to that, writing and executing testsuites becomes easier for developers and teams.

Concretely, you write a testsuite in a YAML file. Venom runs executors, which are the things that talk to the outside world, and it applies assertions to what they return. It can also generate xUnit result files, so the output drops into whatever reporting your CI already uses.

The audience is a team whose integration tests currently live in a tool with its own proprietary format and its own repository, or in a shell script, and who want them reviewed in a pull request like everything else. The YAML file is the point. It is diffable, it is greppable, and it can carry the same review conventions as the rest of the codebase.

The trade is the one that comes with any declarative test format. A YAML testsuite is readable, but a complex setup in a programming language can be harder to express, and a failure is reported as a step and an assertion rather than as a stack trace.

Executors are the actions and assertions are the checks

The two halves of a Venom test are the executor and the assertion, and the executors are the interesting part because they define what the tool can actually reach.

The description names them as scripts, HTTP Request, web and IMAP, and the documentation goes further, with a concepts section covering TestSuites, Executors and user defined executors, plus a Variables section that covers testsuite variables, variable helpers, and using outputs from a test step as the input of another test step.

The dependency list in the Go module shows the real breadth of the executor set. There are AMQP clients, both Azure's go-amqp and streadway's, IBM's sarama for Kafka, Eclipse's Paho for MQTT, Redis through redigo, Couchbase through gocb, several SQL drivers including MySQL, PostgreSQL, SQLite and Oracle, a schema registry client, Avro through goavro, a GitHub API client, grpcurl and protoreflect for gRPC, and venomWeb for the web executor. There is also the OVH API client, so the tool can test a cloud provider's own API.

The user defined executors are the extension point, and the run command's --lib-dir flag points at a directory that can contain them, for example /etc/venom/lib and $HOME/venom.d/lib. That means an organisation can add an executor for an internal system without forking the tool, which is the property that makes a declarative runner viable in a company with systems nobody else has heard of.

Variables, secrets and passing state between steps

A test that cannot talk to the environment it runs against is not an integration test, so the variable system is where a lot of the design effort sits.

Variables can be defined in the testsuite itself, and there is a separate concept of variable helpers, which are functions available to compute a value at run time rather than a literal in the file. They can also come from the environment, and the run command accepts a --var flag for a single value and a --var-from-file flag to load all of them from a YAML file, with the documented precedence that variables initialised with the --var-from-file argument can be overridden with the --var argument.

That precedence rule is the one to remember, because it is what lets a developer override a value locally without editing the file that carries the real credential. It is also the mechanism a CI job would use to inject a secret.

The secrets variables are documented separately, which tells you the project has thought about the difference between a value that is convenient to inline and one that must not be committed. The built-in venom variables are the third group, and the outputs of one step can be fed into another, which is how a test that authenticates can pass a token to the step that uses it.

The assertions have a keyword layer, with Must keywords and user assertions, and the documentation covers using logical operators with them. The Must prefix is a useful idea in a declarative format, because it separates a check that stops the test from a check that is merely reported.

Install a binary or run the container

Installation is a single binary, and the README gives the Linux example directly:

$ curl https://github.com/ovh/venom/releases/download/v1.2.0/venom.linux-amd64 -L -o /usr/local/bin/venom && chmod +x /usr/local/bin/venom
$ venom -h

The tool can then update itself, with venom update downloading the latest version and replacing the current binary, and venom version reporting the current one. The self update is implemented through the inconshreveable/go-update module, which is how the tool knows which release to fetch and how to swap the file.

The container route is the one to use in CI. The image is ovhcom/venom:latest, and the README's example assumes your testsuites are in the ./tests directory and your test library is under ./tests/lib, with the results available under the results directory:

$ mkdir -p results
$ docker run --mount type=bind,source=$(pwd)/tests,target=/workdir/tests --mount type=bind,source=$(pwd)/results,target=/workdir/results ovhcom/venom:latest

The Dockerfile in the repository shows how the image is put together. It is alpine:3.24 with tzdata and ca-certificates added, the prebuilt binary copied into /usr/local/bin/venom, two volumes declared at /workdir/results and /workdir/tests, and the working directory set to /workdir. The environment variables set three defaults, VENOM_OUTPUT_DIR pointing at the results volume, VENOM_LIB_DIR pointing at the tests library inside the mounted tests directory, and VENOM_VERBOSE set to 1. The entrypoint is the binary itself and the default command is run with the glob ./tests/*.y*ml.

That arrangement is a good one, because the results land on a host volume where a CI job can collect them, and the library directory is inside the same mount as the tests.

The run command and the flags that matter

The CLI is small, with four commands, and the help output is worth reading as the documentation of the tool's capabilities.

$ venom run -h

  --format string           --format:json, tap, xml, yaml (default "xml")
  -h, --help                    help for run
      --html-report             Generate HTML Report
      --lib-dir string          Lib Directory: can contain user executors.
      --output-dir string       Output Directory: create tests results file inside this directory
      --stop-on-failure         Stop running Test Suite on first Test Case failure
      --var stringArray         --var cds='cds -f config.json'

The format flag is the one that determines how the results reach your CI. The default is xml, and tap, json and yaml are the alternatives, which is enough to cover most reporting pipelines, and the --html-report flag adds a rendered report on top.

The --stop-on-failure flag is the other one worth understanding. Without it a test case failure does not stop the suite, which is right for a report that lists everything, and with it the run halts at the first failure, which is right for a pipeline where continuing wastes time and money. Both behaviours are defensible, and the flag is how you choose.

Verbosity is an environment variable rather than a flag, VENOM_VERBOSE=2 for a noisy run, and the help text shows it in use. The examples in the help output also show the shape of the day to day usage: run everything, run a single file, export to a directory, and pass a variable with --var="foo=bar".

xUnit output is the bridge into an existing pipeline

The xUnit mention in the description is not a side note, it is the integration point.

Most continuous integration systems already know how to collect xUnit format results, display them per test case and fail a build on a failing one. A tool that emits that format does not need a plugin, a reporter or an API token to become useful in a pipeline, and it is the reason a declarative YAML runner can coexist with an existing CI setup rather than replacing it.

The HTML report covers the other half of the audience, which is the person reading the results. The documentation also has sections for debugging your testsuites, for skipping test cases and test steps, and for iterating over data, which is the mechanism for running the same tests against a set of inputs. The FAQ has a section on common errors with quotes, which is the sort of thing that only exists once a format has been in use long enough to accumulate its sharp edges.

For an adopter, the sequence is short. Install the binary or plan on the container, write one testsuite YAML file for a single endpoint, run it with venom run and the --format flag your pipeline wants, and read the output. The examples in the repository's tests/ directory and the sample testsuites are the reference for the file format, and the documentation has a dedicated section on writing and running a first test suite.

The Makefile is also worth a look if you intend to extend the tool, since it has a plugins target that builds the executors under executors/plugins and moves the resulting libraries into dist/lib, which is the shape the --lib-dir flag expects.

A wide dependency set, a beta release line, Apache 2.0

The Go module is where the real shape of the project shows. It requires Go 1.27.0, and the dependency list is long because the executor set spans so many protocols: message queues, databases, schema registries, cloud APIs, gRPC, web, and the tooling for output formats and self update. The build also depends on the go-update module for the self update command, cobra for the CLI, and several format libraries for the report output.

The cost of that breadth is a large binary with a large attack surface for a tool that often runs with credentials for a lot of systems. A team running Venom in CI should treat the binary the way it would treat anything holding production credentials, and the container image is a reasonable way to keep the footprint known.

On releases, the recent tags are v1.4.0-beta.4 from 2026-10-01, v1.4.0-beta.2 from 2026-09-07 and v1.4.0-beta.1 from 2026-03-31. The repository is not archived and the last push was on 2026-10-01, so the work is continuing, but the current line is a set of betas rather than a stable release, and the install example in the README still points at v1.2.0. That is worth noting before you pin a version in a pipeline.

The licence is Apache 2.0, with a LICENSE file at the root and a LICENSES/ directory, which is the convention for a Go project that vendors third party code. The project is from OVH, and the README points at a Discussions board, a Gitpod button for contributing, and a CONTRIBUTING file, and it was part of Hacktoberfest according to the repository topics.

Editorial conclusion

Venom suits a team that tests against running systems, staging environments and third-party APIs, and that wants those tests in version control with the same review discipline as application code, whether that is an API contract, a message queue round trip or a web front end. It does not suit a project that wants its integration tests bound to the code they exercise, and it is the wrong tool when the check needs the type system and the application's own types. Verify first that an executor exists for the system you need to test, since the executors are the substance of the tool, and check the version you take, because the current release line is a set of 1.4.0 betas rather than a stable tag.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. ovh/venom on GitHub
4. README
5. Releases