Variables and secrets
Give tests data through variables and secrets, where each value comes from, and what gets masked.
Tests get data from two files. Variables are plain values; secrets are masked everywhere agent-qa writes or sends text.
| File | Config key | Holds | Masked |
|---|---|---|---|
.env | workspace.envFile | Test data, such as a product name or a start URL. | No |
.env.secrets.local | workspace.secretsFile | Passwords, tokens and anything else sensitive. | Yes |
Both files must exist, even empty, and both stay out of git: the .gitignore from init covers them.
File format
# .env.secrets.local
ADMIN_PASSWORD=correct-horse-battery
API_TOKEN="tok_test_51H…"One KEY=value per line. Lines starting with # and blank lines are skipped, and surrounding quotes are removed. There is no export and no ${VAR} expansion.
Use them in a step
steps:
- Search for {{env:PRODUCT_NAME}} and open the first result.
- Sign in as admin@example.com with password {{secret:ADMIN_PASSWORD}}.{{secret:NAME}} is filled in at the moment of the action. Everywhere else, in model requests, logs, reports and knowledge, it appears as [secret:ADMIN_PASSWORD].
Where variables come from
Later sources win:
.env- values written by a suite's setup hooks
--var KEY=VALUEon the command line- values written by the test's setup hooks
- during the run: inline hooks, captures and values the agent sets
Your shell's environment variables are not available as {{env:NAME}}. Pass them with --var, or write them into .env.
Masking
- Every value in the secrets file is masked as
[secret:<name>], and never restored. - An action that would type the literal text
[secret:NAME]is refused. Use{{secret:NAME}}instead. - Steps that type a secret are never cached.
- Values a plugin remote asks to mask, such as a session URL that carries a credential, are masked as
[secret:PLUGIN_<ENTRY>]. - Nothing else is masked: not
.env, not screenshots or videos, not cookies or saved logins. Put anything sensitive in the secrets file, and use test accounts.
Hooks receive variables and secrets as environment variables inside their sandbox. The exception is a secret used by a remote, a plugin entry, a device's capabilities or a target's app.ref: it is used only for that connection, so steps, expected values, target URLs and hooks cannot use it.
Errors you may see
| Message | Meaning |
|---|---|
Env file not found or Secrets file not found | Create the file. It may be empty. |
Variable "{{NAME}}" must use a namespace prefix: {{env:NAME}} | Write {{env:NAME}} or {{secret:NAME}}. |
Unresolved template variable(s) | The step needs a variable nothing has set. Add it to .env, pass --var, or set it in a hook. |
'capture:' syntax is not supported. Use {{env:X}} instead. | Captured values are read with {{env:NAME}}. |