Implementation:Microsoft Playwright Recorder SetMode

Knowledge Sources	Playwright Playwright Codegen Playwright Assertions
Domains	Testing, Code_Generation, Test_Verification
Last Updated	2026-02-11 00:00 GMT

Overview

Concrete tool for switching between recording and assertion modes during a codegen session, provided by the Playwright library.

Description

The Recorder.setMode() method controls the recorder's current operating mode, enabling users to switch between capturing actions and capturing assertions. The Mode type includes both the primary recording mode and several assertion sub-modes, each targeting a specific element property for verification.

When the mode is changed:

1. The Recorder updates its internal _mode state (L269-281).
2. The mode change is propagated to the RecorderApp inspector UI via the dispatcher (L148-154 in recorderApp.ts).
3. The injected recorder script in the browser updates its behavior: in assertion modes, hovering highlights elements and clicking generates assertions instead of actions.
4. The _isRecording() check (L454-456) returns true for all assertion modes, recognizing them as sub-modes of the recording state.

The assertion modes generate specific Playwright test assertions:

• assertingText: Reads the text content of the clicked element and generates toContainText() or toHaveText() depending on whether the match is partial or exact.
• assertingVisibility: Generates toBeVisible() for the clicked element.
• assertingValue: Reads the value property of an input element and generates toHaveValue().
• assertingChecked: Reads the checked state of a checkbox/radio and generates toBeChecked().
• assertingSnapshot: Computes the ARIA accessibility tree of the element and generates toMatchAriaSnapshot().

The assertion code generation is handled by each LanguageGenerator. For example, in the JavaScript/TypeScript generator (at javascript.ts:L113-127), assertion actions are mapped to their corresponding expect() calls with the appropriate matcher.

Additionally, the setAutoExpect flag enables precondition assertions, which are automatically generated assertions that verify the page state before performing an action. This feature adds implicit verification steps without requiring the user to manually switch to assertion mode.

Usage

Use this method when you need to:

• Add verification steps to a recording by switching to an assertion mode.
• Programmatically control the recorder mode in custom tooling.
• Implement assertion recording in IDE extensions or custom recorder UIs.

Code Reference

Source Location

• Repository: playwright
• File: packages/playwright-core/src/server/recorder.ts
• Lines: L269-281 (setMode), L454-456 (_isRecording)
• Related file: packages/playwright-core/src/server/recorder/recorderApp.ts
• Lines: L148-154 (mode dispatch to UI)

Signature

// Mode type definition
type Mode = 'recording' | 'inspecting' | 'standby'
  | 'assertingText' | 'assertingVisibility'
  | 'assertingValue' | 'assertingSnapshot';

// Recorder method
class Recorder {
  setMode(mode: Mode): void;

  // Internal check - assertion modes are considered recording
  private _isRecording(): boolean {
    return ['recording', 'assertingText', 'assertingVisibility',
            'assertingValue', 'assertingSnapshot'].includes(this._mode);
  }
}

Import

// Internal API - mode changes are triggered via the inspector UI
// or programmatically through the Recorder instance
// Mode type from: @recorder/recorderTypes

Assertion Code Generation (javascript.ts:L113-127)

// Assertion action to generated code mapping:
switch (action.name) {
  case 'assertText':
    // -> await expect(locator).toContainText('expected text');
    // -> await expect(locator).toHaveText('exact text');
    break;
  case 'assertChecked':
    // -> await expect(locator).toBeChecked();
    break;
  case 'assertVisible':
    // -> await expect(locator).toBeVisible();
    break;
  case 'assertValue':
    // -> await expect(locator).toHaveValue('expected value');
    break;
  case 'assertSnapshot':
    // -> await expect(locator).toMatchAriaSnapshot(`snapshot`);
    break;
}

I/O Contract

Inputs

Name	Type	Required	Description
mode	Mode	Yes	The target mode to switch to. One of: 'recording' (capture actions), 'inspecting' (highlight elements without recording), 'standby' (paused), 'assertingText' (capture text assertions), 'assertingVisibility' (capture visibility assertions), 'assertingValue' (capture value assertions), 'assertingSnapshot' (capture ARIA snapshot assertions).
setAutoExpect	boolean	No	When true, enables automatic precondition assertions that verify page state before each action. This generates assertion code automatically without requiring manual mode switching.

Outputs

Name	Type	Description
Mode change event	Event	Propagated to the RecorderApp UI to update button states and visual indicators.
Updated highlight behavior	Visual	In assertion modes, hovering over elements shows an assertion-specific highlight instead of an action highlight.
Assertion actions	ActionInContext	When an element is clicked in assertion mode, an assertion action record is emitted (e.g., assertText, assertVisible, assertValue, assertSnapshot).
Generated assertion code	string	The assertion action is translated to language-specific assertion code by the active LanguageGenerator and displayed in the inspector.

Usage Examples

Basic Example

// Switch to text assertion mode
recorder.setMode('assertingText');
// User clicks on an element with text "Welcome, John"
// Generated code:
// await expect(page.getByRole('heading')).toContainText('Welcome, John');

// Switch to visibility assertion mode
recorder.setMode('assertingVisibility');
// User clicks on a success message element
// Generated code:
// await expect(page.getByText('Operation successful')).toBeVisible();

// Switch back to recording mode
recorder.setMode('recording');
// User actions are captured as normal (click, fill, etc.)

All Assertion Modes

// Text assertion
recorder.setMode('assertingText');
// Click on element -> await expect(locator).toContainText('...');
// or             -> await expect(locator).toHaveText('...');

// Visibility assertion
recorder.setMode('assertingVisibility');
// Click on element -> await expect(locator).toBeVisible();

// Value assertion (for input elements)
recorder.setMode('assertingValue');
// Click on input  -> await expect(locator).toHaveValue('...');

// ARIA snapshot assertion
recorder.setMode('assertingSnapshot');
// Click on element -> await expect(locator).toMatchAriaSnapshot(`
//   heading "Dashboard" [level=1]
//   list:
//     - listitem: "Item 1"
//     - listitem: "Item 2"
// `);

Inspector UI Interaction

// The RecorderApp dispatches mode changes from the UI:
// recorderApp.ts L148-154
class RecorderApp {
  async setMode(mode: Mode): Promise<void> {
    // Called when user clicks assertion buttons in the inspector
    this._recorder.setMode(mode);
  }
}

// The inspector UI shows buttons for each mode:
// [Record] [Assert Text] [Assert Visibility] [Assert Value] [Assert Snapshot]
// The active mode button is highlighted

Related Pages

Implements Principle

• Principle:Microsoft_Playwright_Add_Assertions