Get Help

Use environment variables

Define a variable, write %NAME% where its value belongs in the project file, and check that the session running CAT can see it. That is how one project file stays free of secrets and runs against several environments.

This guide is the plumbing: defining a variable, referring to it, checking it is visible. What CAT does with the value once it has it — where expansion applies, the rules — is the Environment variables reference.

Define the variable

Where you define it decides how long it lives and who sees it:

Level Seen by Use for
Session the one shell session; gone when it closes trying things out — not for secrets, the command line lands in the shell history
User every new session of that user a developer’s machine
Machine every new session of every user a shared test server, a self-hosted agent
Pipeline the step the pipeline maps it into CI/CD — the platform’s variable or secret store; see Integrations

Session, in PowerShell:

$Env:DWH_CONNECTION_STRING = 'Server=dwh;Database=DWH;Integrated Security=true'

User or machine, for good: Settings → System → Advanced system settings → Environment Variables, or from PowerShell:

[Environment]::SetEnvironmentVariable('DWH_CONNECTION_STRING', 'Server=dwh;…', 'User')     # or 'Machine'

A user- or machine-level variable is seen only by sessions started after it was set — open a new terminal; CAT Studio: start it again.

Session:

export DWH_CONNECTION_STRING='Server=dwh;Database=DWH;User Id=cat;Password=…'

For good, put the export line into the shell’s profile (~/.bashrc, ~/.zshrc) or, for every user and for services, into /etc/environment. Variable names are case-sensitive here — DWH_CONNECTION_STRING and dwh_connection_string are two variables; on Windows they are one.

Define the value in the platform’s store — Azure DevOps variable group, GitLab CI/CD variables, GitHub secrets, Jenkins credentials — and map it into the environment of the step that runs CAT; a secret is never mapped automatically:

# Azure DevOps
- task: PowerShell@2
  inputs: { pwsh: true, script: 'Invoke-CatProject' }
  env:
    DWH_CONNECTION_STRING: $(DWH_CONNECTION_STRING)

The platform guides show it for Azure DevOps, GitLab, GitHub Actions and Jenkins.

Refer to it from the project file

Write the name between percent signs, exactly as defined:

Data sources:
- Name: DWH
  Provider: SqlServer@2
  Connection string: "%DWH_CONNECTION_STRING%"

Tests:
- Name: Departures for terminal %TERMINAL_NUMBER% are loaded
  Data source: DWH
  Query: SELECT * FROM FACT.DEPARTURES WHERE Terminal = %TERMINAL_NUMBER%
  Expectation: set is not empty

A whole connection string can come from a variable, or only its secret parts — the user and the password — and one variable can be used in as many places as needed. Expansion happens wherever a definition lives: the project file, other YAML files, a database table, a worksheet.

Check that CAT can see it

CAT sees exactly the variables the process it runs in sees. When a value reaches a provider with the percent signs still in it — an invalid connection string, a syntax error in a query — the variable was not replaced. Print it in the session you run CAT from:

$Env:DWH_CONNECTION_STRING

echo "$DWH_CONNECTION_STRING"

Nothing printed means the session does not know the variable, and neither does CAT. The usual causes: the variable was created a moment ago and this session is older than it; the name is misspelled (or, on Linux and macOS, cased differently); in a pipeline the variable is not mapped into the step. Until the session prints a value, CAT will not see one either.

← Generate tests from metadata
Work with secrets →