Skip to content
Autowright

Configuration

Configuration

Configuration options for Stepwright scripts.

StepwrightConfig

interface StepwrightConfig {
  name?: string;


  // Browser
  browser?: BrowserType;
  headless?: boolean;
  launchOptions?: LaunchOptions;
  contextOptions?: BrowserContextOptions;


  // Execution
  defaultTimeout?: number;
  stopOnFailure?: boolean;
  screenshotOnFailure?: boolean;
  domOnFailure?: boolean;


  // Video
  video?: VideoConfig;


  // Reporters
  reporters?: Reporter[];


  // Output
  artifactDir?: string;
  verbose?: boolean;
}

Browser Options

browser

Browser type to use.

browser?: 'chromium' | 'firefox' | 'webkit'

Default: 'chromium'

Example:

.config({
  browser: 'firefox',
})

headless

Run in headless mode (no visible browser window).

headless?: boolean

Default: true

Example:

.config({
  headless: false,  // Show browser
})

launchOptions

Playwright browser launch options.

launchOptions?: LaunchOptions

Example:

.config({
  launchOptions: {
    slowMo: 100,  // Slow down actions
    devtools: true,  // Open devtools
    args: ['--start-maximized'],
  },
})

contextOptions

Playwright browser context options.

contextOptions?: BrowserContextOptions

Example:

.config({
  contextOptions: {
    viewport: { width: 1920, height: 1080 },
    locale: 'en-US',
    timezoneId: 'America/New_York',
    geolocation: { latitude: 40.7128, longitude: -74.0060 },
    permissions: ['geolocation'],
  },
})

Execution Options

defaultTimeout

Default timeout for step operations (milliseconds).

defaultTimeout?: number

Default: 30000 (30 seconds)

Example:

.config({
  defaultTimeout: 60000,  // 60 seconds
})

stopOnFailure

Stop script execution on first failure.

stopOnFailure?: boolean

Default: true

Example:

.config({
  stopOnFailure: false,  // Continue on failure
})

screenshotOnFailure

Capture screenshot when a step fails.

screenshotOnFailure?: boolean

Default: true

Example:

.config({
  screenshotOnFailure: true,
})

domOnFailure

Capture DOM snapshot when a step fails.

domOnFailure?: boolean

Default: true

Example:

.config({
  domOnFailure: true,
})

Video Options

video

Video recording configuration.

video?: VideoConfig


interface VideoConfig {
  enabled: boolean;
  dir?: string;
  size?: { width: number; height: number };
}

Default: undefined (disabled)

Example:

.config({
  video: {
    enabled: true,
    dir: './videos',
    size: { width: 1280, height: 720 },
  },
})


// Or use shorthand
.video(true)

Output Options

artifactDir

Directory for saving artifacts.

artifactDir?: string

Default: '.stepwright/artifacts'

Example:

.config({
  artifactDir: './test-artifacts',
})

verbose

Enable verbose logging.

verbose?: boolean

Default: false

Example:

.config({
  verbose: true,
})

CheckpointDefinition

Configuration for checkpoints.

interface CheckpointDefinition {
  name: string;
  required?: boolean;
  maxRetries?: number;
  setup?: () => void | Promise<void>;
  teardown?: () => void | Promise<void>;
}

required

Whether the checkpoint must pass for script success.

Default: true

maxRetries

Maximum retry attempts for the checkpoint.

Default: 0

setup

Function to run before each checkpoint attempt.

teardown

Function to run after checkpoint completes.

Example:

.checkpoint('Critical Flow', {
  required: true,
  maxRetries: 3,
  setup: async () => {
    console.log('Starting checkpoint');
  },
  teardown: async () => {
    console.log('Checkpoint complete');
  },
})

StepOptions

Configuration for individual steps.

interface StepOptions {
  checkpoint?: string;
  critical?: boolean;
  timeout?: number;
  retry?: RetryConfig;
  skip?: (ctx) => boolean | Promise<boolean>;
  dependsOn?: string[];
  beforeRun?: (ctx) => void | Promise<void>;
  afterRun?: (ctx) => void | Promise<void>;
  onError?: (error, ctx) => void | Promise<void>;
}

critical

Whether step failure should stop execution.

Default: true

timeout

Timeout for this specific step (overrides default).

retry

Retry configuration for the step.

interface RetryConfig {
  times: number;
  delay?: number;
  backoff?: 'linear' | 'exponential';
}

skip

Condition to skip this step.

dependsOn

Step names that must pass before this step.

beforeRun, afterRun, onError

Lifecycle hooks.

Example:

.step('Flaky step', async (ctx) => {
  await ctx.page.click('#button');
}, {
  timeout: 10000,
  critical: true,
  retry: {
    times: 3,
    delay: 1000,
    backoff: 'exponential',
  },
  skip: (ctx) => ctx.data.skipFlaky,
  beforeRun: (ctx) => ctx.log('Starting flaky step'),
  afterRun: (ctx) => ctx.log('Flaky step passed'),
  onError: (error, ctx) => ctx.log('Flaky step failed:', error.message),
})

Default Configuration

const DEFAULT_CONFIG: StepwrightConfig = {
  browser: 'chromium',
  headless: true,
  defaultTimeout: 30000,
  stopOnFailure: true,
  screenshotOnFailure: true,
  domOnFailure: true,
  artifactDir: '.stepwright/artifacts',
  verbose: false,
};

Complete Example

Stepwright.create('Fully Configured')
  .config({
    // Browser
    browser: 'chromium',
    headless: false,
    launchOptions: {
      slowMo: 50,
    },
    contextOptions: {
      viewport: { width: 1920, height: 1080 },
      locale: 'en-US',
    },


    // Execution
    defaultTimeout: 30000,
    stopOnFailure: true,
    screenshotOnFailure: true,
    domOnFailure: true,


    // Video
    video: {
      enabled: true,
      dir: './videos',
    },


    // Output
    artifactDir: './artifacts',
    verbose: true,
  })
  .reporter(new ConsoleReporter())
  .reporter(new JSONReporter({ outputPath: './results.json' }))


  .checkpoint('Main Flow', {
    required: true,
    maxRetries: 2,
  })
    .step('Step with options', async (ctx) => {
      // ...
    }, {
      timeout: 60000,
      retry: { times: 3, delay: 1000 },
    })
  .endCheckpoint();

See Also