Configuration Reference

This page documents all configuration options for Stepwright and Fixwright.

Stepwright Configuration

Complete Config Interface

interface StepwrightConfig {
  // Browser settings
  headless?: boolean;
  browser?: 'chromium' | 'firefox' | 'webkit';
  launchOptions?: LaunchOptions;

  // Timeouts
  defaultTimeout?: number;
  navigationTimeout?: number;

  // Viewport
  viewport?: {
    width: number;
    height: number;
  };

  // Artifacts
  screenshotOnFailure?: boolean;
  domOnFailure?: boolean;
  consoleOnFailure?: boolean;
  artifactDir?: string;

  // Video recording
  video?: {
    enabled: boolean;
    dir?: string;
    size?: { width: number; height: number };
  };

  // Logging
  verbose?: boolean;
}

Browser Settings

`headless`

Run browser without visible UI.

Type	Default	Required
`boolean`	`true`	No

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

`browser`

Browser engine to use.

Type	Default	Required
`'chromium' \| 'firefox' \| 'webkit'`	`'chromium'`	No

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

`launchOptions`

Playwright browser launch options.

Type	Default	Required
`LaunchOptions`	`{}`	No

.config({
  launchOptions: {
    slowMo: 100,           // Slow down actions
    devtools: true,        // Open DevTools
    args: ['--no-sandbox'], // Chrome flags
  },
})

Timeouts

`defaultTimeout`

Default timeout for all operations in milliseconds.

Type	Default	Required
`number`	`30000`	No

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

`navigationTimeout`

Timeout specifically for navigation operations.

Type	Default	Required
`number`	`30000`	No

.config({
  navigationTimeout: 120000,  // 2 minutes for slow pages
})

Viewport

`viewport`

Browser viewport size.

Type	Default	Required
`{ width: number; height: number }`	`{ width: 1280, height: 720 }`	No

.config({
  viewport: {
    width: 1920,
    height: 1080,
  },
})

Artifacts

`screenshotOnFailure`

Automatically capture screenshot when a step fails.

Type	Default	Required
`boolean`	`true`	No

.config({
  screenshotOnFailure: true,
})

`domOnFailure`

Capture DOM HTML when a step fails.

Type	Default	Required
`boolean`	`false`	No

.config({
  domOnFailure: true,
})

`consoleOnFailure`

Capture browser console logs when a step fails.

Type	Default	Required
`boolean`	`true`	No

.config({
  consoleOnFailure: true,
})

`artifactDir`

Directory for storing artifacts.

Type	Default	Required
`string`	`'.stepwright/artifacts'`	No

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

Video Recording

`video`

Video recording configuration.

Type	Default	Required
`VideoConfig`	`undefined`	No

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

Logging

`verbose`

Enable verbose logging.

Type	Default	Required
`boolean`	`false`	No

.config({
  verbose: true,
})

Fixwright Configuration

Complete Config Interface

interface FixWrightConfig {
  // AI Configuration
  ai: {
    apiKey: string;
    model?: string;
    maxTokens?: number;
    thinking?: {
      type: 'enabled' | 'disabled';
      budgetTokens?: number;
    };
  };

  // Fixing behavior
  maxAttempts?: number;
  maxRetries?: number;

  // Output
  verbosity?: 'quiet' | 'normal' | 'verbose';

  // File handling
  backup?: boolean;
  backupDir?: string;

  // Git integration
  git?: {
    enabled: boolean;
    createBranch?: boolean;
    branchPrefix?: string;
    commitMessage?: string;
  };

  // PR creation
  pr?: {
    enabled: boolean;
    draft?: boolean;
    labels?: string[];
    assignees?: string[];
  };
}

AI Configuration

`ai.apiKey`

Anthropic API key for Claude.

Type	Default	Required
`string`	-	Yes

new FixWright({
  ai: {
    apiKey: process.env.ANTHROPIC_API_KEY!,
  },
})

`ai.model`

Claude model to use.

Type	Default	Required
`string`	`'claude-sonnet-4-20250514'`	No

new FixWright({
  ai: {
    apiKey: '...',
    model: 'claude-sonnet-4-20250514',
  },
})

`ai.maxTokens`

Maximum tokens for AI response.

Type	Default	Required
`number`	`16000`	No

new FixWright({
  ai: {
    apiKey: '...',
    maxTokens: 32000,
  },
})

`ai.thinking`

Extended thinking configuration.

Type	Default	Required
`ThinkingConfig`	`{ type: 'disabled' }`	No

new FixWright({
  ai: {
    apiKey: '...',
    thinking: {
      type: 'enabled',
      budgetTokens: 10000,
    },
  },
})

Fixing Behavior

`maxAttempts`

Maximum fix attempts per failure.

Type	Default	Required
`number`	`3`	No

new FixWright({
  ai: { apiKey: '...' },
  maxAttempts: 5,
})

`maxRetries`

Maximum retries for failed attempts.

Type	Default	Required
`number`	`2`	No

new FixWright({
  ai: { apiKey: '...' },
  maxRetries: 3,
})

Output

`verbosity`

Log verbosity level.

Type	Default	Required
`'quiet' \| 'normal' \| 'verbose'`	`'normal'`	No

new FixWright({
  ai: { apiKey: '...' },
  verbosity: 'verbose',
})

File Handling

`backup`

Create backup of original files before modification.

Type	Default	Required
`boolean`	`true`	No

new FixWright({
  ai: { apiKey: '...' },
  backup: true,
})

`backupDir`

Directory for backups.

Type	Default	Required
`string`	`'.fixwright/backups'`	No

new FixWright({
  ai: { apiKey: '...' },
  backupDir: './script-backups',
})

Git Integration

`git.enabled`

Enable Git integration.

Type	Default	Required
`boolean`	`false`	No

`git.createBranch`

Create a new branch for fixes.

Type	Default	Required
`boolean`	`true`	No

`git.branchPrefix`

Prefix for created branches.

Type	Default	Required
`string`	`'fix/'`	No

`git.commitMessage`

Template for commit messages.

Type	Default	Required
`string`	`'fix: {description}'`	No

new FixWright({
  ai: { apiKey: '...' },
  git: {
    enabled: true,
    createBranch: true,
    branchPrefix: 'fixwright/',
    commitMessage: 'fix({script}): {description}',
  },
})

PR Creation

`pr.enabled`

Enable automatic PR creation.

Type	Default	Required
`boolean`	`false`	No

`pr.draft`

Create PR as draft.

Type	Default	Required
`boolean`	`true`	No

`pr.labels`

Labels to add to PR.

Type	Default	Required
`string[]`	`['fixwright', 'automated']`	No

`pr.assignees`

Assignees for the PR.

Type	Default	Required
`string[]`	`[]`	No

new FixWright({
  ai: { apiKey: '...' },
  git: { enabled: true },
  pr: {
    enabled: true,
    draft: false,
    labels: ['automated-fix', 'needs-review'],
    assignees: ['username'],
  },
})

Configuration Files

`stepwright.config.ts`

Create a configuration file for shared settings:

import type { StepwrightConfig } from '@korvol/stepwright';

const config: StepwrightConfig = {
  headless: process.env.CI === 'true',
  screenshotOnFailure: true,
  domOnFailure: true,
  defaultTimeout: 30000,
  artifactDir: './artifacts',
};

export default config;

`fixwright.config.ts`

import type { FixWrightConfig } from '@korvol/fixwright';

const config: FixWrightConfig = {
  ai: {
    apiKey: process.env.ANTHROPIC_API_KEY!,
    model: 'claude-sonnet-4-20250514',
  },
  maxAttempts: 3,
  verbosity: 'normal',
  backup: true,
  git: {
    enabled: true,
    branchPrefix: 'fix/',
  },
};

export default config;

Next Steps

CLI Commands - Command line options
Environment Variables - Environment configuration