🍅 tomato - behavioral testing toolkit¶

Tomato is a language-agnostic behavioral testing framework that manages your test infrastructure automatically.

Features¶

Built-in Container Orchestration - Automatically manage test containers with Testcontainers
Clean State Testing - Every resource is reset before every scenario for reliable, isolated tests
BDD/Gherkin Support - Write tests in plain English using Cucumber syntax
Multiple Resource Types - HTTP client (with Server-Sent Events) and server, gRPC, PostgreSQL, ScyllaDB/Cassandra, Redis, Kafka, RabbitMQ, S3, WebSocket client and server, Shell
Presets - preset: kafka instead of a page of listener config, with MSK-style AWS_MSK_IAM authentication on the stock apache/kafka image
AWS identity - an aws resource gives the app IRSA against an STS tomato serves
Avro + Schema Registry - Publish and assert Kafka Avro messages as plain JSON
Web UI - tomato ui browses the suite, draws each scenario's flow and the topology of what it touches, and runs scenarios from the browser
CI Reports - JUnit XML and Cucumber JSON alongside console output
Step Coverage - tomato coverage reports which resource steps your features use, with --min to gate CI
Auto-generated Documentation - Keep step docs in sync with code
Application Runner - Start your app connected to test containers

Installation¶

Quick install (recommended)¶

curl -fsSL https://raw.githubusercontent.com/tomatool/tomato/main/install.sh | sh

Homebrew¶

brew install tomatool/tap/tomato

GitHub Actions¶

- uses: tomatool/tomato@v2

See GitHub Action documentation for all options.

Go install¶

go install github.com/tomatool/tomato@latest

From source¶

Requires Go 1.26 or later.

git clone https://github.com/tomatool/tomato.git
cd tomato
go build -o tomato .
sudo mv tomato /usr/local/bin/

Upgrading¶

tomato update

Quick start¶

tomato init      # Initialize a new project
tomato validate  # Check tomato.yml and the feature files before running
tomato run       # Run behavioral tests
tomato ui        # Browse, visualize and run the suite in a web UI
tomato steps     # List available steps
tomato coverage  # Which steps your features use

Documentation¶

For complete documentation, visit tomatool.github.io/tomato

Documentation Map - every page on one screen
Getting Started
Writing a Suite - how to write scenarios worth trusting
GitHub Action
Configuration Reference
Step Reference
Architecture
Stability and versioning - what is covered by semantic versioning, and the deprecation policy

Coming from tomato v1? v2 is a rewrite, not an upgrade in place: see Migrating from v1. The v1 branch no longer receives updates.

Contributing¶

See CONTRIBUTING.md for development setup and how to add steps and resources, and MAINTAINERS.md for who reviews and how to join.

License¶

Tomato is open source under the MIT License.