Implementation:Microsoft Playwright LocatorGenerators

Knowledge Sources	Microsoft_Playwright
Domains	Code Generation, Locator API
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for generating locator code strings from parsed selectors provided by the Playwright library.

Description

The `locatorGenerators.ts` module converts Playwright's internal parsed selector representation into human-readable locator API code for multiple programming languages (JavaScript, Python, Java, C#, JSONL). It defines the `LocatorFactory` interface that each language generator implements, providing `generateLocator` and `chainLocators` methods. The module supports all locator types: role-based, text, label, placeholder, alt text, title, test ID, nth, first, last, visible filtering, has-text/has-not-text, has/hasNot, frame locators, and logical combinators (and/or/chain). The `asLocator` function is the main entry point that takes a language and internal selector string and returns the corresponding locator API code. Each language generator handles its own quoting, method naming conventions (camelCase vs snake_case), and regex formatting.

Usage

Use this module when generating locator code for display in Playwright's codegen tool, test recorder, trace viewer, or error messages. It translates internal selectors into the user-facing Playwright API syntax.

Code Reference

Source Location

• Repository: Microsoft_Playwright
• File: packages/playwright-core/src/utils/isomorphic/locatorGenerators.ts

Signature

export type Language = 'javascript' | 'python' | 'java' | 'csharp' | 'jsonl';
export type LocatorType = 'default' | 'role' | 'text' | 'label' | 'placeholder' | 'alt' | 'title' | 'test-id' | 'nth' | 'first' | 'last' | 'visible' | 'has-text' | 'has-not-text' | 'has' | 'hasNot' | 'frame' | 'frame-locator' | 'and' | 'or' | 'chain';
export type LocatorBase = 'page' | 'locator' | 'frame-locator';

export interface LocatorFactory {
  generateLocator(base: LocatorBase, kind: LocatorType, body: string | RegExp, options?: LocatorOptions): string;
  chainLocators(locators: string[]): string;
}

export function asLocatorDescription(lang: Language, selector: string): string;
export function asLocators(lang: Language, selector: string): string[];

Import

import { asLocatorDescription, asLocators, Language, LocatorFactory } from '../utils/isomorphic/locatorGenerators';

I/O Contract

Inputs

Name	Type	Required	Description
lang	Language	Yes	Target programming language for code generation
selector	string	Yes	Playwright internal selector string to convert
base	LocatorBase	Yes	Base object type (page, locator, frame-locator)
kind	LocatorType	Yes	Type of locator to generate
body	string or RegExp	Yes	Locator body (selector value, text, role name)
options	LocatorOptions	No	Additional options (exact, attrs, name, hasText)

Outputs

Name	Type	Description
locator code	string	Human-readable locator API code in the target language
locator descriptions	string[]	Array of alternative locator representations

Usage Examples

import { asLocatorDescription } from 'playwright-core/lib/utils/isomorphic/locatorGenerators';

// JavaScript output
const jsLocator = asLocatorDescription('javascript', 'internal:role=button[name="Submit"i]');
// Returns: "getByRole('button', { name: 'Submit' })"

// Python output
const pyLocator = asLocatorDescription('python', 'internal:role=button[name="Submit"i]');
// Returns: "get_by_role('button', name='Submit')"

// Java output
const javaLocator = asLocatorDescription('java', 'internal:role=button[name="Submit"i]');
// Returns: "getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName(\"Submit\"))"

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment