Launching tests

Once you’ve written a test, you’re ready to run it. You can launch a test run from the web app, the Snouty CLI, the API or your CI.

To control how quickly the test explores your system, choose a performance tier.

To keep verbose logging on without slowing down your test run, use retroactive logging to keep verbose logging on without slowing the test down.

Test launchers

Test launchers give you a pre-configured set of options for running a test against your system. You supply run-specific details, such as your config image and the test duration, as parameters.

Every tenant comes with the setup and basic_test launchers. Antithesis can also add custom launchers for you.

The basic_test launcher

The basic_test launcher is the general-purpose launcher for finding bugs in your system.

Set the level to none if you don’t want to inject faults. This is useful when first setting up your system. You can also enable setup mode, which provides a setup assistant in the web app.

The resilient fault tolerance level injects node and network faults that degrade the system without stopping any node or persistently cutting off any network link. Packets may still be dropped intermittently.

The high_availability level adds partitions, Stopped clogs, and node termination. It can persistently drop packets on a network link, including in one direction only.

We recommend building up to high_availability in stages:

1. Run basic_test with none until your system starts reliably with no faults.
2. Run basic_test with resilient to find bugs while your system is slowed down and disrupted.
3. If your system is designed to keep working when a node goes down or the network splits, run basic_test with high_availability.

The basic_test launcher currently defaults to the legacy fault tolerance level. This enables all network faults and thread pausing, but does not inject node faults.

See Fault tolerance levels for more details on the available fault tolerance levels.

By default, faults affect every container in your system. To exclude a container, see Excluding containers from faults.

The setup launcher

The setup launcher is for getting your system running in Antithesis. It doesn’t inject faults, so that any problems you see come from your setup itself. If you launch it from the web app, it defaults to running your test in setup mode.

You can also get the same result with basic_test, by setting the fault tolerance level to none and turning on setup mode.

Custom launchers

Antithesis can create a custom launcher for you, tailored to your system and use cases. To set one up, talk to your forward-deployed engineer, or contact us at support@antithesis.com.

You can still use the antithesis.fault_tolerance and antithesis.fault_exclusions parameters with a custom launcher. Antithesis combines them with the launcher’s own settings:

• The run injects both the faults for your fault_tolerance level, and any faults the custom launcher adds. Where the two set the same fault differently, the fault_tolerance level takes priority.
• Faults skip any container that matches either your fault_exclusions pattern or the custom launcher’s own exclusions. Your fault_exclusions pattern doesn’t apply to the custom launcher’s extra faults, apart from container faults.

Launch methods

snouty launch --webhook basic_test --config ./config --duration 30 \
  --filter-logs-matching '(?i)^\s*(TRACE|DEBUG)\b'

snouty launch --webhook basic_test --config ./config --duration 30 \
  --param 'antithesis.filter_source_matching=^metrics-agent$'

curl -X POST \
  "https://<tenant>.antithesis.com/api/v1/launch/<launcher_name>" \
  -H "Authorization: Bearer $ANTITHESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "antithesis.description": "nightly test run",
      "antithesis.duration": "30",
      "antithesis.filter_logs_matching": "(?i)^\\s*(TRACE|DEBUG)\\b"
    }
  }'

Choose a performance tier

Antithesis lets you choose a performance tier when launching a test run. Higher performance tiers explore system states faster through increased parallelism, and so consume compute hours faster. You can track your compute hour usage in the web app.

Antithesis provides three performance tiers:

• Standard
• Fast
• Turbo

You can configure the performance tier when you launch a test.

Retroactive logging

Retroactive logging lets you keep verbose logging on during a test with minimal performance overhead. Log lines matching a pattern you provide are suppressed while Antithesis fuzzes your system, and they remain fully recoverable in a multiverse debugging session.

Use one or both of these methods to select logging output to suppress:

• filter_logs_matching suppresses individual log lines whose content matches your pattern.
• filter_source_matching suppresses everything from a particular source, which is useful for silencing a chatty component outright rather than picking lines out of it. This method is only available via API or CLI, not the Test Launcher.

Each launch method below details where to set these. Both take an RE2 pattern:

• Matching is unanchored and case-sensitive. Prefix your pattern with (?i) for case-insensitive matching.
• Lookahead, lookbehind and backreferences are not supported.
• Prefer a simple substring or basic pattern over a full-featured regex.

Matching log lines

If your log lines begin with their level, a good starting point is:

(?i)^\s*(TRACE|DEBUG)\b

This suppresses lines whose first non-whitespace token is TRACE or DEBUG, case-insensitive, and leaves your INFO, WARN and ERROR lines untouched.

Anchoring to the start of the line only works if the level is the first thing on it. Structured loggers typically lead with a timestamp, or emit JSON, so match the level field instead:

(?i)"level":"(trace|debug)"

Either way, check your pattern against a handful of real log lines from your system before launching a long test. Because matching is unanchored, a loose pattern like error suppresses every line that merely contains that word.

Matching sources

A source is the emitter of a log line, usually the name of the process that wrote it. The source field on each line in your logs shows you the names available to match against. Use them exactly as they appear there, especially if you intend to anchor your pattern.

This pattern is matched against the source name rather than against the line, so a match suppresses that source’s entire output:

metrics-agent

Matching is unanchored here too, so that pattern also suppresses a source named metrics-agent-v2. Anchor it with ^ and $ when you want to name a source exactly.

Source matching is set with the antithesis.filter_source_matching parameter through the API, or with --param through the Snouty CLI. It cannot be set in a test launcher dialog.

What’s next

Once your test is running, Antithesis will set up your system and explore it for the duration that you configured (minimum 15 minutes). Note that this is minutes of test time — the test run itself will last longer because it also includes set up and build time.

During the test run, you can watch the logs stream in with the logs explorer. Once the run is complete, you can view the triage report summarizing the test results.

See Understand your test results for more ways to explore your test run.