Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
feat(selectors): add pierceFrames context option (#42033)
Dmitry Gozmand7775efb41c8
diff --git a/docs/src/api/class-frame.md b/docs/src/api/class-frame.mdindex 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.mdindex 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.mdindex 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 specifieNetwork 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.mdindex 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.10diff --git a/packages/isomorphic/locatorGenerators.ts b/packages/isomorphic/locatorGenerators.tsindex 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, isFramcontinue;}}- 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.tsindex 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, cchunk.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.tsindex 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.tsindex 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.tsindex 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 './eimport { 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.Frreturn 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.tsindex 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.tsindex 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.Pagereturn 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 Instrumereturn 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.tsindex 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.tsindex 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.tsindex 96de0ecf35..c0ac03305b 100644--- a/packages/playwright/src/index.ts+++ b/packages/playwright/src/index.ts@@ -283,6 +283,7 @@ const playwrightFixtures: Fixtures<TestFixtures, WorkerFixtures, UtilityTestFixtlocale: [({ 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, UtilityTestFixtlocale,offline,permissions,+ pierceFrames,proxy,storageState,viewport,@@ -350,6 +352,8 @@ const playwrightFixtures: Fixtures<TestFixtures, WorkerFixtures, UtilityTestFixtoptions.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.tsindex 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.ymlindex 41a659831f..5b3928fbb1 100644--- a/packages/protocol/spec/electron.yml+++ b/packages/protocol/spec/electron.yml@@ -71,6 +71,7 @@ Electron:properties:$mixin: ShowActionsOptionsstrictSelectors: boolean?+ pierceFrames: boolean?timezoneId: string?tracesDir: string?artifactsDir: string?diff --git a/packages/protocol/spec/mixins.yml b/packages/protocol/spec/mixins.ymlindex 80dcdfe8f4..2ecfcc4a75 100644--- a/packages/protocol/spec/mixins.yml+++ b/packages/protocol/spec/mixins.yml@@ -201,6 +201,7 @@ ContextOptions:properties:$mixin: ShowActionsOptionsstrictSelectors: boolean?+ pierceFrames: boolean?serviceWorkers:type: enum?literals:diff --git a/packages/protocol/src/validator.ts b/packages/protocol/src/validator.tsindex 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.tsnew file mode 100644index 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.tsindex 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) {/*iframediff --git a/tests/page/locator-pierce-frames.spec.ts b/tests/page/locator-pierce-frames.spec.tsindex 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', asyncexpect(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.tsindex 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.tsindex 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;