Skip to content

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

feat(selectors): add pierceFrames context option (#42033)

Dmitry Gozmand7775efb41c8
diff --git a/docs/src/api/class-frame.md b/docs/src/api/class-frame.md
index 50173bbb8b..56db47d57f 100644
--- a/docs/src/api/class-frame.md
+++ b/docs/src/api/class-frame.md
@@ -1479,6 +1479,13 @@ var locator = frame.PierceFrames.GetByRole(AriaRole.Button);
await locator.ClickAsync();
```
+### option: Frame.pierceFrames.pierce
+* since: v1.63
+- `pierce` <[boolean]>
+
+Whether to pierce frames. Pass `false` to opt out of frame piercing enabled
+by the [`option: Browser.newContext.pierceFrames`] context option. Defaults to `true`.
+
## async method: Frame.press
* since: v1.8
* discouraged: Use locator-based [`method: Locator.press`] instead. Read more about [locators](../locators.md).
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index d631c89a16..423fc97eef 100644
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@@ -3208,6 +3208,13 @@ var locator = page.PierceFrames.GetByRole(AriaRole.Button);
await locator.ClickAsync();
```
+### option: Page.pierceFrames.pierce
+* since: v1.63
+- `pierce` <[boolean]>
+
+Whether to pierce frames. Pass `false` to opt out of frame piercing enabled
+by the [`option: Browser.newContext.pierceFrames`] context option. Defaults to `true`.
+
## async method: Page.press
* since: v1.8
* discouraged: Use locator-based [`method: Locator.press`] instead. Read more about [locators](../locators.md).
diff --git a/docs/src/api/params.md b/docs/src/api/params.md
index bf7a70b907..9a812dc0e5 100644
--- a/docs/src/api/params.md
+++ b/docs/src/api/params.md
@@ -885,6 +885,12 @@ Actual picture of each page will be scaled down if necessary to fit the specifie
Network proxy settings to use with this context. Defaults to none.
+## context-option-pierce-frames
+- `pierceFrames` <[boolean]>
+
+If set to true, all selectors in this context will pierce frames by default, as if every locator
+was created through [`method: Page.pierceFrames`]. Defaults to `false`.
+
## context-option-strict
- `strictSelectors` <[boolean]>
@@ -1124,6 +1130,7 @@ between the same pixel in compared images, between zero (strict) and one (lax),
- %%-context-option-recordvideo-%%
- %%-context-option-recordvideo-dir-%%
- %%-context-option-recordvideo-size-%%
+- %%-context-option-pierce-frames-%%
- %%-context-option-strict-%%
- %%-context-option-service-worker-policy-%%
diff --git a/docs/src/test-api/class-testoptions.md b/docs/src/test-api/class-testoptions.md
index fbf8e9f24f..1db97d3d13 100644
--- a/docs/src/test-api/class-testoptions.md
+++ b/docs/src/test-api/class-testoptions.md
@@ -462,6 +462,21 @@ export default defineConfig({
});
```
+## property: TestOptions.pierceFrames = %%-context-option-pierce-frames-%%
+* since: v1.63
+
+**Usage**
+
+```js title="playwright.config.ts"
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+ use: {
+ pierceFrames: true,
+ }
+});
+```
+
## property: TestOptions.proxy = %%-browser-option-proxy-%%
* since: v1.10
diff --git a/packages/isomorphic/locatorGenerators.ts b/packages/isomorphic/locatorGenerators.ts
index 9bb9d31814..f0e037ac76 100644
--- a/packages/isomorphic/locatorGenerators.ts
+++ b/packages/isomorphic/locatorGenerators.ts
@@ -21,7 +21,7 @@ import type { NestedSelectorBody } from './selectorParser';
import type { ParsedSelector } from './selectorParser';
export type Language = 'javascript' | 'python' | 'java' | 'csharp' | 'jsonl';
-export type LocatorType = 'default' | 'role' | 'text' | 'label' | 'placeholder' | 'alt' | 'title' | 'test-id' | 'nth' | 'first' | 'last' | 'visible' | 'has-text' | 'has-not-text' | 'has' | 'hasNot' | 'frame' | 'frame-locator' | 'pierce-frames' | 'and' | 'or' | 'chain';
+export type LocatorType = 'default' | 'role' | 'text' | 'label' | 'placeholder' | 'alt' | 'title' | 'test-id' | 'nth' | 'first' | 'last' | 'visible' | 'has-text' | 'has-not-text' | 'has' | 'hasNot' | 'frame' | 'frame-locator' | 'pierce-frames' | 'no-pierce-frames' | 'and' | 'or' | 'chain';
export type LocatorBase = 'page' | 'locator' | 'frame-locator';
export type Quote = '\'' | '"' | '`';
@@ -205,8 +205,8 @@ function innerAsLocators(factory: LocatorFactory, parsed: ParsedSelector, isFram
continue;
}
}
- if (part.name === 'internal:control' && (part.body as string) === 'pierce-frames') {
- tokens.push([factory.generateLocator(base, 'pierce-frames', '')]);
+ if (part.name === 'internal:control' && ((part.body as string) === 'pierce-frames' || (part.body as string) === 'no-pierce-frames')) {
+ tokens.push([factory.generateLocator(base, part.body as LocatorType, '')]);
nextBase = 'frame-locator';
continue;
}
@@ -322,6 +322,8 @@ export class JavaScriptLocatorFactory implements LocatorFactory {
return `contentFrame()`;
case 'pierce-frames':
return `pierceFrames()`;
+ case 'no-pierce-frames':
+ return `pierceFrames({ pierce: false })`;
case 'nth':
return `nth(${body})`;
case 'first':
@@ -423,6 +425,8 @@ export class PythonLocatorFactory implements LocatorFactory {
return `content_frame`;
case 'pierce-frames':
return `pierce_frames`;
+ case 'no-pierce-frames':
+ return `pierce_frames(pierce=False)`;
case 'nth':
return `nth(${body})`;
case 'first':
@@ -537,6 +541,8 @@ export class JavaLocatorFactory implements LocatorFactory {
return `contentFrame()`;
case 'pierce-frames':
return `pierceFrames()`;
+ case 'no-pierce-frames':
+ return `pierceFrames(new ${clazz}.PierceFramesOptions().setPierce(false))`;
case 'nth':
return `nth(${body})`;
case 'first':
@@ -641,6 +647,8 @@ export class CSharpLocatorFactory implements LocatorFactory {
return `ContentFrame`;
case 'pierce-frames':
return `PierceFrames`;
+ case 'no-pierce-frames':
+ return `PierceFrames(new() { Pierce = false })`;
case 'nth':
return `Nth(${body})`;
case 'first':
diff --git a/packages/isomorphic/selectorParser.ts b/packages/isomorphic/selectorParser.ts
index 74818985bc..a13afb8030 100644
--- a/packages/isomorphic/selectorParser.ts
+++ b/packages/isomorphic/selectorParser.ts
@@ -91,24 +91,25 @@ export function parseSelector(selector: string): ParsedSelector {
};
}
-// Splits a selector into per-frame chunks separated by "enter-frame" boundaries. When the selector
-// starts with the "pierce-frames" token, `pierce` is set globally and "enter-frame" tokens are
-// preserved, so `chunks` holds a single chunk.
-export function splitSelectorByFrame(selectorText: string): { pierce: boolean, chunks: ParsedSelector[] } {
+// Splits a selector into per-frame chunks separated by "enter-frame" boundaries in non-piercing mode.
+// In piercing mode, "enter-frame" tokens are preserved, so `chunks` holds a single chunk.
+export function splitSelectorByFrame(selectorText: string, pierceByDefault?: boolean): { pierce: boolean, chunks: ParsedSelector[] } {
const selector = parseSelector(selectorText);
const chunks: ParsedSelector[] = [];
let chunk: ParsedSelector = {
parts: [],
};
- let pierce = false;
+ let pierce = !!pierceByDefault;
+ let pierceToken = false;
let chunkStartIndex = 0;
for (let i = 0; i < selector.parts.length; ++i) {
const part = selector.parts[i];
- if (part.name === 'internal:control' && part.body === 'pierce-frames') {
- // Piercing is a whole-page operation, so it only makes sense as the very first token.
+ if (part.name === 'internal:control' && (part.body === 'pierce-frames' || part.body === 'no-pierce-frames')) {
+ // Piercing applies to the whole selector, so the token only makes sense as the very first one.
if (i !== 0)
- throw new InvalidSelectorError(`"pierce-frames" is only allowed as the first selector token, while parsing selector ${selectorText}`);
- pierce = true;
+ throw new InvalidSelectorError(`"${part.body}" is only allowed as the first selector token, while parsing selector ${selectorText}`);
+ pierce = part.body === 'pierce-frames';
+ pierceToken = true;
chunkStartIndex = i + 1;
continue;
}
@@ -130,7 +131,7 @@ export function splitSelectorByFrame(selectorText: string): { pierce: boolean, c
chunk.parts.push(part);
}
if (!chunk.parts.length) {
- if (pierce)
+ if (pierceToken)
throw new InvalidSelectorError(`Selector cannot be empty when piercing frames, while parsing selector ${selectorText}`);
throw new InvalidSelectorError(`Selector cannot end with entering frame, while parsing selector ${selectorText}`);
}
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index b1bc91b00b..177bf2afe3 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -4188,8 +4188,16 @@ export interface Page {
* await locator.click();
* ```
*
+ * @param options
*/
- pierceFrames(): FrameLocator;
+ pierceFrames(options?: {
+ /**
+ * Whether to pierce frames. Pass `false` to opt out of frame piercing enabled by the
+ * [`pierceFrames`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-pierce-frames) context
+ * option. Defaults to `true`.
+ */
+ pierce?: boolean;
+ }): FrameLocator;
/**
* **NOTE** Use locator-based [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press)
@@ -8229,8 +8237,16 @@ export interface Frame {
* await locator.click();
* ```
*
+ * @param options
*/
- pierceFrames(): FrameLocator;
+ pierceFrames(options?: {
+ /**
+ * Whether to pierce frames. Pass `false` to opt out of frame piercing enabled by the
+ * [`pierceFrames`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-pierce-frames) context
+ * option. Defaults to `true`.
+ */
+ pierce?: boolean;
+ }): FrameLocator;
/**
* **NOTE** Use locator-based [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press)
@@ -11424,6 +11440,13 @@ export interface Browser {
*/
permissions?: Array<string>;
+ /**
+ * If set to true, all selectors in this context will pierce frames by default, as if every locator was created
+ * through [page.pierceFrames([options])](https://playwright.dev/docs/api/class-page#page-pierce-frames). Defaults to
+ * `false`.
+ */
+ pierceFrames?: boolean;
+
/**
* Network proxy settings to use with this context. Defaults to none.
*/
@@ -17494,6 +17517,13 @@ export interface BrowserType<Unused = {}> {
*/
permissions?: Array<string>;
+ /**
+ * If set to true, all selectors in this context will pierce frames by default, as if every locator was created
+ * through [page.pierceFrames([options])](https://playwright.dev/docs/api/class-page#page-pierce-frames). Defaults to
+ * `false`.
+ */
+ pierceFrames?: boolean;
+
/**
* Network proxy settings.
*/
@@ -24504,6 +24534,13 @@ export interface AndroidDevice {
*/
permissions?: Array<string>;
+ /**
+ * If set to true, all selectors in this context will pierce frames by default, as if every locator was created
+ * through [page.pierceFrames([options])](https://playwright.dev/docs/api/class-page#page-pierce-frames). Defaults to
+ * `false`.
+ */
+ pierceFrames?: boolean;
+
/**
* Optional package name to launch instead of default Chrome for Android.
*/
@@ -25721,6 +25758,13 @@ export interface BrowserContextOptions {
*/
permissions?: Array<string>;
+ /**
+ * If set to true, all selectors in this context will pierce frames by default, as if every locator was created
+ * through [page.pierceFrames([options])](https://playwright.dev/docs/api/class-page#page-pierce-frames). Defaults to
+ * `false`.
+ */
+ pierceFrames?: boolean;
+
/**
* Network proxy settings to use with this context. Defaults to none.
*/
diff --git a/packages/playwright-core/src/client/channels.d.ts b/packages/playwright-core/src/client/channels.d.ts
index 02035b33e2..07944f33b1 100644
--- a/packages/playwright-core/src/client/channels.d.ts
+++ b/packages/playwright-core/src/client/channels.d.ts
@@ -428,6 +428,7 @@ export type AndroidDeviceLaunchBrowserParams = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -495,6 +496,7 @@ export type AndroidDeviceLaunchBrowserOptions = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -875,6 +877,7 @@ export type BrowserNewContextParams = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -945,6 +948,7 @@ export type BrowserNewContextOptions = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -1018,6 +1022,7 @@ export type BrowserNewContextForReuseParams = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -1088,6 +1093,7 @@ export type BrowserNewContextForReuseOptions = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -1200,6 +1206,7 @@ export type BrowserContextInitializer = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -1843,6 +1850,7 @@ export type BrowserTypeLaunchPersistentContextParams = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -1926,6 +1934,7 @@ export type BrowserTypeLaunchPersistentContextOptions = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -2026,6 +2035,7 @@ export type ElectronLaunchParams = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
timezoneId?: string,
tracesDir?: string,
artifactsDir?: string,
@@ -2065,6 +2075,7 @@ export type ElectronLaunchOptions = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
timezoneId?: string,
tracesDir?: string,
artifactsDir?: string,
diff --git a/packages/playwright-core/src/client/frame.ts b/packages/playwright-core/src/client/frame.ts
index 7bec0b1290..b665295bf0 100644
--- a/packages/playwright-core/src/client/frame.ts
+++ b/packages/playwright-core/src/client/frame.ts
@@ -28,7 +28,7 @@ import { ElementHandle, convertInputFiles, convertSelectOptionValues } from './e
import { AbortError, PlaywrightError } from './errors';
import { Events } from './events';
import { JSHandle, assertEvaluateOptions, assertMaxArguments, parseResult, serializeArgument, serializeArgumentWithCallbacks } from './jsHandle';
-import { FrameLocator, kPierceFramesSelector, Locator, testIdAttributeName } from './locator';
+import { FrameLocator, kNoPierceFramesSelector, kPierceFramesSelector, Locator, testIdAttributeName } from './locator';
import * as network from './network';
import { kLifecycleEvents } from './types';
import { Waiter } from './waiter';
@@ -397,8 +397,8 @@ export class Frame extends ChannelOwner<channels.FrameChannel> implements api.Fr
return new FrameLocator(this, selector);
}
- pierceFrames(): FrameLocator {
- return new FrameLocator(this, kPierceFramesSelector);
+ pierceFrames(options?: { pierce?: boolean }): FrameLocator {
+ return new FrameLocator(this, options?.pierce === false ? kNoPierceFramesSelector : kPierceFramesSelector);
}
async focus(selector: string, options: channels.FrameFocusOptions & TimeoutOptions = {}) {
diff --git a/packages/playwright-core/src/client/locator.ts b/packages/playwright-core/src/client/locator.ts
index fe48cab8bd..e1cdf3c615 100644
--- a/packages/playwright-core/src/client/locator.ts
+++ b/packages/playwright-core/src/client/locator.ts
@@ -423,6 +423,8 @@ export class Locator implements api.Locator {
export const kPierceFramesSelector = 'internal:control=pierce-frames';
+export const kNoPierceFramesSelector = 'internal:control=no-pierce-frames';
+
function selectorPiercesFrames(selector: string): boolean {
return selector === kPierceFramesSelector || selector.startsWith(kPierceFramesSelector + ' >> ');
}
@@ -437,7 +439,7 @@ export class FrameLocator implements api.FrameLocator {
}
private _childSelector(selector: string): string {
- if (this._frameSelector === kPierceFramesSelector)
+ if (this._frameSelector === kPierceFramesSelector || this._frameSelector === kNoPierceFramesSelector)
return this._frameSelector + ' >> ' + selector;
return this._frameSelector + ' >> internal:control=enter-frame >> ' + selector;
}
@@ -489,6 +491,8 @@ export class FrameLocator implements api.FrameLocator {
private _nthSelector(nth: string): string {
if (selectorPiercesFrames(this._frameSelector))
throw new Error(`Selecting the nth frame is not allowed while piercing frames.`);
+ if (this._frameSelector === kNoPierceFramesSelector)
+ throw new Error(`Selecting the nth frame is not allowed on the root frame locator.`);
return this._frameSelector + ` >> nth=${nth}`;
}
diff --git a/packages/playwright-core/src/client/page.ts b/packages/playwright-core/src/client/page.ts
index c6dd7f7937..e9b088be1d 100644
--- a/packages/playwright-core/src/client/page.ts
+++ b/packages/playwright-core/src/client/page.ts
@@ -783,8 +783,8 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
return this.mainFrame().frameLocator(selector);
}
- pierceFrames(): FrameLocator {
- return this.mainFrame().pierceFrames();
+ pierceFrames(options?: { pierce?: boolean }): FrameLocator {
+ return this.mainFrame().pierceFrames(options);
}
async focus(selector: string, options?: channels.FrameFocusOptions & TimeoutOptions) {
diff --git a/packages/playwright-core/src/server/browserContext.ts b/packages/playwright-core/src/server/browserContext.ts
index ff4528c3f1..91ee14bcc6 100644
--- a/packages/playwright-core/src/server/browserContext.ts
+++ b/packages/playwright-core/src/server/browserContext.ts
@@ -848,6 +848,7 @@ const defaultNewContextParamValues: channels.BrowserNewContextForReuseParams = {
hasTouch: false,
acceptDownloads: 'accept',
strictSelectors: false,
+ pierceFrames: false,
serviceWorkers: 'allow',
locale: 'en-US',
};
diff --git a/packages/playwright-core/src/server/channels.d.ts b/packages/playwright-core/src/server/channels.d.ts
index f2eec79b36..e8e7962f2b 100644
--- a/packages/playwright-core/src/server/channels.d.ts
+++ b/packages/playwright-core/src/server/channels.d.ts
@@ -429,6 +429,7 @@ export type AndroidDeviceLaunchBrowserParams = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -496,6 +497,7 @@ export type AndroidDeviceLaunchBrowserOptions = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -876,6 +878,7 @@ export type BrowserNewContextParams = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -946,6 +949,7 @@ export type BrowserNewContextOptions = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -1019,6 +1023,7 @@ export type BrowserNewContextForReuseParams = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -1089,6 +1094,7 @@ export type BrowserNewContextForReuseOptions = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -1201,6 +1207,7 @@ export type BrowserContextInitializer = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -1844,6 +1851,7 @@ export type BrowserTypeLaunchPersistentContextParams = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -1927,6 +1935,7 @@ export type BrowserTypeLaunchPersistentContextOptions = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
serviceWorkers?: 'allow' | 'block',
selectorEngines?: SelectorEngine[],
testIdAttributeName?: string,
@@ -2027,6 +2036,7 @@ export type ElectronLaunchParams = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
timezoneId?: string,
tracesDir?: string,
artifactsDir?: string,
@@ -2066,6 +2076,7 @@ export type ElectronLaunchOptions = {
},
},
strictSelectors?: boolean,
+ pierceFrames?: boolean,
timezoneId?: string,
tracesDir?: string,
artifactsDir?: string,
diff --git a/packages/playwright-core/src/server/frameSelectors.ts b/packages/playwright-core/src/server/frameSelectors.ts
index 14397b88e8..c585a12294 100644
--- a/packages/playwright-core/src/server/frameSelectors.ts
+++ b/packages/playwright-core/src/server/frameSelectors.ts
@@ -120,8 +120,9 @@ export class FrameSelectors {
return jumptToFrame;
}
- private async _resolveFramesForSelector(selector: string, options: types.StrictOptions = {}, scope?: ElementHandle): Promise<SelectorInFrame[]> {
- const { pierce, chunks } = splitSelectorByFrame(selector);
+ private async _resolveFramesForSelector(selector: string, options: types.StrictOptions & { noDefaultPierce?: boolean } = {}, scope?: ElementHandle): Promise<SelectorInFrame[]> {
+ const pierceByDefault = !!this.frame._page.browserContext._options.pierceFrames && !options.noDefaultPierce;
+ const { pierce, chunks } = splitSelectorByFrame(selector, pierceByDefault);
for (const chunk of chunks) {
visitAllSelectorParts(chunk, (part, nested) => {
if (nested && part.name === 'internal:control' && part.body === 'enter-frame') {
@@ -279,7 +280,7 @@ export class FrameSelectors {
private async _callOnSelectorInternal<Arg, R>(
selector: string,
- options: types.StrictOptions & { mainWorld?: boolean, callWithoutMatches?: boolean, scope?: ElementHandle, markTargets?: 'all' | 'first' | 'none' },
+ options: types.StrictOptions & { mainWorld?: boolean, callWithoutMatches?: boolean, scope?: ElementHandle, markTargets?: 'all' | 'first' | 'none', noDefaultPierce?: boolean },
pageFunction: MatchedElementsCallback<Arg, R>,
arg: Arg,
returnByValue: boolean,
@@ -335,7 +336,7 @@ export class FrameSelectors {
async callOnSelector<Arg, R>(
selector: string,
- options: types.StrictOptions & { mainWorld?: boolean, callWithoutMatches?: boolean, scope?: ElementHandle, markTargets?: 'all' | 'first' | 'none' },
+ options: types.StrictOptions & { mainWorld?: boolean, callWithoutMatches?: boolean, scope?: ElementHandle, markTargets?: 'all' | 'first' | 'none', noDefaultPierce?: boolean },
pageFunction: MatchedElementsCallback<Arg, R>,
arg: Arg,
): Promise<{ frame: Frame, info: SelectorInfo, result: R } | null> {
diff --git a/packages/playwright-core/src/server/frames.ts b/packages/playwright-core/src/server/frames.ts
index c629a81301..637d429e4d 100644
--- a/packages/playwright-core/src/server/frames.ts
+++ b/packages/playwright-core/src/server/frames.ts
@@ -1565,7 +1565,7 @@ export class Frame extends SdkObject<FrameEventMap> {
let missingReceived = false;
// Non-array expectations are strict (callOnSelector throws on multiple); array ones are not.
- const resolved = await progress.race(this.selectors.callOnSelector(effectiveSelector, { strict: !isArray, mainWorld, markTargets: 'all' }, async ({ injected, elements }, options) => {
+ const resolved = await progress.race(this.selectors.callOnSelector(effectiveSelector, { strict: !isArray, mainWorld, markTargets: 'all', noDefaultPierce: !selector }, async ({ injected, elements }, options) => {
const isArray = options.expression === 'to.have.count' || options.expression.endsWith('.array');
const log = isArray
? ` locator resolved to ${elements.length} element${elements.length === 1 ? '' : 's'}`
diff --git a/packages/playwright-core/src/server/page.ts b/packages/playwright-core/src/server/page.ts
index 0baec6bc59..a68b5b21b4 100644
--- a/packages/playwright-core/src/server/page.ts
+++ b/packages/playwright-core/src/server/page.ts
@@ -1111,13 +1111,13 @@ export class InitScript extends DisposableObject {
}
}
-export async function ariaSnapshotForFrame(progress: Progress, frame: frames.Frame, selector: string | undefined, options: { mode?: 'ai' | 'default', doNotRenderActive?: boolean, depth?: number, boxes?: boolean, strict?: boolean } = {}): Promise<string[]> {
+export async function ariaSnapshotForFrame(progress: Progress, frame: frames.Frame, selector: string | undefined, options: { mode?: 'ai' | 'default', doNotRenderActive?: boolean, depth?: number, boxes?: boolean, strict?: boolean, noDefaultPierce?: boolean } = {}): Promise<string[]> {
const snapshot = await frame.retryWithProgressAndTimeouts(progress, [1000, 2000, 4000, 8000], async (progress, continuePolling) => {
try {
// Note: the resolved frame might differ from the original |frame|.
// See https://developer.mozilla.org/en-US/docs/Web/API/Document/body for body/frameset explanation.
// Non-strict, because pages with nested framesets have multiple "frameset" elements.
- const resolved = await progress.race(frame.selectors.callOnSelector(selector || 'body,frameset', { strict: options.strict ?? !!selector }, ({ injected, elements }, ariaOptions) => {
+ const resolved = await progress.race(frame.selectors.callOnSelector(selector || 'body,frameset', { strict: options.strict ?? !!selector, noDefaultPierce: !selector || options.noDefaultPierce }, ({ injected, elements }, ariaOptions) => {
return injected.ariaSnapshotWithRefs(elements[0], ariaOptions);
}, {
mode: options.mode ?? 'default',
@@ -1147,7 +1147,7 @@ export async function ariaSnapshotForFrame(progress: Progress, frame: frames.Fra
// Non-strict, because child frameset documents have multiple "frameset" elements.
const frameRootSelector = `aria-ref=${ref} >> internal:control=enter-frame >> body,frameset`;
try {
- return await ariaSnapshotForFrame(progress, snapshot.resolvedFrame, frameRootSelector, { ...options, depth: childDepth, strict: false });
+ return await ariaSnapshotForFrame(progress, snapshot.resolvedFrame, frameRootSelector, { ...options, depth: childDepth, strict: false, noDefaultPierce: true });
} catch {
return [];
}
diff --git a/packages/playwright-core/src/server/recorder.ts b/packages/playwright-core/src/server/recorder.ts
index 30c13f84ba..e1461dbab7 100644
--- a/packages/playwright-core/src/server/recorder.ts
+++ b/packages/playwright-core/src/server/recorder.ts
@@ -24,7 +24,7 @@ import { isUnderTest } from '@utils/debug';
import { eventsHelper } from '@utils/eventsHelper';
import { BrowserContext } from './browserContext';
import { Debugger } from './debugger';
-import { buildFullSelector, generateFrameSelector, metadataToCallLog } from './recorder/recorderUtils';
+import { buildFullSelectorForFrame, metadataToCallLog } from './recorder/recorderUtils';
import { nullProgress, ProgressController } from './progress';
import { RecorderSignalProcessor } from './recorder/recorderSignalProcessor';
@@ -194,8 +194,8 @@ export class Recorder extends EventEmitter<RecorderEventMap> implements Instrume
});
await this._context.exposeBinding(progress, '__pw_recorderElementPicked', async ({ frame }, elementInfo: ElementInfo) => {
- const selectorChain = await generateFrameSelector(progress, frame);
- this.emit(RecorderEvent.ElementPicked, { selector: buildFullSelector(selectorChain, elementInfo.selector), ariaSnapshot: elementInfo.ariaSnapshot }, true);
+ const selector = await buildFullSelectorForFrame(progress, frame, elementInfo.selector);
+ this.emit(RecorderEvent.ElementPicked, { selector, ariaSnapshot: elementInfo.ariaSnapshot }, true);
});
await this._context.exposeBinding(progress, '__pw_recorderSetMode', async ({ frame }, mode: Mode) => {
@@ -539,28 +539,21 @@ export class Recorder extends EventEmitter<RecorderEventMap> implements Instrume
return this._params.testIdAttributeName || this._context.selectors().testIdAttributeName() || 'data-testid';
}
- private _appendContextToAction(frame: Frame, action: actions.Action, framePath: string[]): actions.ActionInContext {
- if (framePath.length && 'selector' in action)
- action.selector = buildFullSelector(framePath, action.selector);
- const actionInContext: actions.ActionInContext = {
- pageGuid: frame._page.guid,
- action,
- signals: [],
- };
- return actionInContext;
- }
-
private async _performAction(progress: Progress, frame: Frame, action: actions.PerformableAction) {
- const framePath = await generateFrameSelector(progress, frame);
- const selector = buildFullSelector(framePath, action.selector);
+ const selector = await buildFullSelectorForFrame(progress, frame, action.selector);
await performAction(progress, frame._page.mainFrame(), { ...action, selector });
}
private async _recordAction(progress: Progress, frame: Frame, action: actions.Action, preconditionSelector?: string) {
- const framePath = await generateFrameSelector(progress, frame);
if (preconditionSelector)
- this._signalProcessor.signal(frame, { name: 'expect', selector: buildFullSelector(framePath, preconditionSelector) });
- const actionInContext = this._appendContextToAction(frame, action, framePath);
+ this._signalProcessor.signal(frame, { name: 'expect', selector: await buildFullSelectorForFrame(progress, frame, preconditionSelector) });
+ if ('selector' in action)
+ action.selector = await buildFullSelectorForFrame(progress, frame, action.selector);
+ const actionInContext: actions.ActionInContext = {
+ pageGuid: frame._page.guid,
+ action,
+ signals: [],
+ };
this._signalProcessor.addAction(actionInContext);
}
diff --git a/packages/playwright-core/src/server/recorder/recorderUtils.ts b/packages/playwright-core/src/server/recorder/recorderUtils.ts
index 402bc39a73..eb18550169 100644
--- a/packages/playwright-core/src/server/recorder/recorderUtils.ts
+++ b/packages/playwright-core/src/server/recorder/recorderUtils.ts
@@ -24,10 +24,39 @@ import type { CallMetadata } from '../instrumentation';
import type { CallLog, CallLogStatus } from '@recorder/recorderTypes';
import type { Progress } from '../progress';
-export function buildFullSelector(framePath: string[], selector: string) {
+function buildFullSelector(framePath: string[], selector: string) {
return [...framePath, selector].join(' >> internal:control=enter-frame >> ');
}
+export async function buildFullSelectorForFrame(progress: Progress, frame: Frame, selector: string): Promise<string> {
+ const framePath = await generateFrameSelector(progress, frame);
+ if (!frame._page.browserContext._options.pierceFrames || !framePath.length)
+ return buildFullSelector(framePath, selector);
+
+ // Prefer the shortest selector that resolves to the target frame.
+ const result = await progress.race(raceAgainstDeadline(async () => {
+ for (let i = framePath.length; i >= 0; i--) {
+ const candidate = buildFullSelector(framePath.slice(i), selector);
+ if (await resolvesToFrame(progress, candidate, frame))
+ return candidate;
+ }
+ }, monotonicTime() + 2000));
+ if (!result.timedOut && result.result)
+ return result.result;
+
+ return 'internal:control=no-pierce-frames >> ' + buildFullSelector(framePath, selector);
+}
+
+async function resolvesToFrame(progress: Progress, selector: string, frame: Frame): Promise<boolean> {
+ try {
+ const resolved = await progress.race(frame._page.mainFrame().selectors.callOnSelector(selector, { strict: false }, () => true, {}));
+ return resolved?.frame === frame;
+ } catch (e) {
+ // Errors like "matched in multiple frames" mean the selector does not pinpoint the frame.
+ return false;
+ }
+}
+
export function metadataToCallLog(metadata: CallMetadata, status: CallLogStatus): CallLog {
const title = renderTitleForCall(metadata);
if (metadata.error)
@@ -54,7 +83,7 @@ export function metadataToCallLog(metadata: CallMetadata, status: CallLogStatus)
}
-export async function generateFrameSelector(progress: Progress, frame: Frame): Promise<string[]> {
+async function generateFrameSelector(progress: Progress, frame: Frame): Promise<string[]> {
const selectorPromises: Promise<string>[] = [];
progress.setAllowConcurrentOrNestedRaces(true);
while (frame) {
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index b1bc91b00b..177bf2afe3 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -4188,8 +4188,16 @@ export interface Page {
* await locator.click();
* ```
*
+ * @param options
*/
- pierceFrames(): FrameLocator;
+ pierceFrames(options?: {
+ /**
+ * Whether to pierce frames. Pass `false` to opt out of frame piercing enabled by the
+ * [`pierceFrames`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-pierce-frames) context
+ * option. Defaults to `true`.
+ */
+ pierce?: boolean;
+ }): FrameLocator;
/**
* **NOTE** Use locator-based [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press)
@@ -8229,8 +8237,16 @@ export interface Frame {
* await locator.click();
* ```
*
+ * @param options
*/
- pierceFrames(): FrameLocator;
+ pierceFrames(options?: {
+ /**
+ * Whether to pierce frames. Pass `false` to opt out of frame piercing enabled by the
+ * [`pierceFrames`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-pierce-frames) context
+ * option. Defaults to `true`.
+ */
+ pierce?: boolean;
+ }): FrameLocator;
/**
* **NOTE** Use locator-based [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press)
@@ -11424,6 +11440,13 @@ export interface Browser {
*/
permissions?: Array<string>;
+ /**
+ * If set to true, all selectors in this context will pierce frames by default, as if every locator was created
+ * through [page.pierceFrames([options])](https://playwright.dev/docs/api/class-page#page-pierce-frames). Defaults to
+ * `false`.
+ */
+ pierceFrames?: boolean;
+
/**
* Network proxy settings to use with this context. Defaults to none.
*/
@@ -17494,6 +17517,13 @@ export interface BrowserType<Unused = {}> {
*/
permissions?: Array<string>;
+ /**
+ * If set to true, all selectors in this context will pierce frames by default, as if every locator was created
+ * through [page.pierceFrames([options])](https://playwright.dev/docs/api/class-page#page-pierce-frames). Defaults to
+ * `false`.
+ */
+ pierceFrames?: boolean;
+
/**
* Network proxy settings.
*/
@@ -24504,6 +24534,13 @@ export interface AndroidDevice {
*/
permissions?: Array<string>;
+ /**
+ * If set to true, all selectors in this context will pierce frames by default, as if every locator was created
+ * through [page.pierceFrames([options])](https://playwright.dev/docs/api/class-page#page-pierce-frames). Defaults to
+ * `false`.
+ */
+ pierceFrames?: boolean;
+
/**
* Optional package name to launch instead of default Chrome for Android.
*/
@@ -25721,6 +25758,13 @@ export interface BrowserContextOptions {
*/
permissions?: Array<string>;
+ /**
+ * If set to true, all selectors in this context will pierce frames by default, as if every locator was created
+ * through [page.pierceFrames([options])](https://playwright.dev/docs/api/class-page#page-pierce-frames). Defaults to
+ * `false`.
+ */
+ pierceFrames?: boolean;
+
/**
* Network proxy settings to use with this context. Defaults to none.
*/
diff --git a/packages/playwright/src/index.ts b/packages/playwright/src/index.ts
index 96de0ecf35..c0ac03305b 100644
--- a/packages/playwright/src/index.ts
+++ b/packages/playwright/src/index.ts
@@ -283,6 +283,7 @@ const playwrightFixtures: Fixtures<TestFixtures, WorkerFixtures, UtilityTestFixt
locale: [({ contextOptions }, use) => use(contextOptions.locale ?? 'en-US'), { option: true, box: true }],
offline: [({ contextOptions }, use) => use(contextOptions.offline ?? false), { option: true, box: true }],
permissions: [({ contextOptions }, use) => use(contextOptions.permissions), { option: true, box: true }],
+ pierceFrames: [({ contextOptions }, use) => use(contextOptions.pierceFrames ?? false), { option: true, box: true }],
proxy: [({ contextOptions }, use) => use(contextOptions.proxy), { option: true, box: true }],
storageState: [({ contextOptions }, use) => use(contextOptions.storageState), { option: true, box: true }],
clientCertificates: [({ contextOptions }, use) => use(contextOptions.clientCertificates), { option: true, box: true }],
@@ -312,6 +313,7 @@ const playwrightFixtures: Fixtures<TestFixtures, WorkerFixtures, UtilityTestFixt
locale,
offline,
permissions,
+ pierceFrames,
proxy,
storageState,
viewport,
@@ -350,6 +352,8 @@ const playwrightFixtures: Fixtures<TestFixtures, WorkerFixtures, UtilityTestFixt
options.offline = offline;
if (permissions !== undefined)
options.permissions = permissions;
+ if (pierceFrames !== undefined)
+ options.pierceFrames = pierceFrames;
if (proxy !== undefined)
options.proxy = proxy;
if (storageState !== undefined)
diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts
index e278155a33..cfa014bbca 100644
--- a/packages/playwright/types/test.d.ts
+++ b/packages/playwright/types/test.d.ts
@@ -7586,6 +7586,26 @@ export interface PlaywrightTestOptions {
*
*/
permissions: string[] | undefined;
+ /**
+ * If set to true, all selectors in this context will pierce frames by default, as if every locator was created
+ * through [page.pierceFrames([options])](https://playwright.dev/docs/api/class-page#page-pierce-frames). Defaults to
+ * `false`.
+ *
+ * **Usage**
+ *
+ * ```js
+ * // playwright.config.ts
+ * import { defineConfig } from '@playwright/test';
+ *
+ * export default defineConfig({
+ * use: {
+ * pierceFrames: true,
+ * }
+ * });
+ * ```
+ *
+ */
+ pierceFrames: boolean;
/**
* Network proxy settings.
*
diff --git a/packages/protocol/spec/electron.yml b/packages/protocol/spec/electron.yml
index 41a659831f..5b3928fbb1 100644
--- a/packages/protocol/spec/electron.yml
+++ b/packages/protocol/spec/electron.yml
@@ -71,6 +71,7 @@ Electron:
properties:
$mixin: ShowActionsOptions
strictSelectors: boolean?
+ pierceFrames: boolean?
timezoneId: string?
tracesDir: string?
artifactsDir: string?
diff --git a/packages/protocol/spec/mixins.yml b/packages/protocol/spec/mixins.yml
index 80dcdfe8f4..2ecfcc4a75 100644
--- a/packages/protocol/spec/mixins.yml
+++ b/packages/protocol/spec/mixins.yml
@@ -201,6 +201,7 @@ ContextOptions:
properties:
$mixin: ShowActionsOptions
strictSelectors: boolean?
+ pierceFrames: boolean?
serviceWorkers:
type: enum?
literals:
diff --git a/packages/protocol/src/validator.ts b/packages/protocol/src/validator.ts
index 4a197f0d46..719f94a430 100644
--- a/packages/protocol/src/validator.ts
+++ b/packages/protocol/src/validator.ts
@@ -196,6 +196,7 @@ scheme.AndroidDeviceLaunchBrowserParams = tObject({
})),
})),
strictSelectors: tOptional(tBoolean),
+ pierceFrames: tOptional(tBoolean),
serviceWorkers: tOptional(tEnum(['allow', 'block'])),
selectorEngines: tOptional(tArray(tType('SelectorEngine'))),
testIdAttributeName: tOptional(tString),
@@ -477,6 +478,7 @@ scheme.BrowserNewContextParams = tObject({
})),
})),
strictSelectors: tOptional(tBoolean),
+ pierceFrames: tOptional(tBoolean),
serviceWorkers: tOptional(tEnum(['allow', 'block'])),
selectorEngines: tOptional(tArray(tType('SelectorEngine'))),
testIdAttributeName: tOptional(tString),
@@ -550,6 +552,7 @@ scheme.BrowserNewContextForReuseParams = tObject({
})),
})),
strictSelectors: tOptional(tBoolean),
+ pierceFrames: tOptional(tBoolean),
serviceWorkers: tOptional(tEnum(['allow', 'block'])),
selectorEngines: tOptional(tArray(tType('SelectorEngine'))),
testIdAttributeName: tOptional(tString),
@@ -645,6 +648,7 @@ scheme.BrowserContextInitializer = tObject({
})),
})),
strictSelectors: tOptional(tBoolean),
+ pierceFrames: tOptional(tBoolean),
serviceWorkers: tOptional(tEnum(['allow', 'block'])),
selectorEngines: tOptional(tArray(tType('SelectorEngine'))),
testIdAttributeName: tOptional(tString),
@@ -1041,6 +1045,7 @@ scheme.BrowserTypeLaunchPersistentContextParams = tObject({
})),
})),
strictSelectors: tOptional(tBoolean),
+ pierceFrames: tOptional(tBoolean),
serviceWorkers: tOptional(tEnum(['allow', 'block'])),
selectorEngines: tOptional(tArray(tType('SelectorEngine'))),
testIdAttributeName: tOptional(tString),
@@ -1130,6 +1135,7 @@ scheme.ElectronLaunchParams = tObject({
})),
})),
strictSelectors: tOptional(tBoolean),
+ pierceFrames: tOptional(tBoolean),
timezoneId: tOptional(tString),
tracesDir: tOptional(tString),
artifactsDir: tOptional(tString),
diff --git a/tests/library/browsercontext-pierce-frames.spec.ts b/tests/library/browsercontext-pierce-frames.spec.ts
new file mode 100644
index 0000000000..853c4a0fb1
--- /dev/null
+++ b/tests/library/browsercontext-pierce-frames.spec.ts
@@ -0,0 +1,88 @@
+/**
+ * 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 { browserTest as it, expect } from '../config/browserTest';
+
+it('should not pierce frames without the context option', async ({ page }) => {
+ await page.setContent(`<iframe srcdoc="<button>inside</button>"></iframe>`);
+ await expect.poll(() => page.frames().length).toBe(2);
+ await page.frames()[1].waitForSelector('button', { state: 'attached' });
+ await expect(page.locator('button')).toHaveCount(0);
+});
+
+it.describe('pierceFrames context option', () => {
+ it.use({
+ contextOptions: async ({ contextOptions }, use) => {
+ await use({ ...contextOptions, pierceFrames: true });
+ }
+ });
+
+ it('should pierce frames by default', async ({ page }) => {
+ await page.setContent(`<iframe srcdoc="<button onclick='window.top.__clicked = true'>Click me</button>"></iframe>`);
+ await expect(page.locator('button')).toHaveText('Click me');
+ await page.locator('button').click();
+ expect(await page.evaluate(() => (window as any).__clicked)).toBe(true);
+ });
+
+ it('should pierce nested frames by default', async ({ page }) => {
+ await page.setContent(`<iframe srcdoc="<iframe srcdoc='<div id=target>deep</div>'></iframe>"></iframe>`);
+ await expect(page.locator('#target')).toHaveText('deep');
+ });
+
+ it('should fail when elements match in multiple frames', async ({ page }) => {
+ await page.setContent(`<div>main</div><iframe srcdoc="<div>child</div>"></iframe>`);
+ await expect.poll(() => page.frames().length).toBe(2);
+ await page.frames()[1].waitForSelector('div', { state: 'attached' });
+ const error = await page.locator('div').count().catch(e => e);
+ expect(error.message).toContain('Pierce-frame mode matched elements from multiple frames');
+ });
+
+ it('should opt out with pierceFrames({ pierce: false })', async ({ page }) => {
+ await page.setContent(`<div id="main">main</div><iframe srcdoc="<div id=inner>inner</div>"></iframe>`);
+ await expect(page.locator('#inner')).toHaveText('inner');
+ await expect(page.pierceFrames({ pierce: false }).locator('#inner')).toHaveCount(0);
+ await expect(page.pierceFrames({ pierce: false }).locator('#main')).toHaveText('main');
+ });
+
+ it('should support frameLocator with the context option', async ({ page }) => {
+ await page.setContent(`<iframe srcdoc="<iframe id=target srcdoc='<button>hi</button>'></iframe><button>decoy</button>"></iframe>`);
+ await expect(page.frameLocator('#target').locator('button')).toHaveText('hi');
+ });
+
+ it('should support frameLocator chains with pierceFrames({ pierce: false })', async ({ page }) => {
+ await page.setContent(`<iframe id="direct" srcdoc="<button>direct</button>"></iframe>`);
+ await expect(page.pierceFrames({ pierce: false }).frameLocator('#direct').locator('button')).toHaveText('direct');
+ });
+
+ it('should resolve aria-ref selectors', async ({ page }) => {
+ await page.setContent(`<button>main</button><iframe srcdoc="<button>inside</button>"></iframe>`);
+ await expect.poll(() => page.frames().length).toBe(2);
+ await page.frames()[1].waitForSelector('button', { state: 'attached' });
+ const snapshot = await page.ariaSnapshot({ mode: 'ai' });
+ const mainMatch = snapshot.match(/button "main" \[ref=(.*?)\]/);
+ await expect(page.locator(`aria-ref=${mainMatch![1]}`)).toHaveText('main');
+ // Refs are unique across frames, so piercing resolves them in the right frame.
+ const insideMatch = snapshot.match(/button "inside" \[ref=(.*?)\]/);
+ expect(insideMatch![1]).toMatch(/^f\d+e\d+$/);
+ await expect(page.locator(`aria-ref=${insideMatch![1]}`)).toHaveText('inside');
+ });
+
+ it('should support ai snapshot with nested frames', async ({ page }) => {
+ await page.setContent(`<iframe srcdoc="<iframe srcdoc='<button>deep</button>'></iframe>"></iframe>`);
+ await expect.poll(() => page.frames().length).toBe(3);
+ await expect.poll(() => page.ariaSnapshot({ mode: 'ai' })).toContain('button "deep"');
+ });
+});
diff --git a/tests/library/inspector/cli-codegen-3.spec.ts b/tests/library/inspector/cli-codegen-3.spec.ts
index 4dbf8dbe99..5d3852b89c 100644
--- a/tests/library/inspector/cli-codegen-3.spec.ts
+++ b/tests/library/inspector/cli-codegen-3.spec.ts
@@ -1146,6 +1146,62 @@ await page.GetByTestId("testid").HoverAsync();`);
});
});
+test.describe('cli codegen with pierceFrames', () => {
+ test.use({
+ contextOptions: async ({ contextOptions }, use) => {
+ await use({ ...contextOptions, pierceFrames: true });
+ },
+ });
+
+ test('should generate a short selector when unique across frames', async ({ openRecorder, server }) => {
+ const { page, recorder } = await openRecorder();
+ const { frameHello2 } = await createFrameHierarchy(page, recorder, server);
+
+ const [sources] = await Promise.all([
+ recorder.waitForOutput('JavaScript', 'Hello2'),
+ frameHello2.click('text=Hello2'),
+ ]);
+
+ expect.soft(sources.get('JavaScript')!.text).toContain(`
+ await page.getByText('Hello2').click();`);
+ });
+
+ test('should prepend the frame selector to disambiguate', async ({ openRecorder, server }) => {
+ const { page, recorder } = await openRecorder();
+ await recorder.setContentAndWait(`
+ <iframe id=frame1 srcdoc="<iframe srcdoc='<button>Hello</button>'></iframe>"></iframe>
+ <iframe id=frame2 srcdoc="<iframe srcdoc='<button>Hello</button>'></iframe>"></iframe>
+ `, server.EMPTY_PAGE, 5);
+
+ // Both the bare selector and the "iframe >> enter-frame" prefix are ambiguous,
+ // so two frame selectors must be prepended to pinpoint the target frame.
+ const frame = page.mainFrame().childFrames()[0].childFrames()[0];
+ const [sources] = await Promise.all([
+ recorder.waitForOutput('JavaScript', 'click'),
+ frame.click('text=Hello'),
+ ]);
+
+ expect.soft(sources.get('JavaScript')!.text).toContain(`
+ await page.locator('#frame1').contentFrame().locator('iframe').contentFrame().getByRole('button', { name: 'Hello' }).click();`);
+ });
+
+ test('should opt out of piercing when the frame chain does not pinpoint the frame', async ({ openRecorder, server }) => {
+ const { page, recorder } = await openRecorder();
+ await recorder.setContentAndWait(`
+ <iframe id=frame1 srcdoc="<button>Hello</button><iframe srcdoc='<button>Hello</button>'></iframe>"></iframe>
+ `, server.EMPTY_PAGE, 3);
+
+ const frame = page.mainFrame().childFrames()[0];
+ const [sources] = await Promise.all([
+ recorder.waitForOutput('JavaScript', 'click'),
+ frame.click('internal:control=no-pierce-frames >> text=Hello'),
+ ]);
+
+ expect.soft(sources.get('JavaScript')!.text).toContain(`
+ await page.pierceFrames({ pierce: false }).locator('#frame1').contentFrame().getByRole('button', { name: 'Hello' }).click();`);
+ });
+});
+
async function createFrameHierarchy(page: Page, recorder: Recorder, server: TestServer) {
/*
iframe
diff --git a/tests/page/locator-pierce-frames.spec.ts b/tests/page/locator-pierce-frames.spec.ts
index 7939a48b38..fbc444bcab 100644
--- a/tests/page/locator-pierce-frames.spec.ts
+++ b/tests/page/locator-pierce-frames.spec.ts
@@ -404,6 +404,30 @@ it('should render frameLocator while piercing in the locator description', async
expect(String(page.pierceFrames().locator('section').frameLocator('iframe').getByText('foo'))).toBe(`pierceFrames().locator('section').locator('iframe').contentFrame().getByText('foo')`);
});
+it('should support the pierce option', async ({ page, server }) => {
+ await routePage(page, 'empty.html', `<iframe src="a.html"></iframe><div id="main">main</div>`);
+ await routePage(page, 'a.html', `<div id="inner">inner</div>`);
+ await page.goto(server.EMPTY_PAGE);
+ await expect(page.pierceFrames({ pierce: true }).locator('#inner')).toHaveText('inner');
+ await expect(page.pierceFrames({ pierce: false }).locator('#inner')).toHaveCount(0);
+ await expect(page.pierceFrames({ pierce: false }).locator('#main')).toHaveText('main');
+});
+
+it('should support frameLocator with pierce: false', async ({ page, server }) => {
+ await routePage(page, 'empty.html', `<iframe src="a.html"></iframe>`);
+ await routePage(page, 'a.html', `<button>inside</button>`);
+ await page.goto(server.EMPTY_PAGE);
+ await expect(page.pierceFrames({ pierce: false }).frameLocator('iframe').locator('button')).toHaveText('inside');
+});
+
+it('should render pierce: false in the locator description', async ({ page }) => {
+ expect(String(page.pierceFrames({ pierce: false }).locator('div'))).toBe(`pierceFrames({ pierce: false }).locator('div')`);
+});
+
+it('should not allow first/last/nth after pierceFrames({ pierce: false })', async ({ page }) => {
+ expect(() => page.pierceFrames({ pierce: false }).first()).toThrow('Selecting the nth frame is not allowed on the root frame locator');
+});
+
it('should not allow nth in the middle', async ({ page }) => {
const error = await page.pierceFrames().locator('div').first().locator('span').count().catch(e => e);
expect(error.message).toContain(`nth can only be the last locator when piercing frames, while querying "pierceFrames().locator('div').first().locator('span')"`);
diff --git a/tests/playwright-test/playwright.spec.ts b/tests/playwright-test/playwright.spec.ts
index d3214690c2..a9e2782db9 100644
--- a/tests/playwright-test/playwright.spec.ts
+++ b/tests/playwright-test/playwright.spec.ts
@@ -1074,3 +1074,21 @@ test('should pause test timeout while on pause', async ({ runInlineTest }) => {
}, { timeout: 3000 });
expect(result.exitCode).toBe(0);
});
+
+test('should support pierceFrames option', async ({ runInlineTest }) => {
+ const result = await runInlineTest({
+ 'playwright.config.ts': `
+ module.exports = { use: { pierceFrames: true } };
+ `,
+ 'a.test.ts': `
+ import { test, expect } from '@playwright/test';
+ test('pierces frames by default', async ({ page }) => {
+ await page.setContent('<iframe srcdoc="<button>inside</button>"></iframe>');
+ await expect(page.locator('button')).toHaveText('inside');
+ await expect(page.pierceFrames({ pierce: false }).locator('button')).toHaveCount(0);
+ });
+ `,
+ });
+ expect(result.exitCode).toBe(0);
+ expect(result.passed).toBe(1);
+});
diff --git a/utils/generate_types/overrides-test.d.ts b/utils/generate_types/overrides-test.d.ts
index 1644057d89..8244dc4037 100644
--- a/utils/generate_types/overrides-test.d.ts
+++ b/utils/generate_types/overrides-test.d.ts
@@ -290,6 +290,7 @@ export interface PlaywrightTestOptions {
locale: string | undefined;
offline: boolean;
permissions: string[] | undefined;
+ pierceFrames: boolean;
proxy: Proxy | undefined;
storageState: StorageState | undefined;
timezoneId: string | undefined;