Stepwright Class

Stepwright Class

The main class for creating and running automation scripts.

Import

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

Static Methods

create<TData>(name)

Creates a new Stepwright instance.

static create<T extends Record<string, unknown> = Record<string, unknown>>(
  name: string
): Stepwright<T>

Parameters:

Name	Type	Description
name	string	Name of the script for logging and reporting

Type Parameters:

Name	Constraint	Description
TData	Record<string, unknown>	Shape of the shared data object

Returns: Stepwright<TData>

Example:

// Simple
const script = Stepwright.create('My Script');

// With typed data
interface MyData {
  username: string;
  token?: string;
}
const script = Stepwright.create<MyData>('My Script');

Instance Methods

Configuration Methods

.config(options)

Configure script execution options.

config(cfg: Partial<StepwrightConfig>): this

Parameters:

Name	Type	Description
cfg	Partial<StepwrightConfig>	Configuration options

Returns: this (for chaining)

Example:

.config({
  browser: 'chromium',
  headless: true,
  defaultTimeout: 30000,
  screenshotOnFailure: true,
})

.data(initialData)

Set initial shared data.

data(initialData: TData): this

Parameters:

Name	Type	Description
initialData	TData	Initial data values

Returns: this

Example:

.data({
  username: 'testuser',
  password: 'secret',
})

.video(config)

Enable video recording.

video(enabled: boolean | VideoConfig): this

Parameters:

Name	Type	Description
enabled	boolean | VideoConfig	Enable or configure video

Returns: this

Example:

// Simple enable
.video(true)

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

.reporter(reporter)

Add a reporter for output.

reporter(reporter: Reporter): this

Parameters:

Name	Type	Description
reporter	Reporter	Reporter instance

Returns: this

Example:

.reporter(new ConsoleReporter())
.reporter(new JSONReporter({ outputPath: './results.json' }))

Step Definition Methods

.checkpoint(name, options?)

Start a new checkpoint.

checkpoint(name: string, options?: Omit<CheckpointDefinition, 'name'>): this

Parameters:

Name	Type	Description
name	string	Checkpoint name
options	CheckpointDefinition	Optional checkpoint configuration

Returns: this

Example:

.checkpoint('Login', {
  required: true,
  maxRetries: 3,
})

.endCheckpoint()

End the current checkpoint.

endCheckpoint(): this

Returns: this

Example:

.checkpoint('Login')
  .step('Enter email', ...)
  .step('Submit', ...)
.endCheckpoint()

.step(name, run, options?)

Add a step to the script.

step(
  name: string,
  run: (ctx: StepwrightContext<TData>) => void | Promise<void>,
  options?: StepOptions
): this

Parameters:

Name	Type	Description
name	string	Step name (must be unique)
run	(ctx) => void | Promise<void>	Step execution function
options	StepOptions	Optional step configuration

Returns: this

Example:

.step('Click button', async (ctx) => {
  await ctx.page.click('#submit');
}, {
  timeout: 10000,
  retry: { times: 3 },
})

.background(name, task)

Add a background task.

background(
  name: string,
  task: Omit<BackgroundTaskDefinition, 'name'>
): this

Parameters:

Name	Type	Description
name	string	Task name
task	BackgroundTaskDefinition	Task configuration

Returns: this

Example:

.background('Handle popup', {
  trigger: { type: 'dom', selector: '.modal' },
  handler: async (ctx) => {
    await ctx.page.click('.modal .close');
  },
})

Execution Methods

.run(options?)

Execute the script.

async run(options?: {
  untilStep?: string;
  fromCheckpoint?: string;
}): Promise<StepwrightResult<TData>>

Parameters:

Name	Type	Description
options.untilStep	string	Stop after this step
options.fromCheckpoint	string	Start from this checkpoint

Returns: Promise<StepwrightResult<TData>>

Example:

// Run all steps
const result = await script.run();

// Run until specific step
const result = await script.run({ untilStep: 'Submit form' });

// Start from checkpoint
const result = await script.run({ fromCheckpoint: 'Checkout' });

Complete Example

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

interface LoginData {
  username: string;
  password: string;
  authToken?: string;
}

const script = Stepwright.create<LoginData>('Login Test')
  .config({
    headless: false,
    defaultTimeout: 30000,
    screenshotOnFailure: true,
  })
  .data({
    username: 'testuser',
    password: 'secret123',
  })
  .reporter(new ConsoleReporter())

  .checkpoint('Authentication', { maxRetries: 2 })
    .step('Navigate', async (ctx) => {
      await ctx.page.goto('https://app.example.com/login');
    })
    .step('Enter credentials', async (ctx) => {
      await ctx.page.fill('#username', ctx.data.username);
      await ctx.page.fill('#password', ctx.data.password);
    })
    .step('Submit', async (ctx) => {
      await ctx.page.click('button[type="submit"]');
      await ctx.page.waitForURL('**/dashboard');
    })
    .step('Extract token', async (ctx) => {
      ctx.data.authToken = await ctx.page.evaluate(() =>
        localStorage.getItem('auth_token')
      );
    })
  .endCheckpoint();

const result = await script.run();
console.log('Success:', result.success);
console.log('Token:', result.data.authToken);

See Also

• StepwrightContext - Context API
• StepwrightConfig - Configuration options
• Types - All type definitions