dom-to-locator

dom-to-locator

Generate Playwright locator strings from live DOM elements.

What it does

Given any DOM element, produces the best Playwright locator string (e.g. getByRole('button', { name: 'Submit' })) using the same scoring and uniqueness algorithm that powers Playwright's Inspector, Codegen, and recorder tools.

Strategies are tried in priority order: test ID, ARIA role + name, placeholder, label, alt text, text content, title, CSS ID, tag name — falling back to nth-index or full CSS path when nothing else is unique.

Install

pnpm add dom-to-locator

Usage

import { generateLocator, generateLocators, asLocator } from "dom-to-locator";

// Best locator for an element
generateLocator(element);
// => "getByRole('button', { name: 'Submit' })"

// Multiple ranked variants
generateLocators(element);
// => ["getByTestId('submit-btn')", "getByRole('button', { name: 'Submit' })"]

// Custom test ID attribute
generateLocator(element, { testIdAttributeName: "data-cy" });

// Python / Java / C#
generateLocator(element, { language: "python" });
// => 'get_by_role("button", name="Submit")'

// Scoped to a subtree
generateLocator(element, { root: containerElement });

// Format an internal selector string (no DOM needed)
asLocator("javascript", 'internal:role=button[name="Submit"i]');
// => "getByRole('button', { name: 'Submit' })"

API

generateLocator(element, options?): string

Returns the single best Playwright locator for the given element.

generateLocators(element, options?): string[]

Returns multiple locator variants, ranked from best to worst.

generateInternalSelector(element, options?): string

Returns the raw internal selector string before language-specific formatting.

asLocator(language, selector): string

Converts an internal selector string to a language-specific locator. No DOM required.

asLocators(language, selector): string[]

Converts an internal selector string to multiple language-specific locator variants.

Options

Option	Type	Default	Description
testIdAttributeName	string	'data-testid'	HTML attribute used for test IDs
language	Language	'javascript'	Target language: 'javascript', 'python', 'java', 'csharp'
root	Element | Document	document	Scope locator generation to a subtree

How it works

The pipeline has two stages:

1. DOM element to internal selector (browser-side, requires live DOM)

The selectorGenerator inspects the target element and builds candidate selectors using every available strategy (ARIA role, test ID, text, CSS, etc.). Each candidate is scored — lower is better — and tested for uniqueness by querying the DOM. If a selector matches exactly one element (the target), it wins. When no single selector is unique, the generator composes nested selectors (parent >> child) or appends nth= as a last resort.

2. Internal selector to locator string (isomorphic, no DOM needed)

The locatorGenerators module parses the internal selector syntax (internal:role=button[name="Submit"i]) and routes it through a language-specific factory to emit idiomatic code (getByRole('button', { name: 'Submit' }) for JavaScript, get_by_role("button", name="Submit") for Python, etc.).

Scoring priority

Score	Strategy	Locator
1	Test ID	getByTestId(...)
2	Other data-test* attrs	locator('[data-test=...]')
100	ARIA role + name	getByRole('button', { name: '...' })
120	Placeholder	getByPlaceholder(...)
140	Label	getByLabel(...)
160	Alt text	getByAltText(...)
180	Text content	getByText(...)
200	Title	getByTitle(...)
500	CSS ID	locator('#id')
510	ARIA role (no name)	getByRole('button')
10,000	nth-index	.nth(N)
10,000,000	CSS fallback	locator('div > span.class')

Provenance

This package extracts and bundles the locator generation subsystem from Playwright (Apache-2.0). The original code lives across two layers:

• packages/injected/src/selectorGenerator.ts + supporting modules (roleUtils.ts, domUtils.ts, selectorUtils.ts, selectorEvaluator.ts, roleSelectorEngine.ts) — the DOM-side candidate generation and uniqueness testing
• packages/playwright-core/src/utils/isomorphic/ (locatorGenerators.ts, selectorParser.ts, cssParser.ts, cssTokenizer.ts, stringUtils.ts) — the isomorphic selector parsing and locator formatting

The main adaptation is host.ts, a 220-line shim that replaces Playwright's 1,800+ line InjectedScript class, registering only the selector engines that locator generation actually exercises.

License

BSD-3-Clause. Derived from Playwright (Apache-2.0).