Environment Variables

Introduction

Environment variables provide a centralized way to store values that can be shared across all tests in your project. They are managed through the Test Data section in your workspace and work across both the Stably Web Editor and the Stably SDK.

Environment variables live at the project level and are shared by every test in the workspace. For test-specific values, use local variables instead.

Adding Environment Variables

Navigate to Test Data

Go to Test Data → Variables in your workspace.

Add variable

Click + Add Variable to create a new environment variable.

Set the scope

Select which environment this variable belongs to (e.g., staging, production, or All Environments). Variables scoped to a specific environment are only available when tests run in that environment. If you’re unsure, choose All Environments so every test can access it.

Use environment-scoped variables to store values like API keys, base URLs, and configuration that differ between staging and production.

Configure its value

Enter the variable name and value. JSON values are also supported — they will be accessible in your tests as parsed JSON objects.

Set the sensitivity

Toggle Sensitive to encrypt and hide the value after creation. This will prevent the value from being captured in Playwright traces.

Once a variable is marked as sensitive, you will not be able to view its current value or change it back to non-sensitive. You can still update the value by providing a new one.

Save the variable

Save the variable to make it available across all of your tests.

Downloading Variables as `.env`

You can download all your environment variables as a .env file directly from the dashboard. This makes it easy to sync your variables to your local development environment for use with the Stably SDK. Click the Download .env button in the Environment Variables section of the Test Data page:

Download .env button on the Test Data page

The downloaded file contains all your variables. Non-sensitive variables include their full values, while sensitive variables appear as empty placeholders with a comment (e.g., # MY_SECRET - SENSITIVE (value not exported)). Place the file in your project root for local test execution.

Sensitive variable values are not included in the download. You will need to fill them in manually in the .env file.

When you add or update variables in the dashboard, click Download .env again to keep your local file in sync.

Using Environment Variables

Environment variables are accessed via process.env.VARIABLE_NAME in your test code. How they get loaded depends on whether you’re using Stably on the web or locally.

Stably Web
Stably CLI
Manual Setup

Environment variables you configure in Test Data are automatically injected into the AI agent’s environment. No additional setup is needed.The AI agent will use process.env.VARIABLE_NAME in the generated test code:

import { test, expect } from '@stablyai/playwright-test';

test('login flow', async ({ page }) => {
  await page.goto(process.env.BASE_URL!);
  await page.fill('#username', process.env.TEST_USERNAME!);
  await page.fill('#password', process.env.TEST_PASSWORD!);
});

You can also reference variables naturally in your AI instructions — the agent knows which environment variables are available and will match them to your intent:

“Navigate to the base URL”
“Log in with the test account credentials”
“Use the API key to authenticate”

You don’t need to specify the exact variable name in your instructions — the AI agent will pick the right one automatically.

The Stably CLI can load variables from a named Environment stored on Stably using the --env flag. This is the recommended approach — no local files to manage.

# Load variables from your "Staging" environment
stably --env Staging test

# Works with all CLI commands
stably --env Production create "login test"

You can also load variables from a local .env file:

stably test --env-file .env.staging

Or combine both:

stably --env Production test --env-file .env

Variable Precedence

When using the CLI, variables can come from multiple sources. They are resolved in the following order (highest priority wins):

Stably internals (STABLY_API_KEY, STABLY_PROJECT_ID)
--env — remote environment from Stably
--env-file — local .env file(s)
process.env — system/shell environment

Once loaded, variables are available as process.env.VARIABLE_NAME in your tests:

import { test, expect } from '@stablyai/playwright-test';

test('login flow', async ({ page }) => {
  await page.goto(process.env.BASE_URL!);
  await page.fill('#username', process.env.TEST_USERNAME!);
  await page.fill('#password', process.env.TEST_PASSWORD!);
});

You can also load environment variables manually using dotenv in your Playwright config. This works with any Playwright setup, including without the Stably CLI.

Download your variables

Go to Environments in the dashboard, open your environment, and click Download .env.

Place the file in your project

Move the downloaded .env file to your project root directory.

Load variables in your config

npm install -D dotenv

Then add to the top of your playwright.config.ts:

import dotenv from 'dotenv';
import path from 'path';

dotenv.config({ path: path.resolve(__dirname, '.env') });

Once loaded, variables are available as process.env.VARIABLE_NAME in your tests:

import { test, expect } from '@stablyai/playwright-test';

test('login flow', async ({ page }) => {
  await page.goto(process.env.BASE_URL!);
  await page.fill('#username', process.env.TEST_USERNAME!);
  await page.fill('#password', process.env.TEST_PASSWORD!);
});

Editing and Deleting Variables

To edit a variable, click on it in the variables list to expand the edit form. You can update its name, value, and environment scope. For sensitive variables, you can provide a new value but cannot view the current one. To delete a variable, click the delete icon next to it in the variables list.

Best Practices

✔️ Do	❌ Avoid
Store secrets and API keys as Sensitive variables.	Hard-coding credentials directly in tests.
Use descriptive `UPPER_SNAKE_CASE` names (e.g., `API_KEY`, `BASE_URL`).	Abbreviations that will be hard to remember (`akp`).
Create environment-specific variables for different staging environments.	Using the same credentials across all environments.
Use environment variables for values shared across multiple tests.	Creating duplicate variables with the same value.

See also: Variables for information about local variables and other variable types.

Getting started

Stably Web Editor

Stably CLI

Stably Cloud Runner

Stably SDK

Stably Test Reporter

Configuration

Troubleshooting

Migration Guides

Resources

Introduction

Adding Environment Variables

Downloading Variables as `.env`

Using Environment Variables

Variable Precedence

Editing and Deleting Variables

Best Practices

​Introduction

​Adding Environment Variables

​Downloading Variables as .env

​Using Environment Variables

​Variable Precedence

​Editing and Deleting Variables

​Best Practices

Introduction

Adding Environment Variables

Downloading Variables as `.env`

Using Environment Variables

Variable Precedence

Editing and Deleting Variables

Best Practices