Documentation map¶
Everything here, on one page, with what each part is for.
Start here¶
| Page | What it covers |
|---|---|
| Getting Started | Install tomato and get a passing suite, in seven steps |
| Writing a Suite | How to write scenarios worth trusting: one behaviour each, and asserting the effects your application produces rather than only the response it returns |
Read them in that order. The first gets something running; the second is what makes it worth having.
Running a suite¶
| Page | What it covers |
|---|---|
| Test Coverage | Which lines of your service the scenarios ran, per language |
| GitHub Action | Running the suite in CI |
Configuring¶
Configuration Reference is tomato.yml in full —
settings, the application under test, containers, resources, hooks and feature
paths.
Then one page per dependency, for the options it accepts and how to wire a container to it:
HTTP Server · gRPC · gRPC Server · Kafka · RabbitMQ · ScyllaDB · Redis · S3 · AWS · Lifecycle · Network · Profile · Browser · PDF
Steps, by resource¶
334 steps across 18 resource types. Every page is generated from the step
definitions themselves, so it cannot disagree with the binary you are running
— and tomato steps prints the same thing in your terminal.
| Resource | Steps | For |
|---|---|---|
| HTTP Client | 56 | Calling your application and asserting on the response |
| Kafka | 29 | Producing, consuming and asserting on topics |
| S3 | 27 | Object storage: MinIO, LocalStack or a real bucket |
| Redis | 25 | Keys, TTLs, counters and hashes |
| RabbitMQ | 23 | Queues, exchanges and routing |
| Shell | 22 | Running commands and asserting on their output |
| gRPC | 19 | Calling unary methods via server reflection |
| HTTP Server | 18 | Stubbing the HTTP services your application calls |
| Browser | 18 | Using the web UI in a real Chromium and asserting on what it shows |
| WebSocket Client | 17 | Connecting and exchanging messages |
| gRPC Server | 16 | Stubbing the gRPC services your application calls |
| 13 | What is inside the PDFs your application generates: pages, text, metadata, outline and accessibility | |
| Network | 12 | Making the network to a dependency slow, unreliable or down |
| PostgreSQL | 11 | Seeding tables, running SQL, asserting on rows |
| ScyllaDB | 9 | Cassandra and ScyllaDB over CQL |
| Lifecycle | 9 | Stopping and starting the app and its containers mid-scenario |
| WebSocket Server | 8 | Stubbing a WebSocket your application connects to |
| AWS | 2 | The IRSA identity tomato hands the application |
Overview of all resources lists them together.
Changing tomato itself¶
| Page | What it covers |
|---|---|
| Architecture | What is in the repository, which parts ship, and which of them CI checks |
| Adding a Step or Resource | The walkthrough for both, and how to deprecate rather than rename |
| Design: Network Faults | Why the network resource embeds Toxiproxy, what a spike found per dependency, and how faults reach the reports |
| Stability | What counts as a breaking change, and how long a deprecation lasts |
The short version¶
tomato runs your application the way production does and talks to it over the
network. A suite is tomato.yml plus .feature files — no glue code. Every
scenario starts from the same state, because tomato resets every resource
before each one and gives you no way to turn that off.
The part people miss: assert the effects. A 201 says your handler did
not crash. Whether the row landed, the event published and the receipt was
written is what the rest of your system depends on, and
Writing a Suite is about asserting those.