Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

fix(locators): parse locators the way the client API builds them (#43192)

Pavel Feldman1bfdc528c977
diff --git a/packages/isomorphic/locatorParser.ts b/packages/isomorphic/locatorParser.ts
index ada8f9fb78..7a372dead5 100644
--- a/packages/isomorphic/locatorParser.ts
+++ b/packages/isomorphic/locatorParser.ts
@@ -15,9 +15,9 @@
*/
import { regexFlagNames } from './locatorGenerators';
-import { getByAltTextSelector, getByLabelSelector, getByPlaceholderSelector, getByTestIdSelector, getByTextSelector, getByTitleSelector } from './locatorUtils';
-import { parseSelector, stringifySelector } from './selectorParser';
-import { escapeForAttributeSelector, escapeForTextSelector } from './stringUtils';
+import { getByAltTextSelector, getByLabelSelector, getByPlaceholderSelector, getByRoleSelector, getByTestIdSelector, getByTextSelector, getByTitleSelector } from './locatorUtils';
+import { kAnyFrameSelector, parseSelector, stringifySelector } from './selectorParser';
+import { escapeForTextSelector, toSnakeCase, toTitleCase } from './stringUtils';
import type { Language } from './locatorGenerators';
import type { ParsedSelector, ParsedSelectorPart } from './selectorParser';
@@ -29,9 +29,16 @@ type CallArguments = {
method: string;
args: Value[];
options: Map<string, Value>;
+ hasOptions: boolean;
};
-type CallHandler = (call: CallArguments, testIdAttributeName: string) => ParsedSelectorPart[];
+// The object that a method is called on. FrameLocator parts select the frame element.
+type Target = {
+ type: 'Page' | 'Locator' | 'FrameLocator';
+ parts: ParsedSelectorPart[];
+};
+
+type Method = (call: CallArguments, target: Target, testIdAttributeName: string) => Target;
type Token =
| { kind: 'identifier', value: string }
@@ -41,12 +48,16 @@ type Token =
| { kind: 'punctuation', value: string }
| { kind: 'end' };
+type Match = (re: RegExp) => string | undefined;
+
type ParserOptions = {
- methods: Map<string, CallHandler>;
+ methods: Map<string, Method>;
quotes: string;
+ escape: (char: string, match: Match) => string | undefined;
rawStrings?: boolean;
+ verbatimStrings?: boolean;
regexLiterals?: boolean;
- javascriptEscapes?: boolean;
+ trailingCommas?: boolean;
booleans?: [string, string];
};
@@ -54,9 +65,6 @@ const kEscapes = new Map([['n', '\n'], ['r', '\r'], ['t', '\t'], ['b', '\b'], ['
const kIdentifierRegex = /[A-Za-z_$][\w$]*/y;
const kNumberRegex = /-?\d+(\.\d+)?/y;
const kRegexFlagsRegex = /[a-z]*/y;
-const kHexEscapeRegex = /[\da-f]{2}/iy;
-const kUnicodeEscapeRegex = /[\da-f]{4}/iy;
-const kUnicodeCodePointEscapeRegex = /\{[\da-f]{1,6}\}/iy;
function tokenize(source: string, options: ParserOptions): Token[] {
const tokens: Token[] = [];
@@ -76,6 +84,8 @@ function tokenize(source: string, options: ParserOptions): Token[] {
let inCharacterClass = false;
++pos;
while (pos < source.length && (source[pos] !== quote || inCharacterClass)) {
+ if (quote === '`' && source.startsWith('${', pos))
+ throw new Error(`Template literal placeholders are not supported in ${source}`);
if (source[pos] !== '\\') {
const char = source[pos++];
if (regexLiteral) {
@@ -91,16 +101,12 @@ function tokenize(source: string, options: ParserOptions): Token[] {
pos += 2;
if (raw) {
text += next === quote ? next : '\\' + next;
- } else if (next === 'u' || (options.javascriptEscapes && next === 'x')) {
- const braced = next === 'u' && !!options.javascriptEscapes && source[pos] === '{';
- const hex = match(next === 'x' ? kHexEscapeRegex : braced ? kUnicodeCodePointEscapeRegex : kUnicodeEscapeRegex);
- const codePoint = parseInt((braced ? hex?.slice(1, -1) : hex) || '', 16);
- if (Number.isNaN(codePoint) || codePoint > 0x10FFFF)
- throw new Error(`Invalid escape sequence in ${source}`);
- text += String.fromCodePoint(codePoint);
- } else {
- text += kEscapes.get(next) ?? next;
+ continue;
}
+ const escaped = options.escape(next, match);
+ if (escaped === undefined)
+ throw new Error(`Invalid escape sequence in ${source}`);
+ text += escaped;
}
if (pos >= source.length)
throw new Error(`Unterminated ${regexLiteral ? 'regular expression' : 'string'} in ${source}`);
@@ -108,6 +114,22 @@ function tokenize(source: string, options: ParserOptions): Token[] {
return text;
};
+ // C# verbatim strings only escape the quote by doubling it.
+ const readVerbatimString = () => {
+ let text = '';
+ pos += 2;
+ while (pos < source.length) {
+ if (source[pos] === '"' && source[pos + 1] !== '"') {
+ ++pos;
+ return text;
+ }
+ if (source[pos] === '"')
+ ++pos;
+ text += source[pos++];
+ }
+ throw new Error(`Unterminated string in ${source}`);
+ };
+
while (pos < source.length) {
const char = source[pos];
let text: string | undefined;
@@ -117,6 +139,8 @@ function tokenize(source: string, options: ParserOptions): Token[] {
tokens.push({ kind: 'string', value: readString(char, false) });
} else if (options.rawStrings && char === 'r' && options.quotes.includes(source[pos + 1])) {
tokens.push({ kind: 'string', value: readString(source[++pos], true) });
+ } else if (options.verbatimStrings && char === '@' && source[pos + 1] === '"') {
+ tokens.push({ kind: 'string', value: readVerbatimString() });
} else if (options.regexLiterals && char === '/') {
const regexSource = readString('/', true, true);
tokens.push({ kind: 'regex', value: new RegExp(regexSource, match(kRegexFlagsRegex)) });
@@ -135,6 +159,46 @@ function tokenize(source: string, options: ParserOptions): Token[] {
return tokens;
}
+function codePoint(hex: string | undefined): string | undefined {
+ const value = parseInt(hex ?? '', 16);
+ return Number.isNaN(value) || value > 0x10FFFF ? undefined : String.fromCodePoint(value);
+}
+
+function javascriptEscape(char: string, match: Match): string | undefined {
+ if (char === 'x')
+ return codePoint(match(/[\da-f]{2}/iy));
+ if (char === 'u')
+ return codePoint(match(/[\da-f]{4}/iy) ?? match(/\{[\da-f]{1,6}\}/iy)?.slice(1, -1));
+ return kEscapes.get(char) ?? char;
+}
+
+// Unknown escape sequences keep the backslash in Python.
+function pythonEscape(char: string, match: Match): string | undefined {
+ if (char === 'x')
+ return codePoint(match(/[\da-f]{2}/iy));
+ if (char === 'u')
+ return codePoint(match(/[\da-f]{4}/iy));
+ if (char === 'U')
+ return codePoint(match(/[\da-f]{8}/iy));
+ return kEscapes.get(char) ?? ('\\\'"'.includes(char) ? char : '\\' + char);
+}
+
+function javaEscape(char: string, match: Match): string | undefined {
+ if (char === 'u')
+ return codePoint(match(/[\da-f]{4}/iy));
+ return kEscapes.get(char) ?? char;
+}
+
+function csharpEscape(char: string, match: Match): string | undefined {
+ if (char === 'x')
+ return codePoint(match(/[\da-f]{1,4}/iy));
+ if (char === 'u')
+ return codePoint(match(/[\da-f]{4}/iy));
+ if (char === 'U')
+ return codePoint(match(/[\da-f]{8}/iy));
+ return kEscapes.get(char) ?? char;
+}
+
function isToken(token: Token, kind: 'identifier' | 'punctuation', value: string): boolean {
return token.kind === kind && token.value === value;
}
@@ -142,25 +206,24 @@ function isToken(token: Token, kind: 'identifier' | 'punctuation', value: string
abstract class LocatorParser {
private _tokens: Token[];
private _pos = 0;
- private _methods: Map<string, CallHandler>;
+ private _methods: Map<string, Method>;
private _booleans: [string, string];
+ private _trailingCommas: boolean;
private _testIdAttributeName: string;
constructor(source: string, options: ParserOptions, testIdAttributeName: string) {
this._tokens = tokenize(source, options);
this._methods = options.methods;
this._booleans = options.booleans ?? ['true', 'false'];
+ this._trailingCommas = !!options.trailingCommas;
this._testIdAttributeName = testIdAttributeName;
}
parse(): ParsedSelector {
- const selector = this.parseLocator();
+ const target = this.parseLocator();
if (this.peek().kind !== 'end')
this.unexpected();
- // Same as in parseSelector(), nested selectors like internal:chain cannot be first.
- if (selector.parts.length && isNestedSelectorPart(selector.parts[0]))
- throw new Error(`"${selector.parts[0].name}" selector cannot be first`);
- return selector;
+ return { parts: target.type === 'FrameLocator' ? childParts(target, []) : target.parts };
}
// Parses a single argument that is either a positional value or an options bag.
@@ -169,42 +232,39 @@ abstract class LocatorParser {
// Parses a language-specific regular expression, e.g. `re.compile(...)`.
protected abstract parseRegex(): RegExp | undefined;
- protected parseLocator(): ParsedSelector {
- let parts: ParsedSelectorPart[] = [];
- // FrameLocator enters the frame lazily, so that first(), last() and nth() apply to the frame element.
- let inFrameLocator = false;
+ protected parseLocator(): Target {
+ let target: Target = { type: 'Page', parts: [] };
do {
- const { handler, call } = this.parseCall();
- if (inFrameLocator && !kFrameElementHandlers.has(handler)) {
- parts.push(selectorPart('internal:control', 'enter-frame'));
- inFrameLocator = false;
- }
- const callParts = handler(call, this._testIdAttributeName);
- if (handler === withinParts)
- parts = [...callParts, nestedSelectorPart('internal:chain', { parts })];
- else
- parts.push(...callParts);
- if (handler === contentFrameParts || (handler === frameLocatorParts && call.args.length))
- inFrameLocator = true;
+ const name = this.expectIdentifier();
+ const method = this._methods.get(name);
+ if (!method)
+ throw new Error(`Unsupported locator method ${name}`);
+ target = method(this.parseArguments(name), target, this._testIdAttributeName);
} while (this.eat('.'));
- if (inFrameLocator)
- parts.push(selectorPart('internal:control', 'enter-frame'));
- return { parts };
+ return target;
}
- private parseCall(): { handler: CallHandler, call: CallArguments } {
- const method = this.expectIdentifier();
- const handler = this._methods.get(method);
- if (!handler)
- throw new Error(`Unsupported locator method ${method}`);
- const call: CallArguments = { method, args: [], options: new Map() };
+ private parseArguments(method: string): CallArguments {
+ const call: CallArguments = { method, args: [], options: new Map(), hasOptions: false };
if (this.eat('(') && !this.eat(')')) {
do
this.parseArgument(call);
- while (this.eat(','));
+ while (this.eat(',') && !(this._trailingCommas && isToken(this.peek(), 'punctuation', ')')));
this.expect(')');
}
- return { handler, call };
+ return call;
+ }
+
+ protected addArgument(call: CallArguments, value: Value) {
+ if (call.hasOptions)
+ throw new Error(`Unexpected argument after options for ${call.method}`);
+ call.args.push(value);
+ }
+
+ protected startOptions(call: CallArguments) {
+ if (call.hasOptions)
+ throw new Error(`Unexpected options for ${call.method}`);
+ call.hasOptions = true;
}
protected parseValue(): Value {
@@ -225,11 +285,18 @@ abstract class LocatorParser {
this.expect('.');
return this.expectIdentifier().toLowerCase();
}
- return this.parseRegex() ?? this.parseLocator();
+ const regex = this.parseRegex();
+ if (regex)
+ return regex;
+ const target = this.parseLocator();
+ if (target.type !== 'Locator')
+ throw new Error(`Expected a locator, got ${target.type}`);
+ return { parts: target.parts };
}
// Parses `{ name <separator> value, ... }` after the opening brace.
protected parseOptionsBag(call: CallArguments, separator: string, optionName: (identifier: string) => string) {
+ this.startOptions(call);
while (!this.eat('}')) {
const name = optionName(this.expectIdentifier());
this.expect(separator);
@@ -241,17 +308,21 @@ abstract class LocatorParser {
}
}
- // Parses `(source[, <flagsEnum>.<flag> ( "|" <flagsEnum>.<flag> )*])`.
- protected parseRegexArguments(flagsEnum: string, flagNames: Record<string, string>): RegExp {
+ // Parses `(source[, [flagsKeyword=]<flagsEnum>.<flag> ( "|" <flagsEnum>.<flag> )*])`.
+ protected parseRegexArguments(flagsEnum: string, flagsByName: Map<string, string>, flagsKeyword?: string): RegExp {
this.expect('(');
const source = this.expectString();
let flags = '';
if (this.eat(',')) {
+ if (flagsKeyword && isToken(this.peek(1), 'punctuation', '=')) {
+ this.expectIdentifier(flagsKeyword);
+ this.expect('=');
+ }
do {
this.expectIdentifier(flagsEnum);
this.expect('.');
const name = this.expectIdentifier();
- const flag = Object.keys(flagNames).find(flag => flagNames[flag] === name);
+ const flag = flagsByName.get(name);
if (!flag)
throw new Error(`Unsupported regular expression flag ${flagsEnum}.${name}`);
flags += flag;
@@ -315,35 +386,43 @@ abstract class LocatorParser {
// getByRole('button', { name: /submit/i, exact: true })
class JavaScriptLocatorParser extends LocatorParser {
constructor(source: string, testIdAttributeName: string) {
- super(source, { methods: kJavaScriptMethods, quotes: '\'"`', regexLiterals: true, javascriptEscapes: true }, testIdAttributeName);
+ super(source, { methods: kJavaScriptMethods, quotes: '\'"`', escape: javascriptEscape, regexLiterals: true, trailingCommas: true }, testIdAttributeName);
}
protected parseArgument(call: CallArguments) {
if (this.eat('{'))
this.parseOptionsBag(call, ':', name => name);
else
- call.args.push(this.parseValue());
+ this.addArgument(call, this.parseValue());
}
- // Regular expression literals are tokens.
+ // Regular expression literals are tokens, so only `new RegExp(source, flags)` is parsed here.
protected parseRegex(): RegExp | undefined {
- return undefined;
+ if (!this.eatIdentifier('new'))
+ return;
+ this.expectIdentifier('RegExp');
+ this.expect('(');
+ const source = this.expectString();
+ const flags = this.eat(',') ? this.expectString() : '';
+ this.expect(')');
+ return new RegExp(source, flags);
}
}
// get_by_role("button", name=re.compile(r"submit", re.IGNORECASE), exact=True)
class PythonLocatorParser extends LocatorParser {
constructor(source: string, testIdAttributeName: string) {
- super(source, { methods: kPythonMethods, quotes: '\'"', rawStrings: true, booleans: ['True', 'False'] }, testIdAttributeName);
+ super(source, { methods: kPythonMethods, quotes: '\'"', escape: pythonEscape, rawStrings: true, trailingCommas: true, booleans: ['True', 'False'] }, testIdAttributeName);
}
protected parseArgument(call: CallArguments) {
if (!isToken(this.peek(1), 'punctuation', '=')) {
- call.args.push(this.parseValue());
+ this.addArgument(call, this.parseValue());
return;
}
const name = this.expectIdentifier();
this.expect('=');
+ call.hasOptions = true;
call.options.set(name.replace(/_([a-z])/g, (_, char) => char.toUpperCase()), this.parseValue());
}
@@ -352,21 +431,22 @@ class PythonLocatorParser extends LocatorParser {
return;
this.expect('.');
this.expectIdentifier('compile');
- return this.parseRegexArguments('re', regexFlagNames.python);
+ return this.parseRegexArguments('re', kPythonRegexFlags, 'flags');
}
}
// getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName(Pattern.compile("submit", Pattern.CASE_INSENSITIVE)).setExact(true))
class JavaLocatorParser extends LocatorParser {
constructor(source: string, testIdAttributeName: string) {
- super(source, { methods: kJavaScriptMethods, quotes: '"' }, testIdAttributeName);
+ super(source, { methods: kJavaScriptMethods, quotes: '"', escape: javaEscape }, testIdAttributeName);
}
protected parseArgument(call: CallArguments) {
if (!this.eatIdentifier('new')) {
- call.args.push(this.parseValue());
+ this.addArgument(call, this.parseValue());
return;
}
+ this.startOptions(call);
// Options class, e.g. `Locator.FilterOptions`.
this.expectIdentifier();
this.expect('.');
@@ -388,35 +468,51 @@ class JavaLocatorParser extends LocatorParser {
return;
this.expect('.');
this.expectIdentifier('compile');
- return this.parseRegexArguments('Pattern', regexFlagNames.java);
+ return this.parseRegexArguments('Pattern', flagsByName(regexFlagNames.java));
}
}
// GetByRole(AriaRole.Button, new() { NameRegex = new Regex("submit", RegexOptions.IgnoreCase), Exact = true })
class CSharpLocatorParser extends LocatorParser {
constructor(source: string, testIdAttributeName: string) {
- super(source, { methods: kCSharpMethods, quotes: '"' }, testIdAttributeName);
+ super(source, { methods: kCSharpMethods, quotes: '"', escape: csharpEscape, verbatimStrings: true }, testIdAttributeName);
}
protected parseArgument(call: CallArguments) {
- // `new() { ... }` is an options bag, while `new Regex(...)` is a value.
- if (!isToken(this.peek(), 'identifier', 'new') || !isToken(this.peek(1), 'punctuation', '(')) {
- call.args.push(this.parseValue());
+ if (!this.eatOptionsType()) {
+ this.addArgument(call, this.parseValue());
return;
}
- this.next();
- this.expect('(');
- this.expect(')');
this.expect('{');
// Regular expression options have a "Regex" suffix, e.g. `NameRegex`.
this.parseOptionsBag(call, '=', name => lowerFirst(name.replace(/Regex$/, '')));
}
+ // `new()`, `new PageGetByRoleOptions` or `new PageGetByRoleOptions()`, while `new Regex(...)` is a value.
+ private eatOptionsType(): boolean {
+ if (!isToken(this.peek(), 'identifier', 'new'))
+ return false;
+ const type = this.peek(1);
+ if (isToken(type, 'punctuation', '(')) {
+ this.next();
+ this.expect('(');
+ this.expect(')');
+ return true;
+ }
+ if (type.kind !== 'identifier' || !type.value.endsWith('Options'))
+ return false;
+ this.next();
+ this.next();
+ if (this.eat('('))
+ this.expect(')');
+ return true;
+ }
+
protected parseRegex(): RegExp | undefined {
if (!this.eatIdentifier('new'))
return;
this.expectIdentifier('Regex');
- return this.parseRegexArguments('RegexOptions', regexFlagNames.csharp);
+ return this.parseRegexArguments('RegexOptions', flagsByName(regexFlagNames.csharp));
}
}
@@ -427,155 +523,166 @@ const parsers: Partial<Record<Language, new (source: string, testIdAttributeName
csharp: CSharpLocatorParser,
};
-const kFilterOptions = ['hasText', 'hasNotText', 'has', 'hasNot', 'visible'];
+function flagsByName(flagNames: Record<string, string>): Map<string, string> {
+ return new Map(Object.entries(flagNames).map(([flag, name]) => [name, flag]));
+}
-function locatorParts(call: CallArguments): ParsedSelectorPart[] {
- checkArguments(call, 1, kFilterOptions);
- const inner = arg(call, 0, (value): value is string | ParsedSelector => isString(value) || isSelector(value));
- const parts = isString(inner) ? parseSelector(inner).parts : [nestedSelectorPart('internal:chain', inner)];
- return [...parts, ...filterSelectorParts(call)];
+const kPythonRegexFlags = new Map([...flagsByName(regexFlagNames.python), ['I', 'i'], ['M', 'm'], ['S', 's']]);
+
+const kLocatorOptions = ['hasText', 'hasNotText', 'has', 'hasNot'];
+const kFilterOptions = [...kLocatorOptions, 'visible'];
+const kRoleOptions = ['checked', 'disabled', 'selected', 'expanded', 'includeHidden', 'level', 'name', 'description', 'pressed', 'exact'];
+
+function method(types: Target['type'][], handler: Method): Method {
+ return (call, target, testIdAttributeName) => {
+ if (!types.includes(target.type))
+ throw new Error(`Unsupported method ${call.method} for ${target.type}`);
+ return handler(call, target, testIdAttributeName);
+ };
+}
+
+function locator(call: CallArguments, target: Target): Target {
+ checkArguments(call, 1, kLocatorOptions);
+ const inner = target.type === 'Page' ? arg(call, 0, isString) : arg(call, 0, isStringOrSelector);
+ let parts: ParsedSelectorPart[];
+ if (isString(inner))
+ parts = parseSelector(inner).parts;
+ else if (target.type === 'FrameLocator')
+ parts = inner.parts;
+ else
+ parts = [nestedSelectorPart('internal:chain', inner)];
+ return { type: 'Locator', parts: [...childParts(target, parts), ...filterSelectorParts(call)] };
}
-function filterParts(call: CallArguments): ParsedSelectorPart[] {
+function filter(call: CallArguments, target: Target): Target {
checkArguments(call, 0, kFilterOptions);
- return filterSelectorParts(call);
+ return { type: 'Locator', parts: [...target.parts, ...filterSelectorParts(call)] };
}
-function withinParts(call: CallArguments): ParsedSelectorPart[] {
+function within(call: CallArguments, target: Target): Target {
checkArguments(call, 1, []);
- return arg(call, 0, isSelector).parts;
+ return { type: 'Locator', parts: [...arg(call, 0, isSelector).parts, nestedSelectorPart('internal:chain', { parts: target.parts })] };
}
-function nestedParts(name: string): CallHandler {
- return call => {
+function nested(name: string): Method {
+ return (call, target) => {
checkArguments(call, 1, []);
- return [nestedSelectorPart(name, arg(call, 0, isSelector))];
+ return { type: 'Locator', parts: [...target.parts, nestedSelectorPart(name, arg(call, 0, isSelector))] };
};
}
-function frameLocatorParts(call: CallArguments): ParsedSelectorPart[] {
+function frameLocator(call: CallArguments, target: Target): Target {
checkArguments(call, 1, []);
- return call.args.length ? parseSelector(arg(call, 0, isString)).parts : [selectorPart('internal:control', 'any-frame')];
+ if (target.type === 'Page' && !call.args.length)
+ return { type: 'FrameLocator', parts: parseSelector(kAnyFrameSelector).parts };
+ return { type: 'FrameLocator', parts: childParts(target, parseSelector(arg(call, 0, isString)).parts) };
}
-// Entering the frame is deferred by the parser.
-function contentFrameParts(call: CallArguments): ParsedSelectorPart[] {
+function contentFrame(call: CallArguments, target: Target): Target {
checkArguments(call, 0, []);
- return [];
+ return { type: 'FrameLocator', parts: target.parts };
}
-function fixedNthParts(index: string): CallHandler {
- return call => {
- checkArguments(call, 0, []);
- return [selectorPart('nth', index)];
- };
+function owner(call: CallArguments, target: Target): Target {
+ checkArguments(call, 0, []);
+ return { type: 'Locator', parts: target.parts };
}
-function nthParts(call: CallArguments): ParsedSelectorPart[] {
- checkArguments(call, 1, []);
- return [selectorPart('nth', String(arg(call, 0, isNumber)))];
+function nth(maxArgs: number, index: (call: CallArguments) => string): Method {
+ return (call, target) => {
+ checkArguments(call, maxArgs, []);
+ if (isAnyFrame(target))
+ throw new Error(`Selecting the nth frame is not allowed on frameLocator()`);
+ return { type: target.type, parts: [...target.parts, selectorPart('nth', index(call))] };
+ };
}
-function visibleParts(call: CallArguments): ParsedSelectorPart[] {
+function visible(call: CallArguments, target: Target): Target {
checkArguments(call, 0, []);
- return [selectorPart('visible', 'true')];
+ return { type: 'Locator', parts: [...target.parts, selectorPart('visible', 'true')] };
}
-function getByTestIdParts(call: CallArguments, testIdAttributeName: string): ParsedSelectorPart[] {
+function describe(call: CallArguments, target: Target): Target {
checkArguments(call, 1, []);
- return parseSelector(getByTestIdSelector(testIdAttributeName, arg(call, 0, isText))).parts;
+ return { type: 'Locator', parts: [...target.parts, selectorPart('internal:describe', JSON.stringify(arg(call, 0, isString)))] };
}
-function getByRefParts(call: CallArguments): ParsedSelectorPart[] {
- checkArguments(call, 1, []);
- return [selectorPart('aria-ref', arg(call, 0, isString))];
+function getBy(selector: (call: CallArguments, testIdAttributeName: string) => string): Method {
+ return (call, target, testIdAttributeName) => ({ type: 'Locator', parts: childParts(target, parseSelector(selector(call, testIdAttributeName)).parts) });
}
-function textParts(toSelector: (text: string | RegExp, options: { exact?: boolean }) => string): CallHandler {
- return call => {
+function textSelector(toSelector: (text: string | RegExp, options: { exact?: boolean }) => string) {
+ return (call: CallArguments) => {
checkArguments(call, 1, ['exact']);
- return parseSelector(toSelector(arg(call, 0, isText), { exact: option(call, 'exact', isBoolean) })).parts;
+ return toSelector(arg(call, 0, isText), { exact: option(call, 'exact', isBoolean) });
};
}
-const andParts = nestedParts('internal:and');
-const orParts = nestedParts('internal:or');
-const firstParts = fixedNthParts('0');
-const lastParts = fixedNthParts('-1');
-const getByTextParts = textParts(getByTextSelector);
-const getByLabelParts = textParts(getByLabelSelector);
-const getByAltTextParts = textParts(getByAltTextSelector);
-const getByPlaceholderParts = textParts(getByPlaceholderSelector);
-const getByTitleParts = textParts(getByTitleSelector);
+function roleSelector(call: CallArguments): string {
+ checkArguments(call, 1, kRoleOptions);
+ return getByRoleSelector(arg(call, 0, isString), {
+ checked: option(call, 'checked', isBooleanOrMixed),
+ disabled: option(call, 'disabled', isBoolean),
+ selected: option(call, 'selected', isBoolean),
+ expanded: option(call, 'expanded', isBoolean),
+ includeHidden: option(call, 'includeHidden', isBoolean),
+ level: option(call, 'level', isNumber),
+ name: option(call, 'name', isText),
+ description: option(call, 'description', isText),
+ pressed: option(call, 'pressed', isBooleanOrMixed),
+ exact: option(call, 'exact', isBoolean),
+ });
+}
+
+function testIdSelector(call: CallArguments, testIdAttributeName: string): string {
+ checkArguments(call, 1, []);
+ return getByTestIdSelector(testIdAttributeName, arg(call, 0, isText));
+}
-const kFrameElementHandlers = new Set<CallHandler>([firstParts, lastParts, nthParts]);
+function getByRef(call: CallArguments): Target {
+ checkArguments(call, 1, []);
+ return { type: 'Locator', parts: [selectorPart('aria-ref', arg(call, 0, isString))] };
+}
+
+const kMethods: Record<string, Method> = {
+ locator: method(['Page', 'Locator', 'FrameLocator'], locator),
+ filter: method(['Locator'], filter),
+ within: method(['Locator'], within),
+ and: method(['Locator'], nested('internal:and')),
+ or: method(['Locator'], nested('internal:or')),
+ frameLocator: method(['Page', 'Locator', 'FrameLocator'], frameLocator),
+ contentFrame: method(['Locator'], contentFrame),
+ owner: method(['FrameLocator'], owner),
+ first: method(['Locator', 'FrameLocator'], nth(0, () => '0')),
+ last: method(['Locator', 'FrameLocator'], nth(0, () => '-1')),
+ nth: method(['Locator', 'FrameLocator'], nth(1, call => String(arg(call, 0, isNumber)))),
+ visible: method(['Locator'], visible),
+ describe: method(['Locator'], describe),
+ getByRole: method(['Page', 'Locator', 'FrameLocator'], getBy(roleSelector)),
+ getByText: method(['Page', 'Locator', 'FrameLocator'], getBy(textSelector(getByTextSelector))),
+ getByLabel: method(['Page', 'Locator', 'FrameLocator'], getBy(textSelector(getByLabelSelector))),
+ getByTestId: method(['Page', 'Locator', 'FrameLocator'], getBy(testIdSelector)),
+ getByRef: method(['Page'], getByRef),
+ getByAltText: method(['Page', 'Locator', 'FrameLocator'], getBy(textSelector(getByAltTextSelector))),
+ getByPlaceholder: method(['Page', 'Locator', 'FrameLocator'], getBy(textSelector(getByPlaceholderSelector))),
+ getByTitle: method(['Page', 'Locator', 'FrameLocator'], getBy(textSelector(getByTitleSelector))),
+};
// JavaScript and Java share the method names.
-const kJavaScriptMethods = new Map<string, CallHandler>([
- ['locator', locatorParts],
- ['filter', filterParts],
- ['within', withinParts],
- ['and', andParts],
- ['or', orParts],
- ['frameLocator', frameLocatorParts],
- ['contentFrame', contentFrameParts],
- ['first', firstParts],
- ['last', lastParts],
- ['nth', nthParts],
- ['visible', visibleParts],
- ['getByRole', getByRoleParts],
- ['getByText', getByTextParts],
- ['getByLabel', getByLabelParts],
- ['getByTestId', getByTestIdParts],
- ['getByRef', getByRefParts],
- ['getByAltText', getByAltTextParts],
- ['getByPlaceholder', getByPlaceholderParts],
- ['getByTitle', getByTitleParts],
-]);
-
-const kPythonMethods = new Map<string, CallHandler>([
- ['locator', locatorParts],
- ['filter', filterParts],
- ['within', withinParts],
- ['and_', andParts],
- ['or_', orParts],
- ['frame_locator', frameLocatorParts],
- ['content_frame', contentFrameParts],
- ['first', firstParts],
- ['last', lastParts],
- ['nth', nthParts],
- ['visible', visibleParts],
- ['get_by_role', getByRoleParts],
- ['get_by_text', getByTextParts],
- ['get_by_label', getByLabelParts],
- ['get_by_test_id', getByTestIdParts],
- ['get_by_ref', getByRefParts],
- ['get_by_alt_text', getByAltTextParts],
- ['get_by_placeholder', getByPlaceholderParts],
- ['get_by_title', getByTitleParts],
-]);
-
-const kCSharpMethods = new Map<string, CallHandler>([
- ['Locator', locatorParts],
- ['Filter', filterParts],
- ['Within', withinParts],
- ['And', andParts],
- ['Or', orParts],
- ['FrameLocator', frameLocatorParts],
- ['ContentFrame', contentFrameParts],
- ['First', firstParts],
- ['Last', lastParts],
- ['Nth', nthParts],
- ['Visible', visibleParts],
- ['GetByRole', getByRoleParts],
- ['GetByText', getByTextParts],
- ['GetByLabel', getByLabelParts],
- ['GetByTestId', getByTestIdParts],
- ['GetByRef', getByRefParts],
- ['GetByAltText', getByAltTextParts],
- ['GetByPlaceholder', getByPlaceholderParts],
- ['GetByTitle', getByTitleParts],
-]);
+const kJavaScriptMethods = new Map(Object.entries(kMethods));
+const kPythonMethods = new Map(Object.entries(kMethods).map(([name, method]) => [name === 'and' || name === 'or' ? name + '_' : toSnakeCase(name), method]));
+const kCSharpMethods = new Map(Object.entries(kMethods).map(([name, method]) => [toTitleCase(name), method]));
+
+// Selector parts of a locator created by the target, e.g. `frameLocator.locator()`.
+function childParts(target: Target, parts: ParsedSelectorPart[]): ParsedSelectorPart[] {
+ if (target.type !== 'FrameLocator' || isAnyFrame(target))
+ return [...target.parts, ...parts];
+ return [...target.parts, selectorPart('internal:control', 'enter-frame'), ...parts];
+}
+
+function isAnyFrame(target: Target): boolean {
+ return target.type === 'FrameLocator' && stringifySelector({ parts: target.parts }) === kAnyFrameSelector;
+}
function filterSelectorParts(call: CallArguments): ParsedSelectorPart[] {
const parts: ParsedSelectorPart[] = [];
@@ -597,23 +704,6 @@ function filterSelectorParts(call: CallArguments): ParsedSelectorPart[] {
return parts;
}
-function getByRoleParts(call: CallArguments): ParsedSelectorPart[] {
- checkArguments(call, 1, ['name', 'description', 'exact', 'checked', 'disabled', 'expanded', 'includeHidden', 'level', 'pressed', 'selected']);
- const exact = !!option(call, 'exact', isBoolean);
- let body = arg(call, 0, isString);
- for (const name of call.options.keys()) {
- if (name === 'name' || name === 'description')
- body += `[${name}=${escapeForAttributeSelector(option(call, name, isText)!, exact)}]`;
- else if (name === 'level')
- body += `[level=${option(call, name, isNumber)}]`;
- else if (name === 'checked' || name === 'pressed')
- body += `[${name}=${option(call, name, isBooleanOrMixed)}]`;
- else if (name !== 'exact')
- body += `[${name === 'includeHidden' ? 'include-hidden' : name}=${option(call, name, isBoolean)}]`;
- }
- return [selectorPart('internal:role', body)];
-}
-
function selectorPart(name: string, body: string): ParsedSelectorPart {
return { name, body, source: body };
}
@@ -622,10 +712,6 @@ function nestedSelectorPart(name: string, parsed: ParsedSelector): ParsedSelecto
return { name, body: { parsed }, source: JSON.stringify(stringifySelector(parsed)) };
}
-function isNestedSelectorPart(part: ParsedSelectorPart): boolean {
- return typeof part.body === 'object' && 'parsed' in part.body;
-}
-
function checkArguments(call: CallArguments, maxArgs: number, allowedOptions: string[]) {
if (call.args.length > maxArgs)
throw new Error(`Too many arguments for ${call.method}`);
@@ -673,6 +759,10 @@ function isSelector(value: Value): value is ParsedSelector {
return typeof value === 'object' && !(value instanceof RegExp);
}
+function isStringOrSelector(value: Value): value is string | ParsedSelector {
+ return isString(value) || isSelector(value);
+}
+
function lowerFirst(identifier: string): string {
return identifier.charAt(0).toLowerCase() + identifier.substring(1);
}
diff --git a/packages/isomorphic/locatorUtils.ts b/packages/isomorphic/locatorUtils.ts
index 77cb2d715a..c62015d9a9 100644
--- a/packages/isomorphic/locatorUtils.ts
+++ b/packages/isomorphic/locatorUtils.ts
@@ -17,7 +17,7 @@
import { escapeForAttributeSelector, escapeForTextSelector } from './stringUtils';
export type ByRoleOptions = {
- checked?: boolean;
+ checked?: boolean | 'mixed';
description?: string | RegExp;
disabled?: boolean;
exact?: boolean;
@@ -25,7 +25,7 @@ export type ByRoleOptions = {
includeHidden?: boolean;
level?: number;
name?: string | RegExp;
- pressed?: boolean;
+ pressed?: boolean | 'mixed';
selected?: boolean;
};
diff --git a/tests/library/locator-generator.spec.ts b/tests/library/locator-generator.spec.ts
index 31b9fa89d0..907e9b6623 100644
--- a/tests/library/locator-generator.spec.ts
+++ b/tests/library/locator-generator.spec.ts
@@ -18,7 +18,7 @@ import { contextTest as it, expect } from '../config/browserTest';
import { iso } from '../../packages/playwright-core/lib/coreBundle';
import type { Page, Frame, Locator, FrameLocator } from 'playwright-core';
-const { asLocator, asLocators, asLocatorDescription, locatorOrSelectorAsSelector: parseLocator } = iso;
+const { asLocator, asLocators, asLocatorDescription } = iso;
it.skip(({ mode }) => mode !== 'default');
@@ -28,22 +28,16 @@ function generate(locator: Locator | FrameLocator) {
function generateForSelector(selector: string) {
const result: any = {};
- for (const lang of ['javascript', 'python', 'java', 'csharp']) {
- const locatorString = asLocator(lang, selector);
- expect.soft(parseLocator(lang, locatorString, 'data-testid'), lang + ' mismatch').toBe(selector);
- result[lang] = locatorString;
- }
+ for (const lang of ['javascript', 'python', 'java', 'csharp'])
+ result[lang] = asLocator(lang, selector);
return result;
}
async function generateForNode(pageOrFrame: Page | Frame, target: string): Promise<string> {
const selector = await pageOrFrame.locator(target).evaluate(e => (window as any).playwright.selector(e));
const result: any = {};
- for (const lang of ['javascript', 'python', 'java', 'csharp']) {
- const locatorString = asLocator(lang, selector);
- expect.soft(parseLocator(lang, locatorString)).toBe(selector);
- result[lang] = locatorString;
- }
+ for (const lang of ['javascript', 'python', 'java', 'csharp'])
+ result[lang] = asLocator(lang, selector);
return result;
}
@@ -117,9 +111,7 @@ it('reverse engineer locators', async ({ page }) => {
for (const flags of ['u', 's', 'y', 'd', 'v', 'gm']) {
for (const [engine, method] of [['text', 'getByText'], ['label', 'getByLabel']]) {
const selector = `internal:${engine}=/Hello/${flags}`;
- const locatorString = asLocator('javascript', selector);
- expect.soft(locatorString, selector).toBe(`${method}(/Hello/${flags})`);
- expect.soft(parseLocator('javascript', locatorString, 'data-testid'), selector).toBe(selector);
+ expect.soft(asLocator('javascript', selector), selector).toBe(`${method}(/Hello/${flags})`);
}
}
@@ -393,11 +385,6 @@ it('reverse engineer visible', async ({ page }) => {
javascript: `getByText('Hello').filter({ visible: false }).locator('div')`,
python: `get_by_text("Hello").filter(visible=False).locator("div")`,
});
- const selector = (page.getByText('Hello').visible() as any)._selector;
- expect.soft(parseLocator('javascript', `getByText('Hello').filter({ visible: true })`, 'data-testid')).toBe(selector);
- expect.soft(parseLocator('java', `getByText("Hello").filter(new Locator.FilterOptions().setVisible(true))`, 'data-testid')).toBe(selector);
- expect.soft(parseLocator('python', `get_by_text("Hello").filter(visible=True)`, 'data-testid')).toBe(selector);
- expect.soft(parseLocator('csharp', `GetByText("Hello").Filter(new() { Visible = true })`, 'data-testid')).toBe(selector);
});
it('reverse engineer has', async ({ page }) => {
@@ -469,6 +456,8 @@ it('reverse engineer frameLocator', async ({ page }) => {
// Note that frame locators with ">>" are not restored back due to ambiguity.
const selector = (page.frameLocator('div >> iframe').locator('span') as any)._selector;
expect.soft(asLocator('javascript', selector)).toBe(`locator('div').locator('iframe').contentFrame().locator('span')`);
+
+ expect.soft(asLocators('javascript', 'internal:attr=[title="iframe title"i] >> internal:control=enter-frame')).toEqual([`getByTitle('iframe title').contentFrame()`]);
});
it('reverse engineer frameLocator without a selector', async ({ page }) => {
@@ -561,11 +550,8 @@ it('generate multiple locators', async ({ page }) => {
`Locator("div", new() { HasText = "foo" }).Nth(0).Filter(new() { Has = Locator("span", new() { HasNotText = "bar" }).Nth(-1) })`,
],
};
- for (const lang of ['javascript', 'java', 'python', 'csharp'] as const) {
+ for (const lang of ['javascript', 'java', 'python', 'csharp'] as const)
expect.soft(asLocators(lang, selector)).toEqual(locators[lang]);
- for (const locator of locators[lang])
- expect.soft(parseLocator(lang, locator, 'data-testid'), `parse(${lang}): ${locator}`).toBe(selector);
- }
});
it.describe(() => {
@@ -611,17 +597,7 @@ it('asLocator internal:chain', async () => {
expect.soft(asLocator('csharp', 'div >> internal:chain="span >> article"')).toBe(`Locator("div").Locator(Locator("span").Locator("article"))`);
});
-it('parseLocator and, or, chain', async () => {
- for (const kind of ['and', 'or', 'chain']) {
- const selector = `div >> internal:${kind}="span >> article"`;
- for (const lang of ['javascript', 'python', 'java', 'csharp'] as const)
- expect.soft(parseLocator(lang, asLocator(lang, selector), 'data-testid'), lang).toBe(selector);
- }
-});
-
-it('parseLocator nested and, or, locator', {
- annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/42891' }
-}, async ({ page }) => {
+it('reverse engineer nested locators', async ({ page }) => {
expect.soft(generate(page.getByRole('row').locator(page.getByRole('cell').nth(2)))).toEqual({
csharp: `GetByRole(AriaRole.Row).Locator(GetByRole(AriaRole.Cell).Nth(2))`,
java: `getByRole(AriaRole.ROW).locator(getByRole(AriaRole.CELL).nth(2))`,
@@ -636,149 +612,12 @@ it('parseLocator nested and, or, locator', {
});
});
-it('parseLocator within', {
- annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/43159' }
-}, async () => {
- const selector = `internal:role=row >> internal:chain="internal:role=cell >> nth=2"`;
- expect.soft(parseLocator('javascript', `getByRole('cell').nth(2).within(getByRole('row'))`)).toBe(selector);
- expect.soft(parseLocator('python', `get_by_role("cell").nth(2).within(get_by_role("row"))`)).toBe(selector);
- expect.soft(parseLocator('java', `getByRole(AriaRole.CELL).nth(2).within(getByRole(AriaRole.ROW))`)).toBe(selector);
- expect.soft(parseLocator('csharp', `GetByRole(AriaRole.Cell).Nth(2).Within(GetByRole(AriaRole.Row))`)).toBe(selector);
-});
-
-it('parseLocator getByRef', {
- annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/43159' }
-}, async () => {
- expect.soft(parseLocator('javascript', `getByRef('e5')`)).toBe('aria-ref=e5');
- expect.soft(parseLocator('python', `get_by_ref("e5")`)).toBe('aria-ref=e5');
- expect.soft(parseLocator('java', `getByRef("e5")`)).toBe('aria-ref=e5');
- expect.soft(parseLocator('csharp', `GetByRef("e5")`)).toBe('aria-ref=e5');
-});
-
it('asLocator xpath', async () => {
const selector = `//*[contains(normalizer-text(), 'foo']`;
expect.soft(asLocator('javascript', selector)).toBe(`locator('//*[contains(normalizer-text(), \\'foo\\']')`);
expect.soft(asLocator('python', selector)).toBe(`locator(\"//*[contains(normalizer-text(), 'foo']\")`);
expect.soft(asLocator('java', selector)).toBe(`locator(\"//*[contains(normalizer-text(), 'foo']\")`);
expect.soft(asLocator('csharp', selector)).toBe(`Locator(\"//*[contains(normalizer-text(), 'foo']\")`);
- expect.soft(parseLocator('javascript', `locator('//*[contains(normalizer-text(), \\'foo\\']')`, 'data-testid')).toBe("//*[contains(normalizer-text(), 'foo']");
- expect.soft(parseLocator('javascript', `locator("//*[contains(normalizer-text(), 'foo']")`, 'data-testid')).toBe("//*[contains(normalizer-text(), 'foo']");
- expect.soft(parseLocator('javascript', `locator('xpath=//*[contains(normalizer-text(), \\'foo\\']')`, 'data-testid')).toBe("//*[contains(normalizer-text(), 'foo']");
- expect.soft(parseLocator('javascript', `locator("xpath=//*[contains(normalizer-text(), 'foo']")`, 'data-testid')).toBe("//*[contains(normalizer-text(), 'foo']");
- expect.soft(parseLocator('python', `locator("//*[contains(normalizer-text(), 'foo']")`, 'data-testid')).toBe("//*[contains(normalizer-text(), 'foo']");
- expect.soft(parseLocator('python', `locator("xpath=//*[contains(normalizer-text(), 'foo']")`, 'data-testid')).toBe("//*[contains(normalizer-text(), 'foo']");
- expect.soft(parseLocator('java', `locator("//*[contains(normalizer-text(), 'foo']")`, 'data-testid')).toBe("//*[contains(normalizer-text(), 'foo']");
- expect.soft(parseLocator('java', `locator("xpath=//*[contains(normalizer-text(), 'foo']")`, 'data-testid')).toBe("//*[contains(normalizer-text(), 'foo']");
- expect.soft(parseLocator('csharp', `Locator("//*[contains(normalizer-text(), 'foo']")`, 'data-testid')).toBe("//*[contains(normalizer-text(), 'foo']");
- expect.soft(parseLocator('csharp', `Locator("xpath=//*[contains(normalizer-text(), 'foo']")`, 'data-testid')).toBe("//*[contains(normalizer-text(), 'foo']");
-});
-
-it('parseLocator quotes', async () => {
- expect.soft(parseLocator('javascript', `locator('text="bar"')`, '')).toBe(`text="bar"`);
- expect.soft(parseLocator('javascript', `locator("text='bar'")`, '')).toBe(`text='bar'`);
- expect.soft(parseLocator('javascript', "locator(`text='bar'`)", '')).toBe(`text='bar'`);
- expect.soft(parseLocator('python', `locator("text='bar'")`, '')).toBe(`text='bar'`);
- expect.soft(parseLocator('python', `locator('text="bar"')`, '')).toBe(`text="bar"`);
- expect.soft(parseLocator('java', `locator("text='bar'")`, '')).toBe(`text='bar'`);
- expect.soft(parseLocator('java', `locator('text="bar"')`, '')).toBe(``);
- expect.soft(parseLocator('csharp', `Locator("text='bar'")`, '')).toBe(`text='bar'`);
- expect.soft(parseLocator('csharp', `Locator('text="bar"')`, '')).toBe(``);
-
- const mixedQuotes = `
- locator("[id*=freetext-field]")
- .locator('input:below(:text("Assigned Number:"))')
- .locator("visible=true")
- `;
- expect.soft(parseLocator('javascript', mixedQuotes, '')).toBe(`[id*=freetext-field] >> input:below(:text("Assigned Number:")) >> visible=true`);
-});
-
-it('parseLocator css', async () => {
- expect.soft(parseLocator('javascript', `locator('.foo')`, '')).toBe(`.foo`);
- expect.soft(parseLocator('javascript', `locator('css=.foo')`, '')).toBe(`.foo`);
- expect.soft(parseLocator('python', `locator(".foo")`, '')).toBe(`.foo`);
- expect.soft(parseLocator('python', `locator("css=.foo")`, '')).toBe(`.foo`);
- expect.soft(parseLocator('java', `locator(".foo")`, '')).toBe(`.foo`);
- expect.soft(parseLocator('java', `locator("css=.foo")`, '')).toBe(`.foo`);
- expect.soft(parseLocator('csharp', `Locator(".foo")`, '')).toBe(`.foo`);
- expect.soft(parseLocator('csharp', `Locator("css=.foo")`, '')).toBe(`.foo`);
-});
-
-
-it('parseLocator options', async () => {
- expect.soft(parseLocator('javascript', `getByRole('heading', {})`, '')).toBe(`internal:role=heading`);
- expect.soft(parseLocator('javascript', `getByRole('checkbox', { checked:false, includeHidden: true })`, '')).toBe(`internal:role=checkbox[checked=false][include-hidden=true]`);
-});
-
-it('parseLocator role options', async () => {
- expect.soft(parseLocator('python', `get_by_role("checkbox", checked=True, include_hidden=True)`, '')).toBe(`internal:role=checkbox[checked=true][include-hidden=true]`);
- expect.soft(parseLocator('javascript', `getByRole('button', { nme: 'foo' })`, '')).toBe(``);
-});
-
-it('parseLocator round-trips mixed role options', {
- annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/43158' }
-}, async () => {
- for (const selector of ['internal:role=checkbox[checked=mixed]', 'internal:role=button[pressed=mixed]']) {
- for (const lang of ['javascript', 'python', 'java', 'csharp'] as const)
- expect.soft(parseLocator(lang, asLocator(lang, selector), 'data-testid'), `${lang}: ${selector}`).toBe(selector);
- }
-});
-
-it('parseLocator round-trips selectors', async () => {
- const selectors = [
- 'div',
- '.foo',
- '//div',
- 'internal:text="hello"i',
- 'internal:text="hello"s',
- 'internal:text=/he\\"llo/i',
- 'internal:text=/a\\/b/',
- 'internal:text=/a.b/ims',
- 'internal:role=button[name=/a.b/ms]',
- 'internal:text="a\'b\\"c`d"i',
- 'internal:text="a\\\\b"i',
- 'internal:text="tab\\there\\nnewline"i',
- 'internal:text="\\u0001"i',
- 'internal:label="x"s',
- 'internal:label=/x/',
- 'internal:attr=[placeholder="p"i]',
- 'internal:attr=[alt="a"s]',
- 'internal:attr=[title=/t/i]',
- 'internal:testid=[data-testid="id"s]',
- 'internal:testid=[data-testid=/id/]',
- 'internal:role=button',
- 'internal:role=button[name="ok"s]',
- 'internal:role=button[name=/ok/i]',
- 'internal:role=checkbox[checked=true][include-hidden=true]',
- 'internal:role=heading[name="h"s][level=2]',
- 'internal:role=alert[name="Upload"s][description="doc.pdf"s]',
- 'internal:role=alert[name=/U/][description="d"i]',
- 'internal:role=button[pressed=false][disabled=true][expanded=true][selected=true]',
- 'div >> nth=0',
- 'div >> nth=-1',
- 'div >> nth=3',
- 'div >> visible=true',
- 'div >> visible=false',
- 'div >> internal:has-text="foo"i >> span',
- 'div >> internal:has-not-text=/foo/',
- 'div >> internal:has="span >> internal:has=\\"b\\""',
- 'div >> internal:has-not="internal:role=button[name=\\"x\\"i]"',
- 'iframe >> internal:control=enter-frame >> div',
- 'iframe >> nth=0 >> internal:control=enter-frame >> div',
- 'internal:attr=[title="t"i] >> internal:control=enter-frame',
- 'internal:control=any-frame >> div',
- 'div >> internal:and="span >> nth=0"',
- 'div >> internal:or="span"',
- 'div >> internal:chain="span >> internal:has-text=\\"x\\"i"',
- ];
- for (const selector of selectors) {
- for (const lang of ['javascript', 'python', 'java', 'csharp'] as const) {
- const [canonical, ...alternatives] = asLocators(lang, selector);
- expect.soft(parseLocator(lang, canonical, 'data-testid'), `${lang}: ${canonical}`).toBe(selector);
- // Alternatives may parse into an equivalent selector, e.g. `css=div` instead of `div`.
- for (const locator of alternatives)
- expect.soft(asLocator(lang, parseLocator(lang, locator, 'data-testid')), `${lang}: ${locator}`).toBe(canonical);
- }
- }
});
it('reverse engineer regex flags', async () => {
@@ -796,92 +635,6 @@ it('reverse engineer regex flags', async () => {
});
});
-it('parse javascript string escapes and regex literals', () => {
- expect.soft(parseLocator('javascript', String.raw`getByText("\x41")`)).toBe('internal:text="A"i');
- expect.soft(parseLocator('javascript', String.raw`getByText("\u{1F600}")`)).toBe('internal:text="\u{1F600}"i');
- expect.soft(parseLocator('javascript', 'getByText(/[/]/)')).toBe('internal:text=/[/]/');
-});
-
-it('parseLocator rejects malformed locators', async () => {
- const locators = [
- ['javascript', `locator('div').nth(0))`],
- ['javascript', `locator('div').nth(-)`],
- ['javascript', `locator('div')..locator('span')`],
- ['javascript', `getByRole('button', { nme: 'ok' })`],
- ['javascript', `getByRole('button', { name: 'ok', exct: true })`],
- ['javascript', `getByText('foo', { exact: 'true' })`],
- ['javascript', `locator('div').filter({ hasText: 'foo' }})`],
- ['javascript', String.raw`getByText("\x4")`],
- ['javascript', String.raw`getByText("\u{}")`],
- ['javascript', String.raw`getByText("\u{110000}")`],
- ['python', `get_by_role("checkbox", cheked=True)`],
- ['python', `locator("div").filter(has_text=="foo")`],
- ['python', `locator("div").nth(0))`],
- ['java', `locator("div").filter(newLocator.FilterOptions().setHasText("foo"))`],
- ['java', `getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setNme("ok"))`],
- ['java', `locator('div')`],
- ['csharp', `GetByTestId(newRegex("id"))`],
- ['csharp', `GetByRole(AriaRole.Button, new() { Nme = "ok" })`],
- ['csharp', `Locator('div')`],
- ['csharp', `Locator("div").Nth(0))`],
- ] as const;
- for (const [lang, locator] of locators)
- expect.soft(parseLocator(lang, locator, 'data-testid'), `${lang}: ${locator}`).toBe('');
-});
-
-it('parse locators strictly', () => {
- const selector = 'div >> internal:has-text=\"Goodbye world\"i >> span';
-
- // Exact
- expect.soft(parseLocator('csharp', `Locator("div").Filter(new() { HasText = "Goodbye world" }).Locator("span")`)).toBe(selector);
- expect.soft(parseLocator('java', `locator("div").filter(new Locator.FilterOptions().setHasText("Goodbye world")).locator("span")`)).toBe(selector);
- expect.soft(parseLocator('javascript', `locator('div').filter({ hasText: 'Goodbye world' }).locator('span')`)).toBe(selector);
- expect.soft(parseLocator('python', `locator("div").filter(has_text="Goodbye world").locator("span")`)).toBe(selector);
-
- // Quotes
- expect.soft(parseLocator('javascript', `locator("div").filter({ hasText: "Goodbye world" }).locator("span")`)).toBe(selector);
- expect.soft(parseLocator('python', `locator('div').filter(has_text='Goodbye world').locator('span')`)).toBe(selector);
-
- // Whitespace
- expect.soft(parseLocator('csharp', `Locator("div") . Filter (new ( ) { HasText = "Goodbye world" }).Locator( "span" )`)).toBe(selector);
- expect.soft(parseLocator('java', ` locator("div" ). filter( new Locator. FilterOptions ( ) .setHasText( "Goodbye world" ) ).locator( "span")`)).toBe(selector);
- expect.soft(parseLocator('javascript', `locator\n('div')\n\n.filter({ hasText : 'Goodbye world'\n }\n).locator('span')\n`)).toBe(selector);
- expect.soft(parseLocator('python', `\tlocator(\t"div").filter(\thas_text="Goodbye world"\t).locator\t("span")`)).toBe(selector);
-
- // Extra symbols
- expect.soft(parseLocator('csharp', `Locator("div").Filter(new() { HasText = "Goodbye world" }).Locator("span"))`)).not.toBe(selector);
- expect.soft(parseLocator('java', `locator("div").filter(new Locator.FilterOptions().setHasText("Goodbye world"))..locator("span")`)).not.toBe(selector);
- expect.soft(parseLocator('javascript', `locator('div').filter({ hasText: 'Goodbye world' }}).locator('span')`)).not.toBe(selector);
- expect.soft(parseLocator('python', `locator("div").filter(has_text=="Goodbye world").locator("span")`)).not.toBe(selector);
- expect.soft(parseLocator('javascript', `locator('div').nth(0))`)).toBe('');
-});
-
-it('parseLocator frames', async () => {
- expect.soft(parseLocator('javascript', `locator('iframe').contentFrame().getByText('foo')`, '')).toBe(`iframe >> internal:control=enter-frame >> internal:text=\"foo\"i`);
- expect.soft(parseLocator('javascript', `frameLocator('iframe').getByText('foo')`, '')).toBe(`iframe >> internal:control=enter-frame >> internal:text=\"foo\"i`);
- expect.soft(parseLocator('javascript', `frameLocator('css=iframe').getByText('foo')`, '')).toBe(`iframe >> internal:control=enter-frame >> internal:text=\"foo\"i`);
- expect.soft(parseLocator('javascript', `getByTitle('iframe title').contentFrame()`)).toBe(`internal:attr=[title=\"iframe title\"i] >> internal:control=enter-frame`);
-
- // FrameLocator.first() and nth() pick the frame element, so there is no locator for nth inside a frame.
- const nthInsideFrame = 'iframe >> internal:control=enter-frame >> nth=1';
- for (const lang of ['javascript', 'python', 'java', 'csharp'] as const) {
- for (const locator of asLocators(lang, nthInsideFrame))
- expect.soft(parseLocator(lang, locator), `${lang}: ${locator}`).not.toBe(nthInsideFrame);
- }
-
- expect.soft(asLocators('javascript', 'internal:attr=[title=\"iframe title\"i] >> internal:control=enter-frame')).toEqual([`getByTitle('iframe title').contentFrame()`]);
-
- expect.soft(parseLocator('python', `locator("iframe").content_frame.get_by_text("foo")`, '')).toBe(`iframe >> internal:control=enter-frame >> internal:text=\"foo\"i`);
- expect.soft(parseLocator('python', `frame_locator("iframe").get_by_text("foo")`, '')).toBe(`iframe >> internal:control=enter-frame >> internal:text=\"foo\"i`);
- expect.soft(parseLocator('python', `frame_locator("css=iframe").get_by_text("foo")`, '')).toBe(`iframe >> internal:control=enter-frame >> internal:text=\"foo\"i`);
-
- expect.soft(parseLocator('csharp', `Locator("iframe").ContentFrame.GetByText("foo")`, '')).toBe(`iframe >> internal:control=enter-frame >> internal:text=\"foo\"i`);
- expect.soft(parseLocator('csharp', `FrameLocator("iframe").GetByText("foo")`, '')).toBe(`iframe >> internal:control=enter-frame >> internal:text=\"foo\"i`);
-
- expect.soft(parseLocator('java', `locator("iframe").contentFrame().getByText("foo")`, '')).toBe(`iframe >> internal:control=enter-frame >> internal:text=\"foo\"i`);
- expect.soft(parseLocator('java', `frameLocator("iframe").getByText("foo")`, '')).toBe(`iframe >> internal:control=enter-frame >> internal:text=\"foo\"i`);
-});
-
it('should not oom in locator parser', async ({ page }) => {
const l = page.locator.bind(page);
const locator = page.locator('text=L1').or(l('text=L2').or(l('text=L3').or(l('text=L4')).or(l('#f0')
diff --git a/tests/library/locator-parser.spec.ts b/tests/library/locator-parser.spec.ts
new file mode 100644
index 0000000000..65ad0b0ccb
--- /dev/null
+++ b/tests/library/locator-parser.spec.ts
@@ -0,0 +1,1223 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { test as it, expect as baseExpect } from '@playwright/test';
+import { iso } from '../../packages/playwright-core/lib/coreBundle';
+import { getByAltTextSelector, getByLabelSelector, getByPlaceholderSelector, getByRoleSelector, getByTestIdSelector, getByTextSelector, getByTitleSelector } from '../../packages/isomorphic/locatorUtils';
+import type { FrameLocator, Locator, Page } from 'playwright-core';
+
+const { asLocators, kAnyFrameSelector, parseSelector, stringifySelector, unsafeLocatorOrSelectorAsSelector } = iso;
+
+// Client sources only type-check with the packages tsconfig, so they are loaded at runtime.
+const client: {
+ Locator: new (frame: null, selector: string, options?: object) => Locator & { _selector: string };
+ FrameLocator: new (frame: null, selector: string) => FrameLocator & { _frameSelector: string };
+ setTestIdAttribute: (testIdAttributeName: string) => void;
+ testIdAttributeName: () => string;
+} = require('../../packages/playwright-core/src/client/locator');
+
+type Language = 'javascript' | 'python' | 'java' | 'csharp';
+type AriaRole = Parameters<Page['getByRole']>[0];
+type Built = Locator | FrameLocator;
+type Receiver = 'Page' | 'Locator' | 'FrameLocator';
+type Call = { method: string, args: any[] };
+
+// One of the ways a user may format a locator in a given language.
+type Style = {
+ name: string;
+ quote: string;
+ multiline?: boolean;
+ compact?: boolean;
+ trailingCommas?: boolean;
+ rawRegex?: boolean;
+ regexFlagAliases?: boolean;
+ verbatimRegex?: boolean;
+ optionsType?: 'typed' | 'typed()';
+};
+
+type Styles = Partial<Record<Language, Style[]>>;
+
+const kLanguages: Language[] = ['javascript', 'python', 'java', 'csharp'];
+
+// The most common way to write a locator in each language.
+const kDefaultStyles: Styles = {
+ javascript: [{ name: 'single quotes', quote: `'` }],
+ python: [{ name: 'double quotes', quote: '"', rawRegex: true }],
+ java: [{ name: 'default', quote: '"' }],
+ csharp: [{ name: 'default', quote: '"' }],
+};
+
+// Quotes and formatting that matter for string escaping and tokenizing.
+const kAllStyles: Styles = {
+ javascript: [
+ { name: 'single quotes', quote: `'` },
+ { name: 'double quotes', quote: '"' },
+ { name: 'template literals', quote: '`' },
+ { name: 'multiline', quote: `'`, multiline: true },
+ { name: 'compact', quote: `'`, compact: true },
+ ],
+ python: [
+ { name: 'double quotes', quote: '"', rawRegex: true },
+ { name: 'single quotes', quote: `'` },
+ { name: 'multiline', quote: '"', rawRegex: true, multiline: true },
+ ],
+ java: [
+ { name: 'default', quote: '"' },
+ { name: 'multiline', quote: '"', multiline: true },
+ { name: 'compact', quote: '"', compact: true },
+ ],
+ csharp: [
+ { name: 'default', quote: '"' },
+ { name: 'multiline', quote: '"', multiline: true },
+ { name: 'compact', quote: '"', compact: true },
+ ],
+};
+
+const kTexts = [
+ 'Hello',
+ 'Hello World',
+ '',
+ `It's`,
+ 'Say "hi"',
+ 'back`tick',
+ 'C:\\path\\file',
+ 'line1\nline2',
+ 'tab\there',
+ 'café ✓ 😀',
+ 'a >> b',
+ '$' + '{name}',
+ '(a), {b}: c=d | e.f',
+ ' padded ',
+ '/not a regex/i',
+];
+
+const kRegexes = [
+ /Hello/,
+ /hello/i,
+ /^Sub.*mit$/,
+ /a.b/ims,
+ /\d+ items?/,
+ /\bword\b/,
+ /a\/b/,
+ /[/]/,
+ /say "hi"/,
+ /it's/,
+ /a\\b/,
+ /\(x\), \{y\}/,
+ /x{2,3}|y/,
+ /café/,
+ /a>>b/,
+];
+
+const kSelectors = [
+ 'div',
+ '#main',
+ '.btn.primary',
+ 'div > span',
+ 'ul li:nth-child(2)',
+ '[data-test="submit"]',
+ `[aria-label='Close']`,
+ 'input[name=q]',
+ 'button:has-text("Save")',
+ 'div:has(> span)',
+ '#foo\\:bar',
+ '//div[@id="main"]',
+ `//*[contains(normalize-space(), 'foo')]`,
+ `xpath=//span[@class='x']`,
+ '[id*=freetext-field]',
+ 'input:below(:text("Assigned Number:"))',
+ '..',
+ 'text=Hello',
+ 'text="Hello World"',
+ `text='Hello'`,
+ 'id=main',
+ 'data-testid=submit',
+ 'role=button[name="Save"]',
+ 'css=div',
+ 'div >> span',
+ 'div >> nth=1',
+ 'div >> visible=true',
+];
+
+const kRoles: AriaRole[] = [
+ 'alert', 'alertdialog', 'application', 'article', 'banner', 'blockquote', 'button', 'caption', 'cell', 'checkbox',
+ 'code', 'columnheader', 'combobox', 'complementary', 'contentinfo', 'definition', 'deletion', 'dialog', 'directory',
+ 'document', 'emphasis', 'feed', 'figure', 'form', 'generic', 'grid', 'gridcell', 'group', 'heading', 'img', 'insertion',
+ 'link', 'list', 'listbox', 'listitem', 'log', 'main', 'marquee', 'math', 'meter', 'menu', 'menubar', 'menuitem',
+ 'menuitemcheckbox', 'menuitemradio', 'navigation', 'none', 'note', 'option', 'paragraph', 'presentation', 'progressbar',
+ 'radio', 'radiogroup', 'region', 'row', 'rowgroup', 'rowheader', 'scrollbar', 'search', 'searchbox', 'separator',
+ 'slider', 'spinbutton', 'status', 'strong', 'subscript', 'superscript', 'switch', 'tab', 'table', 'tablist', 'tabpanel',
+ 'term', 'textbox', 'time', 'timer', 'toolbar', 'tooltip', 'tree', 'treegrid', 'treeitem',
+];
+
+const kTextMethods = ['getByText', 'getByLabel', 'getByPlaceholder', 'getByAltText', 'getByTitle'] as const;
+
+const recordedCalls = new WeakMap<object, Call[]>();
+
+function record(calls: Call[]): any {
+ const recorder = new Proxy({}, {
+ get: (_, method) => typeof method === 'string' && method !== 'then' ? (...args: any[]) => record([...calls, { method, args }]) : undefined,
+ });
+ recordedCalls.set(recorder, calls);
+ return recorder;
+}
+
+// Records API calls instead of building selectors. Each recorded locator is replayed
+// on client locators for the expected selector, and rendered as code in every language.
+const $: Page = record([]);
+
+// Page methods that start a locator chain.
+const kPageSelectors: Record<string, (...args: any[]) => string> = {
+ getByAltText: getByAltTextSelector,
+ getByLabel: getByLabelSelector,
+ getByPlaceholder: getByPlaceholderSelector,
+ getByRef: ref => `aria-ref=${ref}`,
+ getByRole: getByRoleSelector,
+ getByTestId: testId => getByTestIdSelector(client.testIdAttributeName(), testId),
+ getByText: getByTextSelector,
+ getByTitle: getByTitleSelector,
+};
+
+const javascript = (code: string) => parse('javascript', code);
+const python = (code: string) => parse('python', code);
+const java = (code: string) => parse('java', code);
+const csharp = (code: string) => parse('csharp', code);
+
+const expect = baseExpect.extend({
+ // The locator parses in every language and style into the selector that the API builds.
+ toParse(built: Built, styles: Styles = kDefaultStyles, testIdAttributeName = 'data-testid') {
+ const expected = selectorOf(built);
+ const failures: string[] = [];
+ for (const lang of kLanguages) {
+ for (const style of styles[lang] ?? []) {
+ const code = render(lang, built, style);
+ const received = parse(lang, code, testIdAttributeName);
+ if (received !== expected)
+ failures.push(`${lang} (${style.name}): ${code.replace(/\s*\n\s*/g, ' ')}\nReceived: ${received}`);
+ }
+ }
+ return { name: 'toParse', pass: !failures.length, message: () => `Expected: ${expected}\n\n${failures.join('\n\n')}` };
+ },
+
+ // The locator cannot be parsed in any language.
+ toBeRejected(built: Built) {
+ const failures: string[] = [];
+ for (const lang of kLanguages) {
+ const code = render(lang, built, kDefaultStyles[lang][0]);
+ const received = parse(lang, code);
+ if (!received.startsWith('Error'))
+ failures.push(`${lang}: ${code}\nReceived: ${received}`);
+ }
+ return { name: 'toBeRejected', pass: !failures.length, message: () => `Expected: Error\n\n${failures.join('\n\n')}` };
+ },
+
+ // Every locator that the generator produces for the selector parses back into the selector.
+ toRoundTrip(value: Built | string, languages: Language[] = kLanguages) {
+ const selector = typeof value === 'string' ? value : selectorOf(value);
+ const expected = canonicalSelector(selector);
+ const failures: string[] = [];
+ for (const lang of languages) {
+ for (const code of asLocators(lang, selector)) {
+ const received = parse(lang, code);
+ if (received !== expected)
+ failures.push(`${lang}: ${code}\nReceived: ${received}`);
+ }
+ }
+ return { name: 'toRoundTrip', pass: !failures.length, message: () => `Expected: ${expected}\n\n${failures.join('\n\n')}` };
+ },
+});
+
+it.beforeEach(() => {
+ client.setTestIdAttribute('data-testid');
+});
+
+it('should parse getByText, getByLabel, getByPlaceholder, getByAltText and getByTitle', () => {
+ for (const method of kTextMethods) {
+ for (const text of kTexts) {
+ expect.soft($[method](text)).toParse(kAllStyles);
+ expect.soft($[method](text, { exact: true })).toParse(kAllStyles);
+ expect.soft($[method](text, { exact: false })).toParse(kAllStyles);
+ }
+ for (const regex of kRegexes)
+ expect.soft($[method](regex)).toParse(kAllStyles);
+ expect.soft($[method]('Hello', {})).toParse();
+ expect.soft($[method](/hello/i, { exact: true })).toParse();
+ expect.soft($.locator('div')[method]('Hello')).toParse();
+ expect.soft($.getByRole('dialog')[method]('Hello', { exact: true })).toParse();
+ expect.soft($.frameLocator('iframe')[method](/hello/i)).toParse();
+ }
+});
+
+it('should parse getByTestId', () => {
+ for (const text of kTexts)
+ expect.soft($.getByTestId(text)).toParse(kAllStyles);
+ for (const regex of kRegexes)
+ expect.soft($.getByTestId(regex)).toParse(kAllStyles);
+ expect.soft($.locator('form').getByTestId('submit')).toParse();
+ expect.soft($.frameLocator('iframe').getByTestId('submit')).toParse();
+});
+
+it('should parse getByTestId with a custom test id attribute', () => {
+ for (const testIdAttributeName of ['data-pw', 'data-test-id', 'data-pw,data-qa']) {
+ client.setTestIdAttribute(testIdAttributeName);
+ expect.soft($.getByTestId('submit')).toParse(kDefaultStyles, testIdAttributeName);
+ expect.soft($.getByTestId(/sub/i)).toParse(kDefaultStyles, testIdAttributeName);
+ expect.soft($.locator('form').getByTestId('Say "hi"')).toParse(kDefaultStyles, testIdAttributeName);
+ expect.soft($.frameLocator('iframe').getByTestId('submit')).toParse(kDefaultStyles, testIdAttributeName);
+ }
+});
+
+it('should parse getByRef', {
+ annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/43159' },
+}, () => {
+ expect.soft($.getByRef('e5')).toParse();
+ expect.soft($.getByRef('f1e3')).toParse();
+ expect.soft($.getByRef('e5').first()).toParse();
+ expect.soft($.getByRef('e5').locator('span')).toParse();
+ expect.soft($.getByRef('e5').contentFrame().getByRole('button')).toParse();
+ expect.soft($.locator('div').filter({ has: $.getByRef('e3') })).toParse();
+ expect.soft($.locator('div').and($.getByRef('e3'))).toParse();
+});
+
+it('should parse getByRole with every role', () => {
+ for (const role of kRoles) {
+ expect.soft($.getByRole(role)).toParse();
+ expect.soft($.getByRole(role, { name: 'Hello' })).toParse();
+ }
+});
+
+it('should parse getByRole options', () => {
+ expect.soft($.getByRole('heading', {})).toParse();
+ expect.soft($.getByRole('checkbox', { checked: true })).toParse();
+ expect.soft($.getByRole('checkbox', { checked: false })).toParse();
+ expect.soft($.getByRole('button', { disabled: true })).toParse();
+ expect.soft($.getByRole('button', { disabled: false })).toParse();
+ expect.soft($.getByRole('option', { selected: true })).toParse();
+ expect.soft($.getByRole('option', { selected: false })).toParse();
+ expect.soft($.getByRole('treeitem', { expanded: true })).toParse();
+ expect.soft($.getByRole('treeitem', { expanded: false })).toParse();
+ expect.soft($.getByRole('button', { includeHidden: true })).toParse();
+ expect.soft($.getByRole('button', { includeHidden: false })).toParse();
+ expect.soft($.getByRole('heading', { level: 1 })).toParse();
+ expect.soft($.getByRole('heading', { level: 6 })).toParse();
+ expect.soft($.getByRole('button', { pressed: true })).toParse();
+ expect.soft($.getByRole('button', { pressed: false })).toParse();
+ expect.soft($.getByRole('button', { exact: true })).toParse();
+ expect.soft($.getByRole('button', { exact: false })).toParse();
+ expect.soft($.getByRole('button', { name: /submit/i, exact: true })).toParse();
+ expect.soft($.getByRole('alert', { name: /upload/i, description: 'doc.pdf' })).toParse();
+ expect.soft($.getByRole('alert', { name: 'Upload', description: /doc\.pdf/, exact: true })).toParse();
+ expect.soft($.getByRole('checkbox', { checked: true, disabled: false, selected: true, expanded: false, includeHidden: true, level: 2, name: 'Agree', description: 'Terms', pressed: false, exact: true })).toParse();
+});
+
+it('should parse getByRole name and description', () => {
+ for (const text of kTexts) {
+ expect.soft($.getByRole('button', { name: text })).toParse(kAllStyles);
+ expect.soft($.getByRole('button', { name: text, exact: true })).toParse(kAllStyles);
+ expect.soft($.getByRole('button', { name: text, exact: false })).toParse(kAllStyles);
+ expect.soft($.getByRole('alert', { description: text })).toParse(kAllStyles);
+ expect.soft($.getByRole('alert', { description: text, exact: true })).toParse(kAllStyles);
+ expect.soft($.getByRole('alert', { name: 'Upload', description: text, exact: true })).toParse(kAllStyles);
+ }
+ for (const regex of kRegexes) {
+ expect.soft($.getByRole('button', { name: regex })).toParse(kAllStyles);
+ expect.soft($.getByRole('alert', { description: regex })).toParse(kAllStyles);
+ }
+});
+
+it('should parse getByRole options in any order', () => {
+ expect.soft($.getByRole('button', { exact: true, name: 'Submit' })).toParse();
+ expect.soft($.getByRole('alert', { description: 'doc.pdf', name: 'Upload' })).toParse();
+ expect.soft($.getByRole('heading', { name: 'Title', level: 2 })).toParse();
+ expect.soft($.getByRole('button', { pressed: true, name: 'Bold' })).toParse();
+ expect.soft($.getByRole('checkbox', { name: 'Agree', checked: true })).toParse();
+ expect.soft($.getByRole('treeitem', { expanded: true, selected: false, disabled: true })).toParse();
+ expect.soft($.getByRole('button', { includeHidden: true, checked: false })).toParse();
+ expect.soft($.getByRole('checkbox', { pressed: false, description: 'Terms', name: 'Agree', level: 2, includeHidden: true, expanded: false, selected: true, disabled: false, checked: true, exact: true })).toParse();
+});
+
+it('should parse locator with a selector', () => {
+ for (const selector of kSelectors) {
+ expect.soft($.locator(selector)).toParse(kAllStyles);
+ expect.soft($.locator('section').locator(selector)).toParse(kAllStyles);
+ expect.soft($.getByRole('main').locator(selector)).toParse(kAllStyles);
+ }
+});
+
+it('should parse locator and filter options', () => {
+ expect.soft($.locator('div').filter()).toParse();
+ expect.soft($.locator('div').filter({})).toParse();
+ expect.soft($.locator('div', {})).toParse();
+ expect.soft($.locator('section').locator($.getByRole('button'), { hasText: 'Hello' })).toParse();
+ expect.soft($.locator('div').filter({ visible: true, hasNot: $.locator('a'), has: $.locator('b'), hasNotText: 'x', hasText: 'y' })).toParse();
+ expect.soft($.locator('div', { hasNot: $.locator('a'), hasText: 'y' })).toParse();
+ expect.soft($.locator('div').filter({ hasText: 'a' }).filter({ hasText: 'b' }).filter({ has: $.locator('c') })).toParse();
+
+ const values = [
+ { hasText: 'Hello', hasNotText: 'Bye', has: $.getByRole('button'), hasNot: $.getByText('Sold out'), visible: true },
+ { hasText: /hello/i, hasNotText: /bye\s+now/, has: $.locator('span').first(), hasNot: $.locator('a', { hasText: 'x' }), visible: false },
+ { hasText: 'Say "hi"', hasNotText: `It's`, has: $.getByText('a >> b'), hasNot: $.getByTestId('Say "hi"'), visible: true },
+ ];
+ const keys = ['hasText', 'hasNotText', 'has', 'hasNot', 'visible'] as const;
+ for (const value of values) {
+ for (let mask = 1; mask < 1 << keys.length; ++mask) {
+ const options: any = {};
+ keys.forEach((key, index) => {
+ if (mask & (1 << index))
+ options[key] = value[key];
+ });
+ expect.soft($.locator('div').filter(options)).toParse(kAllStyles);
+ if ('visible' in options)
+ continue;
+ expect.soft($.locator('div', options)).toParse(kAllStyles);
+ expect.soft($.frameLocator('iframe').locator('div', options)).toParse(kAllStyles);
+ }
+ }
+});
+
+it('should parse first, last, nth and visible', () => {
+ expect.soft($.locator('li').first()).toParse();
+ expect.soft($.locator('li').last()).toParse();
+ for (const index of [0, 1, 2, 10, -1, -2])
+ expect.soft($.locator('li').nth(index)).toParse();
+ expect.soft($.locator('li').visible()).toParse();
+ expect.soft($.locator('li').visible().first()).toParse();
+ expect.soft($.locator('li').first().visible()).toParse();
+ expect.soft($.locator('li').nth(1).nth(0).last()).toParse();
+ expect.soft($.getByRole('listitem').nth(2).getByRole('button')).toParse();
+ expect.soft($.getByRole('row').last().getByRole('cell').first()).toParse();
+ expect.soft($.getByText('Item').visible().nth(-1)).toParse();
+});
+
+it('should parse and, or, locator and within with a locator argument', {
+ annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/43159' },
+}, () => {
+ const inners = [
+ $.locator('span'),
+ $.getByRole('button', { name: 'OK' }),
+ $.getByText('Say "hi"', { exact: true }),
+ $.getByTitle(/it's/i),
+ $.locator('div').first(),
+ $.getByTestId('x').filter({ hasText: 'y' }),
+ $.locator('a').and($.locator('.b')).or($.locator('.c')),
+ $.getByRole('cell').within($.getByRole('row')),
+ ];
+ for (const inner of inners) {
+ expect.soft($.locator('div').and(inner)).toParse();
+ expect.soft($.locator('div').or(inner)).toParse();
+ expect.soft($.locator('div').locator(inner)).toParse();
+ expect.soft($.locator('div').within(inner)).toParse();
+ expect.soft(inner.within($.locator('table'))).toParse();
+ expect.soft(inner.and($.locator('div')).first()).toParse();
+ }
+ expect.soft($.getByRole('cell').nth(2).within($.getByRole('row'))).toParse();
+ expect.soft($.getByRole('cell').within($.getByRole('row')).first()).toParse();
+ expect.soft($.getByRole('cell').within($.getByRole('row').within($.getByRole('table')))).toParse();
+ expect.soft($.frameLocator('iframe').getByRole('cell').within($.locator('tr'))).toParse();
+ expect.soft($.locator('a').or($.locator('b')).or($.locator('c'))).toParse();
+ expect.soft($.locator('a').and($.locator('b').and($.locator('c')))).toParse();
+});
+
+it('should parse chained refinements', () => {
+ const atoms: Locator[] = [
+ $.locator('div'),
+ $.getByRole('button', { name: 'Submit' }),
+ $.getByText('Hello'),
+ $.getByLabel(/name/i),
+ $.getByPlaceholder('Search', { exact: true }),
+ $.getByAltText('logo'),
+ $.getByTitle('Close'),
+ $.getByTestId('submit'),
+ $.getByRef('e5'),
+ ];
+ const refinements: ((locator: Locator) => Locator)[] = [
+ locator => locator.first(),
+ locator => locator.last(),
+ locator => locator.nth(2),
+ locator => locator.visible(),
+ locator => locator.filter({ hasText: 'x', visible: false }),
+ locator => locator.locator('span'),
+ locator => locator.locator($.getByText('x')),
+ locator => locator.getByRole('link', { name: 'More' }),
+ locator => locator.getByText('x', { exact: true }),
+ locator => locator.getByTestId('id'),
+ locator => locator.and($.getByTitle('t')),
+ locator => locator.or($.getByTitle('t')),
+ locator => locator.within($.locator('section')),
+ locator => locator.describe('My element'),
+ locator => locator.contentFrame().locator('body'),
+ locator => locator.frameLocator('iframe').getByText('y'),
+ ];
+ for (const atom of atoms) {
+ for (const refine of refinements)
+ expect.soft(refine(atom)).toParse();
+ }
+ for (const first of refinements) {
+ for (const second of refinements)
+ expect.soft(second(first($.locator('div')))).toParse();
+ }
+});
+
+it('should parse frame locators', () => {
+ const frames: FrameLocator[] = [
+ $.frameLocator('iframe'),
+ $.frameLocator('css=iframe'),
+ $.frameLocator('#frame1'),
+ $.frameLocator('iframe[name="embedded"]'),
+ $.frameLocator('iframe').first(),
+ $.frameLocator('iframe').last(),
+ $.frameLocator('iframe').nth(1),
+ $.locator('iframe').contentFrame(),
+ $.locator('iframe').first().contentFrame(),
+ $.locator('iframe').contentFrame().nth(-1),
+ $.getByTitle('Embedded').contentFrame(),
+ $.getByTestId('frame').nth(2).contentFrame(),
+ $.locator('div').frameLocator('iframe'),
+ $.frameLocator('#outer').frameLocator('#inner'),
+ $.locator('#outer').contentFrame().locator('#inner').contentFrame(),
+ $.frameLocator('#outer').getByTitle('Inner').contentFrame(),
+ $.frameLocator('#outer').locator('#inner').contentFrame().first(),
+ ];
+ for (const frame of frames) {
+ expect.soft(frame).toParse();
+ expect.soft(frame.locator('button')).toParse();
+ expect.soft(frame.locator('div', { hasText: 'Hello' })).toParse();
+ expect.soft(frame.getByRole('button', { name: 'OK' })).toParse();
+ expect.soft(frame.getByText('Hello', { exact: true })).toParse();
+ expect.soft(frame.getByLabel('Name')).toParse();
+ expect.soft(frame.getByPlaceholder(/search/i)).toParse();
+ expect.soft(frame.getByAltText('logo')).toParse();
+ expect.soft(frame.getByTitle('Close')).toParse();
+ expect.soft(frame.getByTestId('submit')).toParse();
+ expect.soft(frame.frameLocator('iframe').locator('span')).toParse();
+ expect.soft(frame.locator('li').first()).toParse();
+ expect.soft(frame.locator('li').nth(1).contentFrame().locator('body')).toParse();
+ }
+ expect.soft($.frameLocator()).toParse();
+ expect.soft($.frameLocator().locator('button')).toParse();
+ expect.soft($.frameLocator().getByText('Hello')).toParse();
+ expect.soft($.frameLocator().getByRole('button').first()).toParse();
+ expect.soft($.frameLocator().frameLocator('iframe').locator('span')).toParse();
+});
+
+it('should parse FrameLocator.locator with a locator argument', () => {
+ expect.soft($.frameLocator('iframe').locator($.getByRole('button'))).toParse();
+ expect.soft($.frameLocator('iframe').locator($.locator('span'))).toParse();
+ expect.soft($.frameLocator('iframe').locator($.getByText('Say "hi"', { exact: true }))).toParse();
+ expect.soft($.frameLocator('iframe').locator($.locator('div').first())).toParse();
+ expect.soft($.frameLocator('iframe').locator($.getByTestId('x').filter({ hasText: 'y' }))).toParse();
+ expect.soft($.frameLocator('iframe').locator($.locator('a').and($.locator('.b')).or($.locator('.c')))).toParse();
+ expect.soft($.frameLocator('iframe').locator($.getByRole('cell').within($.getByRole('row')))).toParse();
+ expect.soft($.frameLocator('iframe').first().locator($.getByRole('button'))).toParse();
+ expect.soft($.locator('iframe').contentFrame().locator($.getByRole('button'))).toParse();
+ expect.soft($.frameLocator().locator($.getByRole('button'))).toParse();
+});
+
+it('should parse owner', {
+ annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/43183' },
+}, () => {
+ expect.soft($.frameLocator('iframe').owner()).toParse();
+ expect.soft($.locator('iframe').contentFrame().owner()).toParse();
+ expect.soft($.frameLocator('iframe').first().owner()).toParse();
+ expect.soft($.frameLocator('iframe').nth(2).owner()).toParse();
+ expect.soft($.frameLocator('#outer').frameLocator('#inner').owner()).toParse();
+ expect.soft($.frameLocator('iframe').owner().locator('..')).toParse();
+ expect.soft($.frameLocator('iframe').owner().first()).toParse();
+ expect.soft($.frameLocator('iframe').owner().contentFrame().locator('body')).toParse();
+ expect.soft($.locator('div').filter({ has: $.frameLocator('iframe').owner() })).toParse();
+});
+
+it('should parse describe', {
+ annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/43181' },
+}, () => {
+ expect.soft($.getByTestId('btn-sub').describe('Subscribe button')).toParse();
+ expect.soft($.locator('div').describe('Say "hi"')).toParse();
+ expect.soft($.locator('div').describe(`It's here`)).toParse();
+ expect.soft($.getByRole('button').describe('Submit').first()).toParse();
+ expect.soft($.getByRole('button').describe('Submit').locator('span')).toParse();
+ expect.soft($.locator('div').filter({ has: $.getByText('x').describe('Inner') })).toParse();
+ expect.soft($.frameLocator('iframe').locator('div').describe('In frame')).toParse();
+ expect.soft($.locator('a').describe('A').or($.locator('b').describe('B'))).toParse();
+});
+
+it('should parse deeply nested locators', () => {
+ expect.soft($.locator('section').filter({ has: $.locator('div').filter({ has: $.getByText('Say "hi"').and($.getByRole('link', { name: /a"b/ })) }) })).toParse(kAllStyles);
+ expect.soft($.getByRole('row').filter({ hasNot: $.getByRole('cell').or($.getByText(`It's`)) }).within($.getByRole('table').filter({ has: $.getByText('line1\nline2') }))).toParse(kAllStyles);
+ expect.soft($.locator('a').and($.locator('b').or($.locator('c').and($.locator('d').or($.getByText('C:\\path')))))).toParse(kAllStyles);
+ expect.soft($.locator('ul').locator($.locator('li').filter({ has: $.locator('span').locator($.getByText('x >> y')) }))).toParse(kAllStyles);
+ expect.soft($.locator('div', { has: $.locator('p', { has: $.locator('span', { hasText: '"quoted"' }) }) })).toParse(kAllStyles);
+});
+
+it('should parse generated locators', {
+ annotation: [
+ { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/42891' },
+ { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/43158' },
+ ],
+}, () => {
+ expect.soft($.getByTestId('Hello')).toRoundTrip();
+ expect.soft($.getByTestId('He"llo')).toRoundTrip();
+ expect.soft($.getByTestId(/He"llo/)).toRoundTrip();
+ expect.soft($.getByTestId(/He\\"llo/)).toRoundTrip();
+ expect.soft($.getByText('Hello', { exact: true })).toRoundTrip();
+ expect.soft($.getByText('Hello')).toRoundTrip();
+ expect.soft($.getByText(/Hello/)).toRoundTrip();
+ expect.soft($.getByText('hello my\nwo"rld')).toRoundTrip();
+ expect.soft($.getByText('hello my wo"rld')).toRoundTrip();
+ expect.soft($.getByText(/he\/\sl\nlo/)).toRoundTrip();
+ expect.soft($.getByText(/hel"lo/)).toRoundTrip();
+ expect.soft($.getByLabel('Name')).toRoundTrip();
+ expect.soft($.getByLabel('Last Name', { exact: true })).toRoundTrip();
+ expect.soft($.getByLabel(/Last\s+name/i)).toRoundTrip();
+ expect.soft($.getByLabel('hello my\nwo"rld')).toRoundTrip();
+ expect.soft($.getByPlaceholder('hello')).toRoundTrip();
+ expect.soft($.getByPlaceholder('Hello', { exact: true })).toRoundTrip();
+ expect.soft($.getByPlaceholder(/wor/i)).toRoundTrip();
+ expect.soft($.getByPlaceholder('hello my\nwo"rld')).toRoundTrip();
+ expect.soft($.getByPlaceholder(/he\/\sl\nlo/)).toRoundTrip();
+ expect.soft($.getByPlaceholder(/hel"lo/)).toRoundTrip();
+ expect.soft($.getByAltText('hello')).toRoundTrip();
+ expect.soft($.getByAltText('Hello', { exact: true })).toRoundTrip();
+ expect.soft($.getByAltText(/wor/i)).toRoundTrip();
+ expect.soft($.getByAltText('hello my\nwo"rld')).toRoundTrip();
+ expect.soft($.getByTitle('hello')).toRoundTrip();
+ expect.soft($.getByTitle('Hello', { exact: true })).toRoundTrip();
+ expect.soft($.getByTitle(/wor/i)).toRoundTrip();
+ expect.soft($.getByTitle('hello my\nwo"rld')).toRoundTrip();
+ expect.soft($.getByRole('button')).toRoundTrip();
+ expect.soft($.getByRole('heading', {})).toRoundTrip();
+ expect.soft($.getByRole('button', { name: 'Hello' })).toRoundTrip();
+ expect.soft($.getByRole('button', { name: /Hello/ })).toRoundTrip();
+ expect.soft($.getByRole('button', { name: 'He"llo', exact: true })).toRoundTrip();
+ expect.soft($.getByRole('button', { checked: true, pressed: false, level: 3 })).toRoundTrip();
+ expect.soft($.getByRole('alert', { name: 'Upload', description: 'doc.pdf' })).toRoundTrip();
+ expect.soft($.getByRole('alert', { description: 'doc.pdf' })).toRoundTrip();
+ expect.soft($.getByRole('alert', { description: /doc\.pdf/ })).toRoundTrip();
+ expect.soft($.getByRole('alert', { name: 'Upload', description: 'doc.pdf', exact: true })).toRoundTrip();
+ expect.soft($.locator('div').nth(3).first().last()).toRoundTrip();
+ expect.soft($.getByText('Hello').filter({ hasText: 'wo"rld\n' })).toRoundTrip();
+ expect.soft($.getByText('Hello').filter({ hasText: /wo\/\srld\n/ })).toRoundTrip();
+ expect.soft($.getByText('Hello').filter({ hasText: /wor"ld/ })).toRoundTrip();
+ expect.soft($.getByText('Hello').filter({ hasNotText: 'wo"rld\n' })).toRoundTrip();
+ expect.soft($.getByText('Hello').visible().locator('div')).toRoundTrip();
+ expect.soft($.getByText('Hello').filter({ visible: false }).locator('div')).toRoundTrip();
+ expect.soft($.getByText('Hello').filter({ has: $.locator('div').getByText('bye') })).toRoundTrip();
+ expect.soft($.getByText('Hello').filter({ hasNot: $.locator('div').getByText('bye') })).toRoundTrip();
+ expect.soft($.locator('section').filter({ has: $.locator('div').filter({ has: $.locator('span') }) }).filter({ hasText: 'foo' }).filter({ has: $.locator('a') })).toRoundTrip();
+ expect.soft($.locator('section').filter({ has: $.locator('div').filter({ hasNot: $.locator('span') }) }).filter({ hasText: 'foo' }).filter({ hasNot: $.locator('a') })).toRoundTrip();
+ expect.soft($.locator('section').filter({ hasText: 'foo', has: $.locator('div') }).locator('a')).toRoundTrip();
+ expect.soft($.locator('div', { hasText: 'foo' }).nth(0).filter({ has: $.locator('span', { hasNotText: 'bar' }).nth(-1) })).toRoundTrip();
+ expect.soft($.frameLocator('iframe').getByText('foo', { exact: true }).frameLocator('frame').first().frameLocator('iframe').locator('span')).toRoundTrip();
+ expect.soft($.frameLocator().getByText('foo').locator('span')).toRoundTrip();
+ expect.soft($.getByTitle('iframe title').contentFrame()).toRoundTrip();
+ expect.soft($.getByRole('row').locator($.getByRole('cell').nth(2))).toRoundTrip();
+ expect.soft($.locator('div').and($.getByText('foo')).or($.locator('span').locator($.locator('a'))).first()).toRoundTrip();
+
+ expect.soft('div').toRoundTrip();
+ expect.soft('.foo').toRoundTrip();
+ expect.soft('//div').toRoundTrip();
+ expect.soft('internal:text="hello"i').toRoundTrip();
+ expect.soft('internal:text="hello"s').toRoundTrip();
+ expect.soft('internal:text=/he\\"llo/i').toRoundTrip();
+ expect.soft('internal:text=/a\\/b/').toRoundTrip();
+ expect.soft('internal:text=/a.b/ims').toRoundTrip();
+ expect.soft('internal:role=button[name=/a.b/ms]').toRoundTrip();
+ expect.soft('internal:role=button[name=/a.b/s]').toRoundTrip();
+ expect.soft('internal:text="a\'b\\"c`d"i').toRoundTrip();
+ expect.soft('internal:text="a\\\\b"i').toRoundTrip();
+ expect.soft('internal:text="tab\\there\\nnewline"i').toRoundTrip();
+ expect.soft('internal:text="\\u0001"i').toRoundTrip();
+ expect.soft('internal:label="x"s').toRoundTrip();
+ expect.soft('internal:label=/x/').toRoundTrip();
+ expect.soft('internal:attr=[placeholder="p"i]').toRoundTrip();
+ expect.soft('internal:attr=[alt="a"s]').toRoundTrip();
+ expect.soft('internal:attr=[title=/t/i]').toRoundTrip();
+ expect.soft('internal:testid=[data-testid="id"s]').toRoundTrip();
+ expect.soft('internal:testid=[data-testid=/id/]').toRoundTrip();
+ expect.soft('internal:role=button').toRoundTrip();
+ expect.soft('internal:role=button[name="ok"s]').toRoundTrip();
+ expect.soft('internal:role=button[name=/ok/i]').toRoundTrip();
+ expect.soft('internal:role=checkbox[checked=true][include-hidden=true]').toRoundTrip();
+ expect.soft('internal:role=checkbox[checked=mixed]').toRoundTrip();
+ expect.soft('internal:role=button[pressed=mixed]').toRoundTrip();
+ expect.soft('internal:role=heading[level=2][name="h"s]').toRoundTrip();
+ expect.soft('internal:role=alert[name="Upload"s][description="doc.pdf"s]').toRoundTrip();
+ expect.soft('internal:role=alert[name=/U/][description="d"i]').toRoundTrip();
+ expect.soft('internal:role=alert[name=/Upload/][description="doc.pdf"i]').toRoundTrip();
+ expect.soft('internal:role=alert[name="Upload"i][description=/doc\\.pdf/]').toRoundTrip();
+ expect.soft('internal:role=button[disabled=true][selected=true][expanded=true][pressed=false]').toRoundTrip();
+ expect.soft('div >> nth=0').toRoundTrip();
+ expect.soft('div >> nth=-1').toRoundTrip();
+ expect.soft('div >> nth=3').toRoundTrip();
+ expect.soft('div >> visible=true').toRoundTrip();
+ expect.soft('div >> visible=false').toRoundTrip();
+ expect.soft('div >> internal:has-text="foo"i >> span').toRoundTrip();
+ expect.soft('div >> internal:has-text="Goodbye world"i >> span').toRoundTrip();
+ expect.soft('div >> internal:has-not-text=/foo/').toRoundTrip();
+ expect.soft('div >> internal:has="span >> internal:has=\\"b\\""').toRoundTrip();
+ expect.soft('div >> internal:has-not="internal:role=button[name=\\"x\\"i]"').toRoundTrip();
+ expect.soft('iframe >> internal:control=enter-frame >> div').toRoundTrip();
+ expect.soft('iframe >> nth=0 >> internal:control=enter-frame >> div').toRoundTrip();
+ expect.soft('internal:attr=[title="t"i] >> internal:control=enter-frame').toRoundTrip();
+ expect.soft('internal:control=any-frame >> div').toRoundTrip();
+ expect.soft('div >> internal:and="span >> nth=0"').toRoundTrip();
+ expect.soft('div >> internal:and="span >> article"').toRoundTrip();
+ expect.soft('div >> internal:or="span"').toRoundTrip();
+ expect.soft('div >> internal:or="span >> article"').toRoundTrip();
+ expect.soft('div >> internal:chain="span >> article"').toRoundTrip();
+ expect.soft('div >> internal:chain="span >> internal:has-text=\\"x\\"i"').toRoundTrip();
+
+ // Python, Java and C# drop the regular expression flags they cannot express.
+ for (const flags of ['u', 'y', 'd', 'v', 'gm']) {
+ expect.soft(`internal:text=/Hello/${flags}`).toRoundTrip(['javascript']);
+ expect.soft(`internal:label=/Hello/${flags}`).toRoundTrip(['javascript']);
+ }
+});
+
+it('should parse javascript string escapes', () => {
+ expect.soft(javascript(String.raw`getByText('It\'s')`)).toBe(selectorOf($.getByText(`It's`)));
+ expect.soft(javascript(String.raw`getByText("Say \"hi\"")`)).toBe(selectorOf($.getByText('Say "hi"')));
+ expect.soft(javascript('getByText(`back\\`tick`)')).toBe(selectorOf($.getByText('back`tick')));
+ expect.soft(javascript(String.raw`getByText('C:\\path')`)).toBe(selectorOf($.getByText('C:\\path')));
+ expect.soft(javascript(String.raw`getByText('line1\nline2\r\n\ttab')`)).toBe(selectorOf($.getByText('line1\nline2\r\n\ttab')));
+ expect.soft(javascript(String.raw`getByText('\x41')`)).toBe(selectorOf($.getByText('A')));
+ expect.soft(javascript(String.raw`getByText('\u0041')`)).toBe(selectorOf($.getByText('A')));
+ expect.soft(javascript(String.raw`getByText('\u{1F600}')`)).toBe(selectorOf($.getByText('😀')));
+ expect.soft(javascript(String.raw`getByText('a\u00a0b')`)).toBe(selectorOf($.getByText('a\u00a0b')));
+ expect.soft(javascript(String.raw`getByText('\/\d')`)).toBe(selectorOf($.getByText('/d')));
+});
+
+it('should parse python string escapes', () => {
+ expect.soft(python(String.raw`get_by_text('It\'s')`)).toBe(selectorOf($.getByText(`It's`)));
+ expect.soft(python(String.raw`get_by_text("Say \"hi\"")`)).toBe(selectorOf($.getByText('Say "hi"')));
+ expect.soft(python(String.raw`get_by_text("C:\\path")`)).toBe(selectorOf($.getByText('C:\\path')));
+ expect.soft(python(String.raw`get_by_text(r"C:\path")`)).toBe(selectorOf($.getByText('C:\\path')));
+ expect.soft(python(String.raw`get_by_text(r'C:\path')`)).toBe(selectorOf($.getByText('C:\\path')));
+ expect.soft(python(String.raw`get_by_text("line1\nline2\ttab")`)).toBe(selectorOf($.getByText('line1\nline2\ttab')));
+ expect.soft(python(String.raw`get_by_text("\x41")`)).toBe(selectorOf($.getByText('A')));
+ expect.soft(python(String.raw`get_by_text("\u0041")`)).toBe(selectorOf($.getByText('A')));
+ expect.soft(python(String.raw`get_by_text("\U0001F600")`)).toBe(selectorOf($.getByText('😀')));
+ expect.soft(python(String.raw`get_by_text("a\xa0b")`)).toBe(selectorOf($.getByText('a\u00a0b')));
+ // Python keeps the backslash of unknown escape sequences.
+ expect.soft(python(String.raw`get_by_text("\d")`)).toBe(selectorOf($.getByText('\\d')));
+});
+
+it('should parse java string escapes', () => {
+ expect.soft(java(String.raw`getByText("Say \"hi\"")`)).toBe(selectorOf($.getByText('Say "hi"')));
+ expect.soft(java(String.raw`getByText("C:\\path")`)).toBe(selectorOf($.getByText('C:\\path')));
+ expect.soft(java(String.raw`getByText("line1\nline2\ttab")`)).toBe(selectorOf($.getByText('line1\nline2\ttab')));
+ expect.soft(java(String.raw`getByText("\u0041")`)).toBe(selectorOf($.getByText('A')));
+ expect.soft(java(String.raw`getByText("a\u00a0b")`)).toBe(selectorOf($.getByText('a\u00a0b')));
+ expect.soft(java(String.raw`getByText("\uD83D\uDE00")`)).toBe(selectorOf($.getByText('😀')));
+});
+
+it('should parse csharp string escapes', () => {
+ expect.soft(csharp(String.raw`GetByText("Say \"hi\"")`)).toBe(selectorOf($.getByText('Say "hi"')));
+ expect.soft(csharp(String.raw`GetByText("C:\\path")`)).toBe(selectorOf($.getByText('C:\\path')));
+ expect.soft(csharp(String.raw`GetByText("line1\nline2\ttab")`)).toBe(selectorOf($.getByText('line1\nline2\ttab')));
+ expect.soft(csharp(String.raw`GetByText("\u0041")`)).toBe(selectorOf($.getByText('A')));
+ expect.soft(csharp(String.raw`GetByText("a\u00a0b")`)).toBe(selectorOf($.getByText('a\u00a0b')));
+ expect.soft(csharp(String.raw`GetByText("\U0001F600")`)).toBe(selectorOf($.getByText('😀')));
+ expect.soft(csharp(String.raw`GetByText(@"C:\path")`)).toBe(selectorOf($.getByText('C:\\path')));
+ expect.soft(csharp(String.raw`GetByText(@"Say ""hi""")`)).toBe(selectorOf($.getByText('Say "hi"')));
+});
+
+it('should parse javascript regular expressions', () => {
+ expect.soft(javascript(String.raw`getByText(/hello/i)`)).toBe(selectorOf($.getByText(/hello/i)));
+ expect.soft(javascript(String.raw`getByText(/a\/b/)`)).toBe(selectorOf($.getByText(/a\/b/)));
+ expect.soft(javascript(String.raw`getByText(/[/]/)`)).toBe(selectorOf($.getByText(/[/]/)));
+ expect.soft(javascript(String.raw`getByText(/[\]/]/)`)).toBe(selectorOf($.getByText(/[\]/]/)));
+ expect.soft(javascript(String.raw`getByText(/a,b\)/)`)).toBe(selectorOf($.getByText(/a,b\)/)));
+ expect.soft(javascript(String.raw`getByText(/\p{L}+/u)`)).toBe(selectorOf($.getByText(/\p{L}+/u)));
+ expect.soft(javascript(String.raw`getByText(new RegExp('hello', 'i'))`)).toBe(selectorOf($.getByText(/hello/i)));
+ expect.soft(javascript(String.raw`getByText(new RegExp("a\\.b"))`)).toBe(selectorOf($.getByText(/a\.b/)));
+});
+
+it('should parse python regular expressions', () => {
+ expect.soft(python(String.raw`get_by_text(re.compile(r"hello", re.IGNORECASE))`)).toBe(selectorOf($.getByText(/hello/i)));
+ expect.soft(python(String.raw`get_by_text(re.compile(r'hello', re.I))`)).toBe(selectorOf($.getByText(/hello/i)));
+ expect.soft(python(String.raw`get_by_text(re.compile("hello", re.I | re.M | re.S))`)).toBe(selectorOf($.getByText(/hello/ims)));
+ expect.soft(python(String.raw`get_by_text(re.compile(r"\d+"))`)).toBe(selectorOf($.getByText(/\d+/)));
+ expect.soft(python(String.raw`get_by_text(re.compile("\\d+"))`)).toBe(selectorOf($.getByText(/\d+/)));
+ expect.soft(python(String.raw`get_by_text(re.compile("\d+"))`)).toBe(selectorOf($.getByText(/\d+/)));
+ expect.soft(python(String.raw`get_by_text(re.compile(r"a.b", flags=re.DOTALL))`)).toBe(selectorOf($.getByText(/a.b/s)));
+ expect.soft(python(String.raw`get_by_text(re.compile(r'say "hi"'))`)).toBe(selectorOf($.getByText(/say "hi"/)));
+ expect.soft(python(String.raw`get_by_role("button", name=re.compile(r"^submit$", re.IGNORECASE))`)).toBe(selectorOf($.getByRole('button', { name: /^submit$/i })));
+
+ const flagAliases: Styles = { python: [{ name: 'flag aliases', quote: '"', rawRegex: true, regexFlagAliases: true }] };
+ expect.soft($.getByText(/hello/i)).toParse(flagAliases);
+ expect.soft($.getByText(/a.b/ims)).toParse(flagAliases);
+ expect.soft($.getByRole('button', { name: /submit/i })).toParse(flagAliases);
+ expect.soft($.locator('div').filter({ hasText: /hello/m })).toParse(flagAliases);
+});
+
+it('should parse java regular expressions', () => {
+ expect.soft(java(String.raw`getByText(Pattern.compile("hello", Pattern.CASE_INSENSITIVE))`)).toBe(selectorOf($.getByText(/hello/i)));
+ expect.soft(java(String.raw`getByText(Pattern.compile("\\d+"))`)).toBe(selectorOf($.getByText(/\d+/)));
+ expect.soft(java(String.raw`getByText(Pattern.compile("a.b", Pattern.CASE_INSENSITIVE | Pattern.MULTILINE | Pattern.DOTALL))`)).toBe(selectorOf($.getByText(/a.b/ims)));
+ expect.soft(java(String.raw`getByText(Pattern.compile("say \"hi\""))`)).toBe(selectorOf($.getByText(/say "hi"/)));
+});
+
+it('should parse csharp regular expressions', () => {
+ expect.soft(csharp(String.raw`GetByText(new Regex("hello", RegexOptions.IgnoreCase))`)).toBe(selectorOf($.getByText(/hello/i)));
+ expect.soft(csharp(String.raw`GetByText(new Regex("\\d+"))`)).toBe(selectorOf($.getByText(/\d+/)));
+ expect.soft(csharp(String.raw`GetByText(new Regex(@"\d+"))`)).toBe(selectorOf($.getByText(/\d+/)));
+ expect.soft(csharp(String.raw`GetByText(new Regex(@"say ""hi"""))`)).toBe(selectorOf($.getByText(/say "hi"/)));
+ expect.soft(csharp(String.raw`GetByText(new Regex("a.b", RegexOptions.IgnoreCase | RegexOptions.Multiline | RegexOptions.Singleline))`)).toBe(selectorOf($.getByText(/a.b/ims)));
+
+ const verbatimStrings: Styles = { csharp: [{ name: 'verbatim strings', quote: '"', verbatimRegex: true }] };
+ for (const regex of kRegexes)
+ expect.soft($.getByText(regex)).toParse(verbatimStrings);
+ expect.soft($.getByRole('button', { name: /submit/i })).toParse(verbatimStrings);
+ expect.soft($.locator('div').filter({ hasText: /hello/ })).toParse(verbatimStrings);
+});
+
+it('should parse csharp options with an explicit type', () => {
+ const typedOptions: Styles = {
+ csharp: [
+ { name: 'typed options', quote: '"', optionsType: 'typed' },
+ { name: 'typed options with parentheses', quote: '"', optionsType: 'typed()' },
+ ],
+ };
+ expect.soft($.getByRole('button', { name: 'Submit', exact: true })).toParse(typedOptions);
+ expect.soft($.getByRole('button', { name: /submit/i })).toParse(typedOptions);
+ expect.soft($.getByText('Hello', { exact: true })).toParse(typedOptions);
+ expect.soft($.locator('div', { hasText: 'Hello' })).toParse(typedOptions);
+ expect.soft($.locator('div').filter({ hasText: /hello/, has: $.getByRole('button') })).toParse(typedOptions);
+ expect.soft($.locator('div').getByLabel('Name', { exact: true })).toParse(typedOptions);
+ expect.soft($.frameLocator('iframe').getByTitle('Close', { exact: true })).toParse(typedOptions);
+});
+
+it('should parse trailing commas', () => {
+ const trailingCommas: Styles = {
+ javascript: [{ name: 'trailing commas', quote: `'`, multiline: true, trailingCommas: true }],
+ python: [{ name: 'trailing commas', quote: '"', rawRegex: true, multiline: true, trailingCommas: true }],
+ csharp: [{ name: 'trailing commas', quote: '"', multiline: true, trailingCommas: true }],
+ };
+ expect.soft($.getByRole('button', { name: 'Submit', exact: true })).toParse(trailingCommas);
+ expect.soft($.locator('div', { hasText: 'Hello' }).filter({ has: $.getByRole('button') }).first()).toParse(trailingCommas);
+ expect.soft($.getByText(/hello/i).nth(1)).toParse(trailingCommas);
+ expect.soft($.frameLocator('iframe').getByLabel('Name', { exact: true })).toParse(trailingCommas);
+});
+
+it('should parse unusual whitespace', () => {
+ const goodbye = selectorOf($.locator('div').filter({ hasText: 'Goodbye world' }).locator('span'));
+ expect.soft(javascript(`getByRole ( 'button' , { name : 'Submit' } ) . first ( )`)).toBe(selectorOf($.getByRole('button', { name: 'Submit' }).first()));
+ expect.soft(javascript(`\n\tgetByRole('button')\n\t\t.first()\n`)).toBe(selectorOf($.getByRole('button').first()));
+ expect.soft(javascript(`locator\n('div')\n\n.filter({ hasText : 'Goodbye world'\n }\n).locator('span')\n`)).toBe(goodbye);
+ expect.soft(javascript(`\n locator("[id*=freetext-field]")\n .locator('input:below(:text("Assigned Number:"))')\n .locator(\`visible=true\`)\n `)).toBe(selectorOf($.locator('[id*=freetext-field]').locator('input:below(:text("Assigned Number:"))').locator('visible=true')));
+ expect.soft(python(`get_by_role ( "button" , name = "Submit" ) . first`)).toBe(selectorOf($.getByRole('button', { name: 'Submit' }).first()));
+ expect.soft(python(`get_by_text(re . compile ( r"hello" , re . IGNORECASE ))`)).toBe(selectorOf($.getByText(/hello/i)));
+ expect.soft(python(`\tlocator(\t"div").filter(\thas_text="Goodbye world"\t).locator\t("span")`)).toBe(goodbye);
+ expect.soft(python(`locator("div").filter(has_text='Goodbye world').locator('span')`)).toBe(goodbye);
+ expect.soft(java(`getByRole ( AriaRole . BUTTON , new Page . GetByRoleOptions ( ) . setName ( "Submit" ) ) . first ( )`)).toBe(selectorOf($.getByRole('button', { name: 'Submit' }).first()));
+ expect.soft(java(`getByText(Pattern . compile ( "hello" , Pattern . CASE_INSENSITIVE ))`)).toBe(selectorOf($.getByText(/hello/i)));
+ expect.soft(java(` locator("div" ). filter( new Locator. FilterOptions ( ) .setHasText( "Goodbye world" ) ).locator( "span")`)).toBe(goodbye);
+ expect.soft(csharp(`GetByRole ( AriaRole . Button , new ( ) { Name = "Submit" } ) . First`)).toBe(selectorOf($.getByRole('button', { name: 'Submit' }).first()));
+ expect.soft(csharp(`GetByText(new Regex ( "hello" , RegexOptions . IgnoreCase ))`)).toBe(selectorOf($.getByText(/hello/i)));
+ expect.soft(csharp(`Locator("div") . Filter (new ( ) { HasText = "Goodbye world" }).Locator( "span" )`)).toBe(goodbye);
+});
+
+it('should return selectors as is', () => {
+ for (const selector of [
+ 'div',
+ '#main',
+ 'text=Hello',
+ '//div',
+ 'xpath=//div',
+ 'css=div',
+ 'div >> nth=0',
+ 'role=button[name="Submit"]',
+ 'internal:role=button[name="Submit"i]',
+ 'iframe >> internal:control=enter-frame >> div',
+ ]) {
+ for (const lang of kLanguages)
+ expect.soft(parse(lang, selector), `${lang}: ${selector}`).toBe(selector);
+ }
+});
+
+it('should reject malformed javascript locators', () => {
+ expect.soft(javascript(`getByRole('button'`)).toMatch(/^Error/);
+ expect.soft(javascript(`getByRole('button'))`)).toMatch(/^Error/);
+ expect.soft(javascript(`getByRole('button', { name: 'Submit' )`)).toMatch(/^Error/);
+ expect.soft(javascript(`getByRole('button' { name: 'Submit' })`)).toMatch(/^Error/);
+ expect.soft(javascript(`getByRole('button', { name 'Submit' })`)).toMatch(/^Error/);
+ expect.soft(javascript(`getByRole('button', { name: 'Submit', exact })`)).toMatch(/^Error/);
+ expect.soft(javascript(`getByRole('button', { ...options })`)).toMatch(/^Error/);
+ expect.soft(javascript(`getByRole('button', { name: 'Submit' }, { exact: true })`)).toMatch(/^Error/);
+ expect.soft(javascript(`getByRole({ name: 'Submit' }, 'button')`)).toMatch(/^Error/);
+ expect.soft(javascript(`getByRole('button', { name: 'ok', exct: true })`)).toMatch(/^Error/);
+ expect.soft(javascript(`getByText('unterminated)`)).toMatch(/^Error/);
+ expect.soft(javascript(`getByText(/unterminated)`)).toMatch(/^Error/);
+ expect.soft(javascript(`getByText('a' 'b')`)).toMatch(/^Error/);
+ expect.soft(javascript(`getByText('a' + 'b')`)).toMatch(/^Error/);
+ expect.soft(javascript(`getByText(text)`)).toMatch(/^Error/);
+ expect.soft(javascript('getByText(`Hello ${name}`)')).toMatch(/^Error/);
+ expect.soft(javascript(`getByText('Hello', { exact: True })`)).toMatch(/^Error/);
+ expect.soft(javascript(`getByText(re.compile('hello'))`)).toMatch(/^Error/);
+ expect.soft(javascript(String.raw`getByText("\x4")`)).toMatch(/^Error/);
+ expect.soft(javascript(String.raw`getByText("\u{}")`)).toMatch(/^Error/);
+ expect.soft(javascript(String.raw`getByText("\u{110000}")`)).toMatch(/^Error/);
+ expect.soft(javascript(`locator('div')..first()`)).toMatch(/^Error/);
+ expect.soft(javascript(`locator('div')..locator('span')`)).toMatch(/^Error/);
+ expect.soft(javascript(`locator('div').`)).toMatch(/^Error/);
+ expect.soft(javascript(`.locator('div')`)).toMatch(/^Error/);
+ expect.soft(javascript(`locator('div') locator('span')`)).toMatch(/^Error/);
+ expect.soft(javascript(`locator('div').nth(0))`)).toMatch(/^Error/);
+ expect.soft(javascript(`locator('div').nth(-)`)).toMatch(/^Error/);
+ expect.soft(javascript(`locator('div').filter({ hasText: 'x' }})`)).toMatch(/^Error/);
+ expect.soft(javascript(`locator('div').filter({ hasText: 'Goodbye world' }}).locator('span')`)).toMatch(/^Error/);
+ expect.soft(javascript(`get_by_role('button')`)).toMatch(/^Error/);
+ expect.soft(javascript(`GetByRole('button')`)).toMatch(/^Error/);
+});
+
+it('should reject malformed python locators', () => {
+ expect.soft(python(`get_by_role("button"`)).toMatch(/^Error/);
+ expect.soft(python(`get_by_role("button", name="Submit"))`)).toMatch(/^Error/);
+ expect.soft(python(`get_by_role("button", name=="Submit")`)).toMatch(/^Error/);
+ expect.soft(python(`get_by_role("button", name: "Submit")`)).toMatch(/^Error/);
+ expect.soft(python(`get_by_role("button", {"name": "Submit"})`)).toMatch(/^Error/);
+ expect.soft(python(`get_by_role(name="Submit", "button")`)).toMatch(/^Error/);
+ expect.soft(python(`get_by_role("checkbox", cheked=True)`)).toMatch(/^Error/);
+ expect.soft(python(`get_by_text("Hello", exact=true)`)).toMatch(/^Error/);
+ expect.soft(python(`get_by_text("Hello", True)`)).toMatch(/^Error/);
+ expect.soft(python(`get_by_text(f"Hello {name}")`)).toMatch(/^Error/);
+ expect.soft(python(`get_by_text(text)`)).toMatch(/^Error/);
+ expect.soft(python(`get_by_text(re.compile(r"hello", re.VERBOSE))`)).toMatch(/^Error/);
+ expect.soft(python(`get_by_text(re.compile(r"hello", "i"))`)).toMatch(/^Error/);
+ expect.soft(python(`get_by_text(/hello/)`)).toMatch(/^Error/);
+ expect.soft(python(`locator("div").and(locator("span"))`)).toMatch(/^Error/);
+ expect.soft(python(`locator("div").filter(has_text=="Goodbye world").locator("span")`)).toMatch(/^Error/);
+ expect.soft(python(`locator("div").nth(0))`)).toMatch(/^Error/);
+ expect.soft(python(`getByRole("button")`)).toMatch(/^Error/);
+ expect.soft(python(`GetByRole("button")`)).toMatch(/^Error/);
+});
+
+it('should reject malformed java locators', () => {
+ expect.soft(java(`locator('div')`)).toMatch(/^Error/);
+ expect.soft(java(`locator('text="bar"')`)).toMatch(/^Error/);
+ expect.soft(java(`getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Submit")`)).toMatch(/^Error/);
+ expect.soft(java(`getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions.setName("Submit"))`)).toMatch(/^Error/);
+ expect.soft(java(`getByRole(AriaRole.BUTTON, Page.GetByRoleOptions().setName("Submit"))`)).toMatch(/^Error/);
+ expect.soft(java(`getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setNme("Submit"))`)).toMatch(/^Error/);
+ expect.soft(java(`getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().name("Submit"))`)).toMatch(/^Error/);
+ expect.soft(java(`getByText("Hello", true)`)).toMatch(/^Error/);
+ expect.soft(java(`getByText("Hello", new Page.GetByTextOptions().setExact(True))`)).toMatch(/^Error/);
+ expect.soft(java(`getByText(Pattern.compile("hello", Pattern.COMMENTS))`)).toMatch(/^Error/);
+ expect.soft(java(`getByText("Hello"),`)).toMatch(/^Error/);
+ expect.soft(java(`locator("div").filter(newLocator.FilterOptions().setHasText("foo"))`)).toMatch(/^Error/);
+ expect.soft(java(`locator("div").filter(new Locator.FilterOptions().setHasText("Goodbye world"))..locator("span")`)).toMatch(/^Error/);
+ expect.soft(java(`get_by_text("Hello")`)).toMatch(/^Error/);
+ expect.soft(java(`GetByText("Hello")`)).toMatch(/^Error/);
+});
+
+it('should reject malformed csharp locators', () => {
+ expect.soft(csharp(`Locator('div')`)).toMatch(/^Error/);
+ expect.soft(csharp(`Locator('text="bar"')`)).toMatch(/^Error/);
+ expect.soft(csharp(`GetByRole(AriaRole.Button, new() { Name = "Submit" )`)).toMatch(/^Error/);
+ expect.soft(csharp(`GetByRole(AriaRole.Button, new() { Nme = "Submit" })`)).toMatch(/^Error/);
+ expect.soft(csharp(`GetByRole(AriaRole.Button, new() { Name: "Submit" })`)).toMatch(/^Error/);
+ expect.soft(csharp(`GetByRole(AriaRole.Button, new { Name = "Submit" })`)).toMatch(/^Error/);
+ expect.soft(csharp(`GetByText("Hello", new() { Exact = True })`)).toMatch(/^Error/);
+ expect.soft(csharp(`GetByText(new Regex("hello", RegexOptions.ECMAScript))`)).toMatch(/^Error/);
+ expect.soft(csharp(`GetByText($"Hello {name}")`)).toMatch(/^Error/);
+ expect.soft(csharp(`GetByTestId(newRegex("id"))`)).toMatch(/^Error/);
+ expect.soft(csharp(`Locator("div").Nth(0))`)).toMatch(/^Error/);
+ expect.soft(csharp(`Locator("div").Filter(new() { HasText = "Goodbye world" }).Locator("span"))`)).toMatch(/^Error/);
+ expect.soft(csharp(`getByText("Hello")`)).toMatch(/^Error/);
+ expect.soft(csharp(`get_by_text("Hello")`)).toMatch(/^Error/);
+});
+
+it('should reject methods that the receiver does not have', () => {
+ const page = untyped($);
+ const frame = untyped($.frameLocator('iframe'));
+ const anyFrame = untyped($.frameLocator());
+ const locator = untyped($.locator('div'));
+ expect.soft(frame.filter({ hasText: 'x' })).toBeRejected();
+ expect.soft(frame.and($.locator('a'))).toBeRejected();
+ expect.soft(frame.or($.locator('a'))).toBeRejected();
+ expect.soft(frame.within($.locator('a'))).toBeRejected();
+ expect.soft(frame.visible()).toBeRejected();
+ expect.soft(frame.describe('x')).toBeRejected();
+ expect.soft(frame.contentFrame()).toBeRejected();
+ expect.soft(frame.getByRef('e1')).toBeRejected();
+ expect.soft(frame.frameLocator()).toBeRejected();
+ // frameLocator() matches any frame, so there is no frame element to pick.
+ expect.soft(anyFrame.first()).toBeRejected();
+ expect.soft(anyFrame.nth(1)).toBeRejected();
+ expect.soft(locator.owner()).toBeRejected();
+ expect.soft(locator.getByRef('e1')).toBeRejected();
+ expect.soft(locator.frameLocator()).toBeRejected();
+ expect.soft(page.nth(1)).toBeRejected();
+ expect.soft(page.filter({ hasText: 'x' })).toBeRejected();
+ expect.soft(page.and($.locator('a'))).toBeRejected();
+ expect.soft(page.or($.locator('a'))).toBeRejected();
+ expect.soft(page.within($.locator('a'))).toBeRejected();
+ expect.soft(page.describe('x')).toBeRejected();
+});
+
+it('should reject arguments of a wrong type or count', () => {
+ const page = untyped($);
+ const locator = untyped($.locator('div'));
+ expect.soft(page.getByText()).toBeRejected();
+ expect.soft(page.getByText(1)).toBeRejected();
+ expect.soft(page.getByText('a', 'b')).toBeRejected();
+ expect.soft(page.getByText('x', { name: 'y' })).toBeRejected();
+ expect.soft(page.getByText('x', { exact: 'true' })).toBeRejected();
+ expect.soft(page.getByRole()).toBeRejected();
+ expect.soft(page.getByRole('button', { name: 1 })).toBeRejected();
+ expect.soft(page.getByRole('button', { level: '2' })).toBeRejected();
+ expect.soft(page.getByRole('button', { checked: 'true' })).toBeRejected();
+ expect.soft(page.getByRole('button', { includeHidden: 1 })).toBeRejected();
+ expect.soft(page.getByRole('button', { name: $.getByText('x') })).toBeRejected();
+ expect.soft(page.getByRole('button', { nme: 'x' })).toBeRejected();
+ expect.soft(page.getByTestId()).toBeRejected();
+ expect.soft(page.getByTestId('x', { exact: true })).toBeRejected();
+ expect.soft(page.getByRef()).toBeRejected();
+ expect.soft(page.getByRef(/e1/)).toBeRejected();
+ expect.soft(page.getByRef('e1', 'e2')).toBeRejected();
+ expect.soft(page.locator()).toBeRejected();
+ expect.soft(page.locator(1)).toBeRejected();
+ expect.soft(page.locator('div', 'span')).toBeRejected();
+ expect.soft(page.locator('div', { exact: true })).toBeRejected();
+ expect.soft(page.locator('div', { visible: true })).toBeRejected();
+ expect.soft(page.frameLocator($.locator('iframe'))).toBeRejected();
+ expect.soft(page.frameLocator('a', 'b')).toBeRejected();
+ expect.soft(locator.filter('div')).toBeRejected();
+ expect.soft(locator.filter({ has: 'div' })).toBeRejected();
+ expect.soft(locator.filter({ hasNot: 'div' })).toBeRejected();
+ expect.soft(locator.filter({ hasText: $.getByText('x') })).toBeRejected();
+ expect.soft(locator.filter({ visible: 'true' })).toBeRejected();
+ expect.soft(locator.filter({ text: 'x' })).toBeRejected();
+ expect.soft(locator.nth()).toBeRejected();
+ expect.soft(locator.nth('1')).toBeRejected();
+ expect.soft(locator.nth(1, 2)).toBeRejected();
+ expect.soft(locator.first(1)).toBeRejected();
+ expect.soft(locator.and('span')).toBeRejected();
+ expect.soft(locator.and()).toBeRejected();
+ expect.soft(locator.or($.locator('a'), $.locator('b'))).toBeRejected();
+ expect.soft(locator.within('span')).toBeRejected();
+ expect.soft(locator.and($.frameLocator('iframe'))).toBeRejected();
+ expect.soft(locator.within($.frameLocator('iframe'))).toBeRejected();
+ expect.soft(locator.filter({ has: $.frameLocator('iframe') })).toBeRejected();
+ expect.soft(locator.describe()).toBeRejected();
+ expect.soft(locator.describe(1)).toBeRejected();
+ expect.soft(locator.contentFrame('iframe')).toBeRejected();
+});
+
+// Allows calls that the typed API does not have.
+function untyped(value: Page | Built): Record<string, (...args: any[]) => Built> {
+ return value as any;
+}
+
+function parse(lang: Language, code: string, testIdAttributeName = 'data-testid'): string {
+ try {
+ return unsafeLocatorOrSelectorAsSelector(lang, code, testIdAttributeName);
+ } catch (e) {
+ return `Error: ${e.message}`;
+ }
+}
+
+// The selector that the API builds for a recorded locator.
+function selectorOf(built: Built): string {
+ const result = replay(built);
+ if (result instanceof client.Locator)
+ return canonicalSelector(result._selector);
+ const frameSelector = result._frameSelector;
+ if (frameSelector === kAnyFrameSelector)
+ return frameSelector;
+ return canonicalSelector(frameSelector + ' >> internal:control=enter-frame');
+}
+
+function replay(value: any): any {
+ if (recordedCalls.has(value)) {
+ const [{ method, args }, ...calls] = recordedCalls.get(value)!;
+ let result: any = startChain(method, args.map(replay));
+ for (const { method, args } of calls)
+ result = result[method](...args.map(replay));
+ return result;
+ }
+ if (isOptions(value))
+ return Object.fromEntries(Object.entries(value).map(([name, option]) => [name, replay(option)]));
+ return value;
+}
+
+function startChain(method: string, args: any[]): Built {
+ if (method === 'frameLocator')
+ return new client.FrameLocator(null, args[0] ?? kAnyFrameSelector);
+ if (method === 'locator')
+ return new client.Locator(null, args[0], args[1]);
+ return new client.Locator(null, kPageSelectors[method](...args));
+}
+
+// The parser normalizes selector strings, e.g. "css=div" into "div", including nested selectors.
+function canonicalSelector(selector: string): string {
+ const parsed = parseSelector(selector);
+ return stringifySelector({
+ ...parsed,
+ parts: parsed.parts.map(part => typeof part.body === 'object' && 'parsed' in part.body ? { ...part, source: JSON.stringify(canonicalSelector(JSON.parse(part.source))) } : part),
+ });
+}
+
+function isOptions(value: any): boolean {
+ return typeof value === 'object' && !(value instanceof RegExp) && !recordedCalls.has(value);
+}
+
+function render(lang: Language, built: Built, style: Style): string {
+ let receiver: Receiver = 'Page';
+ const calls: string[] = [];
+ for (const call of recordedCalls.get(built)!) {
+ calls.push(renderCall(lang, receiver, call, style));
+ receiver = returnType(receiver, call.method);
+ }
+ return calls.join(style.multiline ? '\n .' : '.');
+}
+
+function returnType(receiver: Receiver, method: string): Receiver {
+ if (method === 'frameLocator' || method === 'contentFrame')
+ return 'FrameLocator';
+ if (receiver === 'FrameLocator' && ['first', 'last', 'nth'].includes(method))
+ return 'FrameLocator';
+ return 'Locator';
+}
+
+function renderCall(lang: Language, receiver: Receiver, { method, args }: Call, style: Style): string {
+ const name = methodName(lang, method);
+ // Python and C# expose methods without arguments as properties, e.g. `.first` and `.First`.
+ if (!args.length && (lang === 'python' || lang === 'csharp') && ['first', 'last', 'contentFrame', 'owner', 'visible'].includes(method))
+ return name;
+ const items = args.flatMap((arg, index) => {
+ if (method === 'getByRole' && index === 0)
+ return [renderRole(lang, arg, style)];
+ if (isOptions(arg))
+ return renderOptions(lang, receiver, method, arg, style);
+ return [renderValue(lang, arg, style)];
+ });
+ return `${name}(${renderList(items, style, style.trailingCommas && (lang === 'javascript' || lang === 'python'), ' ', ' ')})`;
+}
+
+function methodName(lang: Language, method: string): string {
+ if (lang === 'python')
+ return method === 'and' || method === 'or' ? method + '_' : method.replace(/[A-Z]/g, char => '_' + char.toLowerCase());
+ if (lang === 'csharp')
+ return upperFirst(method);
+ return method;
+}
+
+function renderOptions(lang: Language, receiver: Receiver, method: string, options: object, style: Style): string[] {
+ const entries = Object.entries(options);
+ if (lang === 'python')
+ return entries.map(([name, value]) => `${name.replace(/[A-Z]/g, char => '_' + char.toLowerCase())}=${renderValue(lang, value, style)}`);
+ if (lang === 'java') {
+ const setters = entries.map(([name, value]) => `.set${upperFirst(name)}(${renderValue(lang, value, style)})`);
+ return [`new ${receiver}.${upperFirst(method)}Options()${setters.join(style.multiline ? '\n ' : '')}`];
+ }
+ const separator = style.compact ? (lang === 'csharp' ? '=' : ':') : (lang === 'csharp' ? ' = ' : ': ');
+ const properties = entries.map(([name, value]) => {
+ // C# has a separate property for regular expressions, e.g. `NameRegex`.
+ const property = lang === 'csharp' ? upperFirst(name) + (value instanceof RegExp ? 'Regex' : '') : name;
+ return property + separator + renderValue(lang, value, style);
+ });
+ const body = properties.length ? renderBag(properties, style) : '{}';
+ if (lang === 'javascript')
+ return [body];
+ const type = style.optionsType ? ` ${receiver}${upperFirst(method)}Options${style.optionsType === 'typed()' ? '()' : ''}` : '()';
+ return [`new${type}${style.compact ? '' : ' '}${body}`];
+}
+
+function renderBag(properties: string[], style: Style): string {
+ const trailingComma = style.trailingCommas ? ',' : '';
+ if (style.multiline)
+ return `{\n ${properties.join(',\n ')}${trailingComma}\n }`;
+ if (style.compact)
+ return `{${properties.join(',')}${trailingComma}}`;
+ return `{ ${properties.join(', ')}${trailingComma} }`;
+}
+
+function renderList(items: string[], style: Style, trailingComma: boolean, indent: string, closingIndent: string): string {
+ if (!items.length)
+ return '';
+ const comma = trailingComma ? ',' : '';
+ if (style.multiline)
+ return `\n${indent}${items.join(`,\n${indent}`)}${comma}\n${closingIndent}`;
+ return items.join(style.compact ? ',' : ', ') + comma;
+}
+
+function renderRole(lang: Language, role: string, style: Style): string {
+ if (lang === 'java')
+ return `AriaRole.${role.toUpperCase()}`;
+ if (lang === 'csharp')
+ return `AriaRole.${upperFirst(role)}`;
+ return quote(role, style.quote);
+}
+
+function renderValue(lang: Language, value: any, style: Style): string {
+ if (recordedCalls.has(value))
+ return render(lang, value, style);
+ if (value instanceof RegExp)
+ return renderRegex(lang, value, style);
+ if (typeof value === 'string')
+ return quote(value, style.quote);
+ if (typeof value === 'boolean' && lang === 'python')
+ return value ? 'True' : 'False';
+ return String(value);
+}
+
+function renderRegex(lang: Language, regex: RegExp, style: Style): string {
+ if (lang === 'javascript')
+ return String(regex);
+ const flagNames = {
+ python: style.regexFlagAliases ? { i: 're.I', m: 're.M', s: 're.S' } : { i: 're.IGNORECASE', m: 're.MULTILINE', s: 're.DOTALL' },
+ java: { i: 'Pattern.CASE_INSENSITIVE', m: 'Pattern.MULTILINE', s: 'Pattern.DOTALL' },
+ csharp: { i: 'RegexOptions.IgnoreCase', m: 'RegexOptions.Multiline', s: 'RegexOptions.Singleline' },
+ }[lang];
+ const flags = [...regex.flags].map(flag => {
+ if (!flagNames[flag])
+ throw new Error(`Regular expression flag "${flag}" cannot be expressed in ${lang}`);
+ return flagNames[flag];
+ });
+ let source = quote(regex.source, style.quote);
+ if (lang === 'python' && style.rawRegex)
+ source = 'r' + style.quote + regex.source.replaceAll(style.quote, '\\' + style.quote) + style.quote;
+ if (lang === 'csharp' && style.verbatimRegex)
+ source = '@"' + regex.source.replaceAll('"', '""') + '"';
+ const args = [source, ...(flags.length ? [flags.join(' | ')] : [])].join(', ');
+ if (lang === 'python')
+ return `re.compile(${args})`;
+ if (lang === 'java')
+ return `Pattern.compile(${args})`;
+ return `new Regex(${args})`;
+}
+
+function quote(text: string, quoteChar: string): string {
+ let result = '';
+ for (const char of text) {
+ if (char === '\\' || char === quoteChar || (quoteChar === '`' && char === '$'))
+ result += '\\' + char;
+ else if (char === '\n')
+ result += '\\n';
+ else if (char === '\r')
+ result += '\\r';
+ else if (char === '\t')
+ result += '\\t';
+ else
+ result += char;
+ }
+ return quoteChar + result + quoteChar;
+}
+
+function upperFirst(text: string): string {
+ return text.charAt(0).toUpperCase() + text.substring(1);
+}