Implementation:Microsoft Playwright Client Selectors

Knowledge Sources	Microsoft_Playwright
Domains	Browser Automation, Element Selection
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for managing custom selector engines and test ID attributes for element selection provided by the Playwright library.

Description

The Selectors class implements the api.Selectors interface and manages custom selector engine registration and test ID attribute configuration. It maintains an internal list of registered SelectorEngine definitions and a set of BrowserContext instances that receive selector registrations.

The register() method accepts a selector engine name, a script (as a string, function, or object with path/content), and optional options. It validates uniqueness, evaluates the script source, and propagates the registration to all tracked browser contexts.

The setTestIdAttribute() method configures the attribute name used by getByTestId() locators (defaulting to data-testid), updating both the local locator configuration and all active browser contexts.

The internal _withSelectorOptions() method merges selector engines and test ID configuration into options objects for browser context creation.

Usage

Use Selectors to register custom selector engines (e.g., for shadow DOM, custom components) or to configure the test ID attribute used by getByTestId(). Access it via playwright.selectors.

Code Reference

Source Location

• Repository: Microsoft_Playwright
• File: packages/playwright-core/src/client/selectors.ts

Signature

export class Selectors implements api.Selectors {
  readonly _contextsForSelectors: Set<BrowserContext>;

  constructor(platform: Platform);

  async register(
    name: string,
    script: string | (() => SelectorEngine) | { path?: string; content?: string },
    options?: { contentScript?: boolean }
  ): Promise<void>;

  setTestIdAttribute(attributeName: string): void;
}

Import

import { Selectors } from 'playwright-core/src/client/selectors';

I/O Contract

Inputs

Name	Type	Required	Description
platform	Platform	Yes	The platform abstraction (constructor parameter)
name	string	Yes	Unique name for the selector engine
script	Function \| { path?: string; content?: string }	Yes	The selector engine implementation
options.contentScript	boolean	No	Whether to inject the engine as a content script
attributeName	string	Yes	The attribute name for test ID selectors

Outputs

Name	Type	Description
register()	Promise<void>	Registers the selector engine with all active browser contexts
setTestIdAttribute()	void	Updates the test ID attribute name globally

Usage Examples

const { selectors, chromium } = require('playwright');

// Register a custom selector engine
await selectors.register('my-engine', () => ({
  query(root, selector) {
    return root.querySelector(`[data-my-attr="${selector}"]`);
  },
  queryAll(root, selector) {
    return [...root.querySelectorAll(`[data-my-attr="${selector}"]`)];
  },
}));

// Use the custom selector
const element = await page.locator('my-engine=value');

// Configure test ID attribute
selectors.setTestIdAttribute('data-test');
const button = page.getByTestId('submit-button');

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment