Types

Types

Complete TypeScript type definitions exported by @korvol/stepwright.

Import

import type {
  StepwrightConfig,
  StepwrightResult,
  StepwrightContext,
  StepResult,
  CheckpointResult,
  StepOptions,
  RetryConfig,
  Reporter,
  FailureCase,
} from '@korvol/stepwright';

Result Types

StepwrightResult

Result returned by script.run().

interface StepwrightResult<TData = Record<string, unknown>> {
  /** Whether all steps passed */
  success: boolean;

  /** Total execution time in milliseconds */
  duration: number;

  /** Number of steps that completed (passed or skipped) */
  stepsCompleted: number;

  /** Total number of steps */
  totalSteps: number;

  /** Results for each step */
  steps: StepResult[];

  /** Checkpoint results (if checkpoints used) */
  checkpoints?: CheckpointResult[];

  /** Final data state */
  data: TData;

  /** Failed step info (if any) */
  failedStep?: {
    name: string;
    index: number;
    checkpoint?: string;
    error: Error;
    artifacts: StepArtifacts;
  };

  /** Video path (if recording enabled) */
  video?: string;
}

StepResult

Result for an individual step.

interface StepResult {
  /** Step name */
  name: string;

  /** Step index (0-based) */
  index: number;

  /** Final status */
  status: StepStatus;

  /** Duration in milliseconds */
  duration: number;

  /** Number of retry attempts */
  retryAttempts: number;

  /** Error if failed */
  error?: Error;

  /** Captured artifacts */
  artifacts?: StepArtifacts;

  /** Checkpoint this step belongs to */
  checkpoint?: string;
}

StepStatus

Possible step statuses.

type StepStatus = 'pending' | 'running' | 'passed' | 'failed' | 'skipped';

CheckpointResult

Result for a checkpoint.

interface CheckpointResult {
  /** Checkpoint name */
  name: string;

  /** Final status */
  status: 'passed' | 'failed' | 'skipped';

  /** Duration in milliseconds */
  duration: number;

  /** Number of retry attempts */
  retryAttempts: number;

  /** Steps in this checkpoint */
  steps: StepResult[];
}

StepArtifacts

Artifacts captured for a step.

interface StepArtifacts {
  /** Path to screenshot */
  screenshot?: string;

  /** Path to DOM snapshot */
  dom?: string;

  /** URL at time of capture */
  url?: string;

  /** Page title at time of capture */
  title?: string;

  /** Path to console log file */
  console?: string;
}

Configuration Types

StepwrightConfig

Main configuration interface.

interface StepwrightConfig {
  name?: string;
  browser?: BrowserType;
  headless?: boolean;
  launchOptions?: LaunchOptions;
  contextOptions?: BrowserContextOptions;
  defaultTimeout?: number;
  stopOnFailure?: boolean;
  screenshotOnFailure?: boolean;
  domOnFailure?: boolean;
  video?: VideoConfig;
  reporters?: Reporter[];
  artifactDir?: string;
  verbose?: boolean;
}

BrowserType

Supported browser types.

type BrowserType = 'chromium' | 'firefox' | 'webkit';

VideoConfig

Video recording configuration.

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

RetryConfig

Retry configuration for steps.

interface RetryConfig {
  /** Number of retry attempts */
  times: number;

  /** Delay between retries in ms */
  delay?: number;

  /** Backoff strategy */
  backoff?: 'linear' | 'exponential';
}

Step Types

StepDefinition

Full step definition.

interface StepDefinition<TCtx extends StepwrightContext = StepwrightContext> {
  /** Step name (must be unique) */
  name: string;

  /** Step execution function */
  run: (ctx: TCtx) => void | Promise<void>;

  /** Checkpoint this step belongs to */
  checkpoint?: string;

  /** Whether this step is critical */
  critical?: boolean;

  /** Step timeout in milliseconds */
  timeout?: number;

  /** Retry configuration */
  retry?: RetryConfig;

  /** Condition to skip this step */
  skip?: (ctx: TCtx) => boolean | Promise<boolean>;

  /** Dependencies (step names that must pass first) */
  dependsOn?: string[];

  /** Hook before step runs */
  beforeRun?: (ctx: TCtx) => void | Promise<void>;

  /** Hook after step runs */
  afterRun?: (ctx: TCtx) => void | Promise<void>;

  /** Hook on step error */
  onError?: (error: Error, ctx: TCtx) => void | Promise<void>;
}

StepOptions

Options for defining a step (excludes name and run).

type StepOptions<TCtx> = Omit<StepDefinition<TCtx>, 'name' | 'run'>;

CheckpointDefinition

Checkpoint definition.

interface CheckpointDefinition {
  /** Checkpoint name */
  name: string;

  /** Whether checkpoint is required to pass */
  required?: boolean;

  /** Max retries for this checkpoint */
  maxRetries?: number;

  /** Setup function for checkpoint restart */
  setup?: () => void | Promise<void>;

  /** Teardown function after checkpoint */
  teardown?: () => void | Promise<void>;
}

Context Types

StepwrightContext

Full context available to steps.

interface StepwrightContext<TData = Record<string, unknown>> {
  readonly browser: Browser;
  readonly browserContext: BrowserContext;
  page: Page;
  readonly config: StepwrightConfig;
  data: TData;
  locators: Record<string, Locator>;
  readonly step: CurrentStepInfo | null;
  readonly results: StepResult[];
  readonly pages: Map<string, Page>;

  log(message: string, ...args: unknown[]): void;
  screenshot(name?: string): Promise<string>;
  getDOM(selector?: string): Promise<string>;
  evaluate<T>(fn: () => T): Promise<T>;
  registerPage(name: string, page: Page): void;
  setActivePage(name: string): void;
  snapshot(): ContextSnapshot<TData>;
  restoreLastSnapshot(): void;
}

CurrentStepInfo

Information about the currently executing step.

interface CurrentStepInfo {
  name: string;
  index: number;
  checkpoint?: string;
}

ContextSnapshot

State snapshot for checkpoint recovery.

interface ContextSnapshot<TData = Record<string, unknown>> {
  id: string;
  checkpoint: string;
  state: SerializableState<TData>;
  timestamp: number;
}

Reporter Types

Reporter

Interface for implementing reporters.

interface Reporter {
  onStart?(config: StepwrightConfig): void | Promise<void>;
  onStepStart?(step: StepResult): void | Promise<void>;
  onStepEnd?(step: StepResult): void | Promise<void>;
  onEnd?(result: StepwrightResult): void | Promise<void>;
}

Failure Case Types

FailureCase

Failure case for Fixwright integration.

interface FailureCase {
  id: string;
  status: FailureCaseStatus;
  timestamp: string;
  script: {
    name: string;
    path: string;
    repository?: {
      url: string;
      branch: string;
      commit?: string;
    };
  };
  failure: {
    stepName: string;
    checkpointName?: string;
    error: {
      type: string;
      message: string;
      stack?: string;
    };
    sourceLocation: {
      file: string;
      startLine: number;
      endLine: number;
    };
    sourceCode: string;
    artifacts: {
      screenshot?: string;
      dom?: string;
      console?: string;
    };
    url?: string;
    title?: string;
  };
}

FailureCaseStatus

type FailureCaseStatus = 'pending' | 'processing' | 'fixed' | 'unfixable';

Watcher Types

WatchEvent

Event emitted by watchers.

interface WatchEvent {
  type: WatchEventType;
  url?: string;
  selector?: string;
  timestamp: number;
}

type WatchEventType = 'url_change' | 'dom_change' | 'network' | 'console';

BackgroundTaskDefinition

Background task definition.

interface BackgroundTaskDefinition<TCtx> {
  name: string;
  trigger: {
    type: 'url' | 'dom';
    pattern?: string;
    selector?: string;
  };
  handler: (ctx: TCtx, event: WatchEvent) => void | Promise<void>;
}

See Also

• Stepwright Class - Main class
• Context - Context API
• Config - Configuration options