Recording Adapters

Recording adapters let you customise how the recorder turns raw browser actions into recorded test steps. Each adapter is a TypeScript asset that can extend the recorder's default event set, drop or transform captured events, and take over how a step's description and Playwright code are generated for a specific application.

You create your own adapter for an application by creating a New recording adapter asset by writing a RecordingAdapterDefinition.

What a recording adapter does

When a recording session runs, the recorder watches the page and emits events such as clicks, input, and page navigation. The recording pipeline turns each such event into a step with a description and an executable Playwright action. An adapter sits in this pipeline and can hook into several stages:

Stage

Adapter hook

Purpose

Event capture

additionalEvents

Add extra browser events to observe (for example change, selectionchange, pointerDown).

Event prepare

filterEvent

Decide whether a captured event should be kept or dropped.

Event prepare

transformCapturedEvent

Modify the captured event before it becomes a step.

Step description

onRecordingStepGenerateDescription

Customise the human-readable description of a step.

Step code

onRecordingStepGeneratePlaywright

Customise (or fully replace) the generated Playwright code.

Step finalise

onRecordingStepFinalize

Adjust the final step before it is saved.

Step save

onRecordingStepSave

Hook into the moment the step is saved.

Prerequisites

  • The Recording Adapter Pipeline feature must be enabled.

  • Adapters are stored as TypeScript assets. To edit them you need access to the TypeScript / Playwright editor for your team.

Create a recording adapter

  1. In the Explorer, open the team or folder where you want the adapter to live.

  2. Open the New menu and choose New recording adapter.

  3. A new TypeScript asset is created, pre-filled with the RecordingAdapterDefinition boilerplate and auto-selected for renaming.

  4. Give the asset a meaningful name.

  5. Edit the definition (see Anatomy of an adapter below).

  6. Save the asset. The asset's assetRole is set to recording_adapter, which makes it appear in the recording-adapter selectors.

Assign an adapter to a scope

You can assign a external adapter at two levels:

  • Team level: set the recording adapter for the team in Team Settings.

  • Test-case level: set the recording adapter for a test case on test case settings.

If no adapter is selected, the recorder falls back to default adapter.

Anatomy of an adapter

The boilerplate for a new adapter looks like this:

TypeScript
export const recordingAdapter: RecordingAdapterDefinition = {
  id: 'my-adapter',
  displayName: 'My Adapter',
  hostFragments: [ ],
  additionalEvents: [ ],

  preferLlmOverNative: (context) => {
    return false;
  },

  filterEvent: async (context, base, next) => {
    await base(context);
    await next();
  },

  transformCapturedEvent: async (context, base, next) => {
    await base(context);
    await next();
  },

  onRecordingStepGenerateDescription: async (context, base, next) => {
    await base(context);
    await next();
  },

  onRecordingStepGeneratePlaywright: async (context, base, next) => {
    await base(context);
    await next();
  },

  onRecordingStepFinalize: async (context, base, next) => {
    await base(context);
    await next();
  },

  onRecordingStepSave: async (context, base, next) => {
    await base(context);
    await next();
  },
};

Top-level fields

Field

Type

Description

id

string

Unique identifier for the adapter.

displayName

string

Human-readable name shown in selectors and logs.

hostFragments

string[]

Hostname fragments used to auto-match the adapter to a page. The adapter is selected when the recorded page hostname contains any fragment (case-insensitive).

additionalEvents

string[]

Extra browser events to observe beyond the recorder defaults. Values are trimmed and lower-cased.

preferLlmOverNative

(context) => boolean

When true and native Playwright generation is enabled, the adapter opts into the LLM code path instead.

Default events

The recorder observes these events out of the box (the default RecordingEventName set):

  • recording.browser.click

  • recording.browser.input

  • recording.browser.keydown

Use additionalEvents to observe more events (for example change, selectionchange, pointerDown). Any extra event name you list is added to the recorder session's event set. Event names are trimmed and lower-cased, and duplicates are removed.

The adapter pipeline

Each pipeline stage is a middleware chain. It receives three arguments:

  • context - the stage-specific context (see below).

  • base - invokes the adapter's previous/default stage behaviour for this stage.

  • next - continues to the next step in the pipeline.

base and next give you three ways to write a adapter defination:

  • Keep the default behaviour, then adjust it. Call await base(context) first, then modify the fields on context, then await next():

    TypeScript
    onRecordingStepGenerateDescription: async (context, base, next) => {
      await base(context);            // run the standard description generation
      context.finalStep.description = context.finalStep.description.toUpperCase();
      await next();
    },
    
  • Replace the default behaviour entirely. Do not call base(context) and instead write your own values onto context, then await next(). Because base() was never invoked, the standard outcome is skipped and your values are used:

    TypeScript
    onRecordingStepGenerateDescription: async (context, base, next) => {
      // no await base(...) -> the standard generation is skipped
      context.finalStep.description = 'Custom description';
      await next();
    },
    
  • Gate the outcome. Call base(context) but then conditionally change (or drop) the result before next(). For filterEvent in particular, setting context.cancelled after (or instead of) calling base() drops the event entirely.

    Calling only base() (and not next()) also stops the pipeline at that stage, which is how an event is discarded in filterEvent without producing a step.

The overall per-step pipeline order is:

  1. onRecordingStepGenerateDescription

  2. onRecordingStepGeneratePlaywright

  3. onRecordingStepFinalize

  4. onRecordingStepSave

The event prepare stage runs before the step stages:

  1. filterEvent

  2. transformCapturedEvent

filterEvent - dropping events

Use filterEvent to discard events you do not want as steps. Set context.cancelled = true.

TypeScript
filterEvent: async (context, base, next) => {
  await base(context);
  if (context.eventName === 'recording.browser.input') {
    context.cancelled = true; // do not record text input in this application
    return;
  }
  await next();
},

transformCapturedEvent - modifying captured content

Use transformCapturedEvent to normalise or enrich the captured event before it is turned into a step. The context exposes the captured content (action, selector, value, page URL, and the raw action) that you can adjust.

TypeScript
transformCapturedEvent: async (context, base, next) => {
  context.captured.friendlyName = 'click' + context.captured.friendlyName;
  await next();
},

onRecordingStepGenerateDescription

Customise the step's description. Run base(context) first to use the default description generation, then override the fields you care about.

onRecordingStepGeneratePlaywright

Customise the generated Playwright code for the step. The context exposes the element info, the captured action, and the target. Run base(context) first to generate the default code, then replace context.finalStep.playwrightCode if needed.

Because base() is optional, you can also generate entirely custom Playwright code for any type of element by skipping base() and writing your own code onto context.finalStep.playwrightCode.

TypeScript
onRecordingStepGeneratePlaywright: async (context, base, next) => {
  // no await base(...) -> the default code generation is skipped
  switch (context.captured.action) {
    case 'click':
      context.finalStep.playwrightCode =
        `await page.locator('${ context.captured.selector }').click();`;
      break;
    case 'input':
      context.finalStep.playwrightCode =
        `await page.getByRole('textbox').fill(${context.captured.value});`;
      break;
    default:
      // use the default generation for anything this adapter does not special-case
      await base(context);
      break;
  }
  await next();
},

The generated code can target any element type you can describe with a Playwright selector/locator, so this hook is where you add recorder support for custom controls, file inputs, sliders, canvas elements, and so on.

Native vs LLM code generation

By default, if native Playwright recording is enabled, the recorder uses the native path to build the step code. The built-in native generation includes special handling for interactive elements such as checkboxes and radio buttons.

Setting preferLlmOverNative to true switches the adapter to the LLM code path:

TypeScript
preferLlmOverNative: (context) => {
  if(context.captured.action === 'click'){
    return true;
  }
  return false;
},

Applying an adapter during a recording

When you start a recording for a page, the resolver:

  1. Normalises your selected adapter's additionalEvents.

  2. Adds the adapter's additionalEvents to the recorder session's event set.

  3. Runs the prepare and step pipeline for each recorded event.

Example

A minimal adapter that drops all recording.browser.change events and attaches a friendlier step description for inputs:

TypeScript
export const recordingAdapter: RecordingAdapterDefinition = {
  id: 'my-app',
  displayName: 'My App',
  hostFragments: ['example.com'],
  additionalEvents: ['pointerdown', 'change'],

  filterEvent: async (context, base, next) => {
    await base(context);
    if (context.eventName === 'recording.browser.change') {
      context.cancelled = true;
      return;
    }
    await next();
  },

  onRecordingStepGenerateDescription: async (context, base, next) => {
    await base(context);
    if (context.captured.action === 'input') {
      context.finalStep.description =
        'Type into ' + (context.captured.friendlyName || 'field');
    }
    await next();
  },
};

Troubleshooting

  • The adapter does not apply to a page. Confirm the Recording Adapter Pipeline feature is enabled.

  • Events you expect are not captured. Add them to additionalEvents. Only the default event set plus your additionalEvents are observed.

  • Steps are still generated. filterEvent must set context.cancelled = true to drop an event; calling only base() keeps the behavior.

  • An external adapter fails to load. The asset must export a valid RecordingAdapterDefinition. Check the editor for type/export errors after saving.