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 |
|
Add extra browser events to observe (for example |
|
Event prepare |
|
Decide whether a captured event should be kept or dropped. |
|
Event prepare |
|
Modify the captured event before it becomes a step. |
|
Step description |
|
Customise the human-readable description of a step. |
|
Step code |
|
Customise (or fully replace) the generated Playwright code. |
|
Step finalise |
|
Adjust the final step before it is saved. |
|
Step save |
|
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
-
In the Explorer, open the team or folder where you want the adapter to live.
-
Open the New menu and choose New recording adapter.
-
A new TypeScript asset is created, pre-filled with the
RecordingAdapterDefinitionboilerplate and auto-selected for renaming. -
Give the asset a meaningful name.
-
Edit the definition (see Anatomy of an adapter below).
-
Save the asset. The asset's
assetRoleis set torecording_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:
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 |
|---|---|---|
|
|
|
Unique identifier for the adapter. |
|
|
|
Human-readable name shown in selectors and logs. |
|
|
|
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). |
|
|
|
Extra browser events to observe beyond the recorder defaults. Values are trimmed and lower-cased. |
|
|
|
When |
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 oncontext, thenawait next():TypeScriptonRecordingStepGenerateDescription: 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 ontocontext, thenawait next(). Becausebase()was never invoked, the standard outcome is skipped and your values are used:TypeScriptonRecordingStepGenerateDescription: 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 beforenext(). ForfilterEventin particular, settingcontext.cancelledafter (or instead of) callingbase()drops the event entirely.Calling only
base()(and notnext()) also stops the pipeline at that stage, which is how an event is discarded infilterEventwithout producing a step.
The overall per-step pipeline order is:
-
onRecordingStepGenerateDescription -
onRecordingStepGeneratePlaywright -
onRecordingStepFinalize -
onRecordingStepSave
The event prepare stage runs before the step stages:
-
filterEvent -
transformCapturedEvent
filterEvent - dropping events
Use filterEvent to discard events you do not want as steps. Set context.cancelled = true.
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.
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.
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:
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:
-
Normalises your selected adapter's
additionalEvents. -
Adds the adapter's
additionalEventsto the recorder session's event set. -
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:
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 youradditionalEventsare observed. -
Steps are still generated.
filterEventmust setcontext.cancelled = trueto drop an event; calling onlybase()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.