CLI

CLI

Stepwright includes a command-line interface for running and validating scripts.

Installation

The CLI is included with the Stepwright package:

npm install @korvol/stepwright

Run with npx or add to your package.json scripts:

# With npx
npx stepwright run ./scripts/my-script.ts

# Or add to package.json
{
  "scripts": {
    "automation": "stepwright run ./scripts/my-script.ts"
  }
}

Commands

run

Execute a Stepwright script:

npx stepwright run <script-path> [options]

Options

Option	Description	Default
--headless	Run in headless mode	true
--headed	Run with visible browser	-
--browser <type>	Browser to use	chromium
--timeout <ms>	Default step timeout	30000
--artifacts <dir>	Artifact output directory	.stepwright/artifacts
--video	Enable video recording	false
--verbose	Enable verbose output	false
--json <path>	Output results as JSON	-

Examples

# Run headless (default)
npx stepwright run ./scripts/login.ts

# Run with visible browser
npx stepwright run ./scripts/login.ts --headed

# Use Firefox
npx stepwright run ./scripts/login.ts --browser firefox

# Enable video and verbose output
npx stepwright run ./scripts/login.ts --video --verbose

# Output JSON results
npx stepwright run ./scripts/login.ts --json ./results.json

validate

Validate a script without running it:

npx stepwright validate <script-path>

This checks:

• Script syntax is valid
• All imports can be resolved
• Script exports are correct

Example

$ npx stepwright validate ./scripts/login.ts
✓ Syntax valid
✓ Imports resolved
✓ Script structure valid

Script Requirements

Export Pattern

Scripts should export either a Stepwright instance or a run function:

Default Export

scripts/login.ts

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

export default Stepwright.create('Login Test')
  .step('Navigate', async (ctx) => {
    await ctx.page.goto('https://example.com');
  })
  .step('Login', async (ctx) => {
    await ctx.page.fill('#email', 'user@example.com');
  });

Named Export

scripts/login.ts

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

export const script = Stepwright.create('Login Test')
  .step('Navigate', async (ctx) => {
    await ctx.page.goto('https://example.com');
  });

Run Function

scripts/login.ts

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

export async function run() {
  return Stepwright.create('Login Test')
    .step('Navigate', async (ctx) => {
      await ctx.page.goto('https://example.com');
    })
    .run();
}

Environment Variables

Configuration via Environment

# Browser settings
STEPWRIGHT_BROWSER=firefox
STEPWRIGHT_HEADLESS=false

# Timeouts
STEPWRIGHT_TIMEOUT=60000

# Output
STEPWRIGHT_ARTIFACTS_DIR=./my-artifacts
STEPWRIGHT_VERBOSE=true

Using .env Files

Create a .env file:

.env

STEPWRIGHT_HEADLESS=false
STEPWRIGHT_BROWSER=chromium
STEPWRIGHT_TIMEOUT=30000

Note

CLI arguments take precedence over environment variables.

Exit Codes

Code	Meaning
0	Script passed
1	Script failed
2	Script error (syntax, import, etc.)

Use in CI pipelines:

npx stepwright run ./scripts/checkout.ts || exit 1

CI/CD Usage

GitHub Actions

name: Automation Tests
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npx playwright install chromium

      - name: Run automation
        run: npx stepwright run ./scripts/checkout.ts --json ./results.json

      - name: Upload artifacts
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: artifacts
          path: .stepwright/artifacts/

GitLab CI

automation:
  image: mcr.microsoft.com/playwright:v1.40.0-jammy
  script:
    - npm ci
    - npx stepwright run ./scripts/checkout.ts
  artifacts:
    when: on_failure
    paths:
      - .stepwright/artifacts/

Jenkins

pipeline {
  agent any
  stages {
    stage('Test') {
      steps {
        sh 'npm ci'
        sh 'npx playwright install chromium'
        sh 'npx stepwright run ./scripts/checkout.ts --json ./results.json'
      }
    }
  }
  post {
    failure {
      archiveArtifacts artifacts: '.stepwright/artifacts/**/*'
    }
  }
}

Programmatic Usage

For more control, run scripts programmatically:

import { spawn } from 'child_process';

const child = spawn('npx', [
  'stepwright', 'run',
  './scripts/checkout.ts',
  '--headless',
  '--json', './results.json',
]);

child.stdout.on('data', (data) => {
  console.log(data.toString());
});

child.on('exit', (code) => {
  console.log('Exit code:', code);
});

Troubleshooting

Script Not Found

$ npx stepwright run ./nonexistent.ts
Error: Script not found: ./nonexistent.ts

Ensure the path is correct and the file exists.

Browser Not Installed

$ npx stepwright run ./script.ts --browser webkit
Error: Browser webkit not installed

Install browsers with Playwright:

npx playwright install webkit

TypeScript Errors

$ npx stepwright run ./script.ts
Error: Cannot find module '@korvol/stepwright'

Ensure dependencies are installed:

npm install @korvol/stepwright

Next Steps

• Configuration Reference - All config options
• CI/CD Integration Guide - Detailed CI setup
• Examples - Complete script examples