tanu.toml Configuration¶
The tanu.toml file is used to configure different project environments for the tanu application.
Structure¶
The [[projects]] tables in the tanu.toml file allow you to define different configurations for various environments. This is inspired by Playwright and enables you to iterate the same set of tests with different configurations or environments. You can make as many projects as you want.
The tanu.toml file consists of multiple [[projects]] tables, each representing a different environment. Each table contains the following fields:
name: The name of the project (e.g., "dev", "staging", "production").test_ignore: A list of test cases to ignore for the environment.
Example¶
Below is an example of a tanu.toml file:
[tui]
payload.color_theme = "tomorrow-night" # Replace with your preferred theme name
[runner]
capture_http = true # Capture HTTP debug logs
concurrency = 4 # Run up to 4 tests in parallel
[[projects]]
name = "staging"
test_ignore = [
"feature_flag::feature_flag_enabled",
"feature_flag::feature_flag_disabled",
]
retry.count = 3
retry.factor = 2.0
retry.jitter = true
retry.min_delay = "1s"
retry.max_delay = "60s"
[[projects]]
name = "production"
test_ignore = []
retry.count = 3
retry.factor = 2.0
retry.jitter = true
retry.min_delay = "1s"
retry.max_delay = "60s"
Runner¶
The [runner] section configures global test execution behavior. All values are optional and serve as defaults that can be overridden by command-line flags.
[runner]
capture_http = true # Capture HTTP debug logs for all tests (equivalent to "all")
capture_http = "all" # Capture HTTP debug logs for all tests
capture_http = "on-failure" # Capture HTTP debug logs only for failed tests (default)
capture_http = "off" # Suppress HTTP debug logs entirely
capture_rust = false # Capture Rust "log" crate logs (default: false)
show_sensitive = false # Show sensitive data in HTTP logs (default: false)
concurrency = 4 # Max parallel tests (default: unlimited for CLI, CPU cores for TUI)
fail_fast = false # Abort after the first failure (default: false)
Options¶
capture_http: Controls when HTTP request/response logs are captured and displayed. Accepts a boolean (true="all",false="off") or a string ("all","on-failure", or"off"). Default is"on-failure"(show HTTP logs only for failed tests). Use"all"to show logs for every test, or"off"to suppress logs entirely. Can be overridden with--capture-http[=MODE]on the command line.capture_rust: When enabled, captures logs from Rust'slogcrate. Useful for debugging tanu internals or test code that uses the log crate. Default isfalse. Can be overridden with--capture-rust.show_sensitive: When enabled, displays sensitive data (API keys, tokens, passwords) in HTTP logs instead of masking them with*****. Use with caution as this may expose secrets. Default isfalse. Can be overridden with--show-sensitive.concurrency: Maximum number of tests to run in parallel. If not specified, CLI mode runs all tests in parallel (unlimited), while TUI mode defaults to the number of CPU cores. Can be overridden with-cor--concurrency.fail_fast: When enabled, aborts test execution after the first failure. Remaining tests are skipped and counted as skipped in the summary. Default isfalse. Can be overridden with--fail-fast.
Note
Command-line flags always take precedence over configuration file settings. Use configuration file settings to establish project defaults and command-line flags for one-off overrides.
Retry¶
This section describes the HTTP retry configuration for the project. All values are optional. If the retry configuration is entirely omitted, retries are disabled by default. If configured, the Tanu runner will perform retry attempts if a request fails.
- retry.count: The number of retry attempts. Default is 0.
- retry.factor: The factor for exponential backoff. Default is 2.0.
- retry.jitter: A boolean to enable or disable backoff jitter. Default is false.
- retry.min_delay: The minimum delay for backoff. Default is "1s".
- retry.max_delay: The maximum delay for backoff. Default is "60s".
User defined settings¶
tanu allows you to set user-defined settings in tanu.toml. You can set arbitrary key-value pairs under each project setting.
Here is an example specifying different base_url values for staging and production environments:
[[projects]]
name = "staging"
base_url = "https://api.production.foobar.com"
[[projects]]
name = "production"
base_url = "https://api.staging.foobar.com"
In your test code, you can retrieve the value for the current project using the following method:
If the value is not string, you can use other methods to retrieve it:
Environment variables¶
Config file location¶
By default, tanu looks for tanu.toml in the current directory. You can specify a custom config file path using the TANU_CONFIG environment variable:
# Use a custom config file
TANU_CONFIG=/path/to/my-config.toml tanu test
# Or export it
export TANU_CONFIG=/path/to/my-config.toml
tanu test
Warning
TANU_CONFIG is reserved for specifying the config file path. Do not use it as a config value key (e.g., TANU_CONFIG=true). Tanu will error if it detects misuse.
User-defined config values¶
Tanu also allows you to set user-defined settings in a .env file. Secret settings like API keys should not be stored in plain text; instead, environment variables should be used.
Global config values: Any environment variable prefixed with TANU_ will be exposed as a configuration value accessible from all projects.
Project-specific config values: Any environment variable prefixed with TANU_{PROJECT}_ will be exposed as a configuration for that specific project. For example, an API key set in the TANU_STAGING_API_KEY environment variable can be accessed using tanu::get_config().get_str("api_key") when running the "staging" project.
Theme¶
You can customize the appearance of Tanu's interface by selecting a color theme.
To change the theme, add the following to your tanu.toml configuration file:
Note
The color theme setting primarily affects the Payload tab in the TUI, where it's used to colorize and syntax-highlight response payloads (particularly JSON responses). This makes the API responses more readable and helps you quickly identify different elements in the response data.
Available Themes¶
Tanu ships with all Base16 themes, providing a consistent color palette across different interfaces. Available themes include:
3024apathyashesatelier-caveatelier-duneatelier-estuaryatelier-forestatelier-heathatelier-lakesideatelier-plateauatelier-savannaatelier-seasideatelier-sulphurpoolatlasbespinblack-metalbrewerbrightbrushtreeschalkcircusclassiccodeschoolcupcakecupertinodarktoothdefaulteightiesembersflatfruit-sodagithubgooglegrayscalegreenscreengruvboxharmonichopscotchirblackisotopemacintoshmarrakeshmateriamaterialmellowmexicomochamonokainordoceanoceanicnextoneonedarkpapercolorparaisophdpicopopporplerailscastsrebeccasetishapeshiftersolarflaresolarizedspacemacssummerfruittomorrowtomorrow-nighttubetwilightunikittywoodlandxcodezenburn