Skip to main content

Environment-Based Testing

Welcome to the Environment-Based Testing documentation!

When developing an API, you rarely test against a single target. A typical lifecycle involves developing against localhost, verifying on a remote staging server, and running smoke tests against production.

Rumour's environment variables system makes it effortless to use the exact same .toml request definitions across multiple different environments without altering your test logic.

1. Defining Environment Files​

By default, if Rumour finds a workspace.env.toml file in the directory (or a parent directory) of the executing workflow, it will automatically load it. However, you can create distinct environment files for different targets.

Staging Environment​

staging.env.toml:

base_url = "https://staging.swahira.io/api"
api_key = "stg_ab12cd34"
db_timeout = 5000

Production Environment​

production.env.toml:

base_url = "https://api.swahira.io/v1"
api_key = "prod_99zz88yy"
db_timeout = 2000

2. Using Variables in Workflows​

Inside your test files, you reference the variables using standard {{}} interpolation. Note that we can even parameterize assertions (like enforcing a stricter timeout in production).

health_check.toml:

name = "System Health Check"

[request]
method = "GET"
url = "{{base_url}}/health"
headers = { "X-API-Key" = "{{api_key}}" }

[assert]
status = 200
duration = {{db_timeout}}

3. Switching Environments at Runtime​

To override the default workspace.env.toml, use the --env-file (or -e) flag when invoking the CLI.

Running against Staging​

rumour run ./health_check.toml -e ./staging.env.toml

Running against Production​

rumour run ./health_check.toml -e ./production.env.toml

Validating Resolution​

If you ever want to verify exactly which environment file was loaded and how the variables resolved before firing the network request, use the --vars diagnostic flag combined with your environment flag:

rumour run ./health_check.toml -e ./production.env.toml --vars

Output Trace:

PRE-FLIGHT DIAGNOSTIC REPORT

• ./health_check.toml
  └─ base_url        RESOLVED https://api.swahira.io/v1
  └─ api_key         RESOLVED prod_99zz88yy
  └─ db_timeout      RESOLVED 2000

4. Inline Variable Overrides​

Sometimes you need to test a specific edge case without creating a whole new .env.toml file. You can override any environment variable on the fly using the --var (or -V) flag.

CLI variables have the absolute highest precedence in Rumour's resolution hierarchy.

# Force the production timeout to be evaluated at 50ms instead of 2000ms
rumour run ./health_check.toml -e ./production.env.toml -V db_timeout=50

By keeping your configurations decoupled from your assertions, your Rumour suites remain completely environment-agnostic and portable.