{"record":{"id":"dfc166c3688f9f2f","repo":"microsoft/playwright","slug":"composite-locators-are-not-supported-with-piercing","errorCode":null,"errorMessage":"Composite locators are not supported with piercing frames, while querying \"${locator}\"","messagePattern":"Composite locators are not supported with piercing frames, while querying \"(.+?)\"","errorType":"exception","errorClass":"InvalidSelectorError","httpStatus":null,"severity":"error","filePath":"packages/playwright-core/src/server/frameSelectors.ts","lineNumber":146,"sourceCode":"    const frameSeq = +match[1];\n    const jumptToFrame = this.frame._page.frameManager.frames().find(frame => frame.seq === frameSeq);\n    if (!jumptToFrame)\n      throw new InvalidSelectorError(`Invalid frame in aria-ref selector \"${selector}\"`);\n    return jumptToFrame;\n  }\n\n  async resolveFramesForSelector(selector: string, options: types.StrictOptions & { anyFrame?: boolean } = {}, scope?: ElementHandle): Promise<SelectorInFrame[]> {\n    const { anyFrame, chunks } = splitSelectorByFrame(selector);\n    for (const chunk of chunks) {\n      visitAllSelectorParts(chunk, (part, nested) => {\n        if (nested && part.name === 'internal:control' && part.body === 'enter-frame') {\n          const locator = asLocator(this.frame._page.browserContext._browser.sdkLanguage(), selector);\n          throw new InvalidSelectorError(`Frame locators are not allowed inside composite locators, while querying \"${locator}\"`);\n        }\n        if (nested && part.name === 'internal:control' && part.body === 'any-frame') {\n          const locator = asLocator(this.frame._page.browserContext._browser.sdkLanguage(), selector);\n          throw new InvalidSelectorError(`frameLocator() is not allowed inside composite locators, while querying \"${locator}\"`);\n        }\n      });\n    }\n\n    if (!anyFrame && !options.anyFrame) {\n      const result = await this._resolveChainedSelector(this.frame, selector, options, chunks, scope, false /* noStall */);\n      return result ? [result] : [];\n    }\n\n    const result: SelectorInFrame[] = [];\n    const seenFrames = new Set<Frame>();\n    for (const startFrame of await this._anyFrameCandidates(scope)) {\n      const resolved = await this._resolveChainedSelector(startFrame, selector, options, chunks, startFrame === this.frame ? scope : undefined, startFrame !== this.frame /* noStall */);\n      // Different starting frames may resolve into the same frame, e.g. with an aria-ref selector.\n      if (!resolved || seenFrames.has(resolved.frame))\n        continue;\n      seenFrames.add(resolved.frame);\n      result.push(resolved);\n    }","sourceCodeStart":128,"sourceCodeEnd":164,"githubUrl":"https://github.com/microsoft/playwright/blob/500c9c822ce7664539a4c8a88810048dfe090c3b/packages/playwright-core/src/server/frameSelectors.ts#L128-L164","documentation":"When pierce-frames mode is active (browserContext option pierceFrames, or internal piercing), composite (multi-part chained) locators are not supported. If a nested selector part is encountered while pierce is on, InvalidSelectorError is thrown.","triggerScenarios":"Enabling pierceFrames on a BrowserContext (or using piercing selectors) and then issuing a composite/chained locator that has nested parts, which the piercing resolver cannot decompose.","commonSituations":"Turning on pierceFrames experimentally and reusing existing composite locators; frameworks that auto-generate chained selectors; refactoring tests without re-validating against piercing.","solutions":["Disable pierceFrames if you need composite locators, or","Simplify the locator to a single-part selector when piercing is enabled.","Refactor the query into a frameLocator chain that does not produce nested composite parts."],"exampleFix":"// before\nconst ctx = await browser.newContext({ pierceFrames: true });\nawait page.locator('div >> button').click(); // composite under pierce -> throws\n// after\nawait page.locator('button').click();","handlingStrategy":"validation","validationCode":"// Avoid composite (>>) selectors when piercing is on\nconst isPiercing = !!context.options()?.pierceFrames;\nif (isPiercing && sel.includes('>>')) throw new Error('no composite under pierce');","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Decide between pierceFrames and composite locators up front; do not mix.","Document the piercing mode in test fixtures so contributors use single-part locators."],"tags":["selector","pierce-frames","validation"],"backgroundTag":null,"analyzedSha":"500c9c822ce7664539a4c8a88810048dfe090c3b","analyzedAt":"2026-08-12T07:26:36.950Z","contentChangedAt":"2026-08-12T07:26:36.950Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}