Environment Variables

This page documents all environment variables used by Stepwright and Fixwright.

Stepwright Environment Variables

Browser Configuration

`STEPWRIGHT_HEADLESS`

Run browser in headless mode.

Type	Default
`boolean`	`true`

STEPWRIGHT_HEADLESS=false npx stepwright run ./script.ts

`STEPWRIGHT_BROWSER`

Browser engine to use.

Type	Default	Values
`string`	`chromium`	`chromium`, `firefox`, `webkit`

STEPWRIGHT_BROWSER=firefox npx stepwright run ./script.ts

`STEPWRIGHT_TIMEOUT`

Default timeout in milliseconds.

Type	Default
`number`	`30000`

STEPWRIGHT_TIMEOUT=60000 npx stepwright run ./script.ts

Artifacts

`STEPWRIGHT_ARTIFACT_DIR`

Directory for storing artifacts.

Type	Default
`string`	`.stepwright/artifacts`

STEPWRIGHT_ARTIFACT_DIR=./my-artifacts npx stepwright run ./script.ts

`STEPWRIGHT_SCREENSHOT_ON_FAILURE`

Capture screenshot on step failure.

Type	Default
`boolean`	`true`

STEPWRIGHT_SCREENSHOT_ON_FAILURE=false npx stepwright run ./script.ts

`STEPWRIGHT_DOM_ON_FAILURE`

Capture DOM on step failure.

Type	Default
`boolean`	`false`

STEPWRIGHT_DOM_ON_FAILURE=true npx stepwright run ./script.ts

Logging

`STEPWRIGHT_VERBOSE`

Enable verbose logging.

Type	Default
`boolean`	`false`

STEPWRIGHT_VERBOSE=true npx stepwright run ./script.ts

`DEBUG`

Enable debug logging (uses debug package).

Type	Default
`string`	-

DEBUG=stepwright:* npx stepwright run ./script.ts

Fixwright Environment Variables

API Configuration

`ANTHROPIC_API_KEY`

Required. Anthropic API key for Claude.

Type	Default
`string`	-

ANTHROPIC_API_KEY=sk-ant-... npx fixwright fix ./failure.json

`FIXWRIGHT_MODEL`

Claude model to use.

Type	Default
`string`	`claude-sonnet-4-20250514`

FIXWRIGHT_MODEL=claude-sonnet-4-20250514 npx fixwright fix ./failure.json

`FIXWRIGHT_MAX_TOKENS`

Maximum tokens for AI response.

Type	Default
`number`	`16000`

FIXWRIGHT_MAX_TOKENS=32000 npx fixwright fix ./failure.json

Fixing Behavior

`FIXWRIGHT_MAX_ATTEMPTS`

Maximum fix attempts.

Type	Default
`number`	`3`

FIXWRIGHT_MAX_ATTEMPTS=5 npx fixwright fix ./failure.json

`FIXWRIGHT_VERBOSITY`

Log verbosity level.

Type	Default	Values
`string`	`normal`	`quiet`, `normal`, `verbose`

FIXWRIGHT_VERBOSITY=verbose npx fixwright fix ./failure.json

File Handling

`FIXWRIGHT_BACKUP`

Create backups before modifying files.

Type	Default
`boolean`	`true`

FIXWRIGHT_BACKUP=false npx fixwright fix ./failure.json

`FIXWRIGHT_BACKUP_DIR`

Directory for file backups.

Type	Default
`string`	`.fixwright/backups`

FIXWRIGHT_BACKUP_DIR=./backups npx fixwright fix ./failure.json

Git Integration

`FIXWRIGHT_GIT_ENABLED`

Enable Git integration.

Type	Default
`boolean`	`false`

FIXWRIGHT_GIT_ENABLED=true npx fixwright fix ./failure.json

`FIXWRIGHT_GIT_BRANCH_PREFIX`

Prefix for created branches.

Type	Default
`string`	`fix/`

FIXWRIGHT_GIT_BRANCH_PREFIX=fixwright/ npx fixwright fix ./failure.json

GitHub Integration

`GITHUB_TOKEN`

GitHub token for PR creation.

Type	Default
`string`	-

GITHUB_TOKEN=ghp_... npx fixwright fix ./failure.json --create-pr

`FIXWRIGHT_PR_DRAFT`

Create PRs as drafts.

Type	Default
`boolean`	`true`

FIXWRIGHT_PR_DRAFT=false npx fixwright fix ./failure.json --create-pr

CI Environment Detection

Both tools detect common CI environments:

`CI`

Standard CI environment indicator.

Type	Default
`boolean`	`false`

When CI=true:

Stepwright defaults to headless mode
Timeout defaults increase
Verbose error output enabled

CI=true npx stepwright run ./script.ts

CI-Specific Variables

env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  CI: true

variables:
  ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
  CI: "true"

environment {
  ANTHROPIC_API_KEY = credentials('anthropic-key')
  CI = 'true'
}

Using .env Files

Create a .env file in your project root:

# Stepwright
STEPWRIGHT_HEADLESS=true
STEPWRIGHT_BROWSER=chromium
STEPWRIGHT_TIMEOUT=30000
STEPWRIGHT_VERBOSE=false

# Fixwright
ANTHROPIC_API_KEY=sk-ant-your-key-here
FIXWRIGHT_MODEL=claude-sonnet-4-20250514
FIXWRIGHT_MAX_ATTEMPTS=3
FIXWRIGHT_VERBOSITY=normal

# Git/GitHub
GITHUB_TOKEN=ghp_your-token-here
FIXWRIGHT_GIT_ENABLED=true

# Test data (for your scripts)
TEST_USER_EMAIL=test@example.com
TEST_USER_PASSWORD=secret123
BASE_URL=https://staging.example.com

Loading .env Files

Use dotenv to load environment variables:

import 'dotenv/config';
import { Stepwright } from '@korvol/stepwright';

// Environment variables are now available
const script = Stepwright.create('My Script')
  .data({
    email: process.env.TEST_USER_EMAIL!,
    baseUrl: process.env.BASE_URL!,
  });

Or in package.json:

{
  "scripts": {
    "test": "dotenv -- npx stepwright run ./scripts/main.ts"
  }
}

Environment Variable Precedence

Variables are resolved in this order (highest to lowest priority):

Command line flags (--headed)
Environment variables (STEPWRIGHT_HEADLESS=false)
Configuration file (stepwright.config.ts)
Default values

Example:

# Environment says headless
export STEPWRIGHT_HEADLESS=true

# CLI flag overrides
npx stepwright run ./script.ts --headed
# Result: runs with visible browser

Custom Environment Variables in Scripts

Access custom variables in your scripts:

const script = Stepwright.create('Configured Script')
  .data({
    // Required variables
    apiKey: process.env.API_KEY!,

    // Optional with defaults
    baseUrl: process.env.BASE_URL || 'https://example.com',
    debug: process.env.DEBUG === 'true',

    // Parsed numbers
    timeout: parseInt(process.env.TIMEOUT || '30000'),
  })

  .step('Use config', async (ctx) => {
    await ctx.page.goto(ctx.data.baseUrl);
    ctx.log('API Key present:', !!ctx.data.apiKey);
  });

Reference Table

Stepwright

Variable	Type	Default	Description
`STEPWRIGHT_HEADLESS`	boolean	`true`	Headless browser mode
`STEPWRIGHT_BROWSER`	string	`chromium`	Browser engine
`STEPWRIGHT_TIMEOUT`	number	`30000`	Default timeout (ms)
`STEPWRIGHT_ARTIFACT_DIR`	string	`.stepwright/artifacts`	Artifact directory
`STEPWRIGHT_SCREENSHOT_ON_FAILURE`	boolean	`true`	Screenshot on failure
`STEPWRIGHT_DOM_ON_FAILURE`	boolean	`false`	DOM capture on failure
`STEPWRIGHT_VERBOSE`	boolean	`false`	Verbose logging

Fixwright

Variable	Type	Default	Description
`ANTHROPIC_API_KEY`	string	-	Required. API key
`FIXWRIGHT_MODEL`	string	`claude-sonnet-4-20250514`	Claude model
`FIXWRIGHT_MAX_TOKENS`	number	`16000`	Max response tokens
`FIXWRIGHT_MAX_ATTEMPTS`	number	`3`	Max fix attempts
`FIXWRIGHT_VERBOSITY`	string	`normal`	Log verbosity
`FIXWRIGHT_BACKUP`	boolean	`true`	Create backups
`FIXWRIGHT_BACKUP_DIR`	string	`.fixwright/backups`	Backup directory
`FIXWRIGHT_GIT_ENABLED`	boolean	`false`	Enable Git
`FIXWRIGHT_GIT_BRANCH_PREFIX`	string	`fix/`	Branch prefix
`GITHUB_TOKEN`	string	-	GitHub token for PRs
`FIXWRIGHT_PR_DRAFT`	boolean	`true`	Create draft PRs

Next Steps

Configuration Reference - Config file options
CLI Commands - Command line usage
CI/CD Integration - Using in pipelines