zebbern/claude-code-guide / skills/playwright/core
playwright-core
VerifiedBattle-tested Playwright patterns for E2E, API, component, visual, accessibility, and security testing. Covers locators, assertions, fixtures, network mocking, auth flows, debugging, and framework recipes for React, Next.js, Vue, and Angular. TypeScript and JavaScript.
iframes-and-shadow-dom.md
View on GitHub# Iframes and Shadow DOM
> **When to use**: When your application embeds content in `<iframe>` elements (payment widgets, third-party embeds, legacy modules) or uses Web Components with Shadow DOM (design systems, custom elements, Salesforce Lightning).
> **Prerequisites**: [core/locators.md](locators.md), [core/assertions-and-waiting.md](assertions-and-waiting.md)
## Quick Reference
```typescript
// Iframes — use frameLocator to reach inside
const frame = page.frameLocator('iframe[title="Payment"]')
await frame.getByLabel("Card number").fill("4242424242424242")
// Nested iframes — chain frameLocator calls
const inner = page.frameLocator("#outer").frameLocator("#inner")
await inner.getByRole("button", { name: "Submit" }).click()
// Shadow DOM — Playwright pierces open shadow roots automatically
await page.getByRole("button", { name: "Toggle" }).click() // auto-pierces
await page.locator("my-component").getByText("Hello").click() // auto-pierces
```
## Patterns
### Basic iframe Interaction with `frameLocator()`
**Use when**: You need to interact with content inside an `<iframe>` -- payment forms, embedded editors, captchas, third-party widgets.
**Avoid when**: The content is in the main frame. Never use `frameLocator` for Shadow DOM.
`frameLocator()` returns a locator-like object scoped to the iframe's document. All standard locator methods work inside it.
**TypeScript**
```typescript
import { test, expect } from "@playwright/test"
test("complete payment inside Stripe iframe", async ({ page }) => {
await page.goto("/checkout")
// Locate the iframe by its title, name, or a CSS selector
const paymentFrame = page.frameLocator('iframe[title="Secure payment"]')
// Use normal locators inside the frame
await paymentFrame.getByLabel("Card number").fill("4242424242424242")
await paymentFrame.getByLabel("Expiry").fill("12/28")
await paymentFrame.getByLabel("CVC").fill("123")
await paymentFrame.getByRole("button", { name: "Pay" }).click()
// Assertion on content inside the iframe
await expect(paymentFrame.getByText("Payment successful")).toBeVisible()
// Assertion on the parent page (outside the iframe)
await expect(page.getByRole("heading", { name: "Order confirmed" })).toBeVisible()
})
```
**JavaScript**
```javascript
const { test, expect } = require("@playwright/test")
test("complete payment inside Stripe iframe", async ({ page }) => {
await page.goto("/checkout")
const paymentFrame = page.frameLocator('iframe[title="Secure payment"]')
await paymentFrame.getByLabel("Card number").fill("4242424242424242")
await paymentFrame.getByLabel("Expiry").fill("12/28")
await paymentFrame.getByLabel("CVC").fill("123")
await paymentFrame.getByRole("button", { name: "Pay" }).click()
await expect(paymentFrame.getByText("Payment successful")).toBeVisible()
await expect(page.getByRole("heading", { name: "Order confirmed" })).toBeVisible()
})
```
### Selecting the Right iframe
**Use when**: Multiple iframes exist on the page or the iframe has no obvious identifier.
**Avoid when**: There is only one iframe and a simple `page.frameLocator('iframe')` works.
**TypeScript**
```typescript
import { test, expect } from "@playwright/test"
test("interact with the correct iframe among many", async ({ page }) => {
await page.goto("/dashboard")
// By title attribute (best — accessible and stable)
const chatFrame = page.frameLocator('iframe[title="Live chat"]')
// By name attribute
const reportFrame = page.frameLocator('iframe[name="analytics-report"]')
// By src URL pattern
const adFrame = page.frameLocator('iframe[src*="ads.example.com"]')
// By index — when nothing else works (0-indexed)
const thirdFrame = page.frameLocator("iframe").nth(2)
// By parent container — scope to a section first
const sidebar = page.getByRole("complementary")
const sidebarFrame = sidebar.frameLocator("iframe")
await chatFrame.getByRole("textbox", { name: "Message" }).fill("Help")
await expect(reportFrame.getByRole("heading")).toBeVisible()
})
```
**JavaScript**
```javascript
const { test, expect } = require("@playwright/test")
test("interact with the correct iframe among many", async ({ page }) => {
await page.goto("/dashboard")
const chatFrame = page.frameLocator('iframe[title="Live chat"]')
const reportFrame = page.frameLocator('iframe[name="analytics-report"]')
const adFrame = page.frameLocator('iframe[src*="ads.example.com"]')
const thirdFrame = page.frameLocator("iframe").nth(2)
await chatFrame.getByRole("textbox", { name: "Message" }).fill("Help")
await expect(reportFrame.getByRole("heading")).toBeVisible()
})
```
### Nested Iframes
**Use when**: An iframe contains another iframe (common in complex widget hierarchies, ad containers, or embedded third-party tools).
**Avoid when**: There is only one level of iframe nesting.
**TypeScript**
```typescript
import { test, expect } from "@playwright/test"
test("interact with deeply nested iframe content", async ({ page }) => {
await page.goto("/embed-page")
// Chain frameLocator calls for each level of nesting
const outerFrame = page.frameLocator("#widget-container")
const innerFrame = outerFrame.frameLocator("#payment-form")
await innerFrame.getByLabel("Amount").fill("99.99")
await innerFrame.getByRole("button", { name: "Confirm" }).click()
// Three levels deep
const deepFrame = page.frameLocator("#level-1").frameLocator("#level-2").frameLocator("#level-3")
await expect(deepFrame.getByText("Success")).toBeVisible()
})
```
**JavaScript**
```javascript
const { test, expect } = require("@playwright/test")
test("interact with deeply nested iframe content", async ({ page }) => {
await page.goto("/embed-page")
const outerFrame = page.frameLocator("#widget-container")
const innerFrame = outerFrame.frameLocator("#payment-form")
await innerFrame.getByLabel("Amount").fill("99.99")
await innerFrame.getByRole("button", { name: "Confirm" }).click()
const deepFrame = page.frameLocator("#level-1").frameLocator("#level-2").frameLocator("#level-3")
await expect(deepFrame.getByText("Success")).toBeVisible()
})
```
### Cross-Origin Iframes
**Use when**: The iframe loads content from a different domain (payment providers, OAuth flows, third-party embeds).
**Avoid when**: The iframe is same-origin.
Playwright handles cross-origin iframes transparently. `frameLocator()` works regardless of origin. No special configuration is needed.
**TypeScript**
```typescript
import { test, expect } from "@playwright/test"
test("complete OAuth login in cross-origin iframe", async ({ page }) => {
await page.goto("/login")
await page.getByRole("button", { name: "Sign in with Google" }).click()
// The OAuth provider renders in a cross-origin iframe or popup
// For iframes:
const oauthFrame = page.frameLocator('iframe[src*="accounts.google.com"]')
await oauthFrame.getByLabel("Email").fill("user@gmail.com")
await oauthFrame.getByRole("button", { name: "Next" }).click()
})
test("cross-origin payment widget", async ({ page }) => {
await page.goto("/checkout")
// Stripe, PayPal, etc. load in cross-origin iframes
const stripeFrame = page.frameLocator('iframe[src*="js.stripe.com"]')
// All locator methods work across origins
await stripeFrame.getByLabel("Card number").fill("4242424242424242")
await stripeFrame.getByLabel("MM / YY").fill("12 / 28")
await stripeFrame.getByLabel("CVC").fill("123")
})
```
**JavaScript**
```javascript
const { test, expect } = require("@playwright/test")
test("cross-origin payment widget", async ({ page }) => {
await page.goto("/checkout")
const stripeFrame = page.frameLocator('iframe[src*="js.stripe.com"]')
await stripeFrame.getByLabel("Card number").fill("4242424242424242")
await stripeFrame.getByLabel("MM / YY").fill("12 / 28")
await stripeFrame.getByLabel("CVC").fill("123")
})
```
### Using the Frame API for Advanced Scenarios
**Use when**: You need to access the frame's URL, wait for frame navigation, or run `evaluate` inside the frame.
**Avoid when**: `frameLocator()` covers your needs. It is simpler and auto-waits.
**TypeScript**
```typescript
import { test, expect } from "@playwright/test"
test("use Frame API for URL checks and evaluate", async ({ page }) => {
await page.goto("/dashboard")
// Get the Frame object (not FrameLocator)
const frame = page.frame({ url: /analytics\.example\.com/ })
expect(frame).not.toBeNull()
// Check the frame's URL
expect(frame!.url()).toContain("analytics.example.com")
// Run JavaScript inside the frame
const title = await frame!.evaluate(() => document.title)
expect(title).toBe("Analytics Dashboard")
// Wait for a frame to navigate
const frameNavPromise = page.waitForEvent("framenavigated", {
predicate: (f) => f.url().includes("/reports"),
})
await page.frameLocator('iframe[name="analytics"]').getByRole("link", { name: "Reports" }).click()
await frameNavPromise
})
```
**JavaScript**
```javascript
const { test, expect } = require("@playwright/test")
test("use Frame API for URL checks and evaluate", async ({ page }) => {
await page.goto("/dashboard")
const frame = page.frame({ url: /analytics\.example\.com/ })
expect(frame).not.toBeNull()
expect(frame.url()).toContain("analytics.example.com")
const title = await frame.evaluate(() => document.title)
expect(title).toBe("Analytics Dashboard")
})
```
### Shadow DOM -- Automatic Piercing
**Use when**: Your app uses Web Components with open Shadow DOM. This is the default behavior -- no special configuration needed.
**Avoid when**: The shadow root is closed (see workaround below).
Playwright's `locator()`, `getByRole()`, `getByText()`, and all semantic locators pierce open Shadow DOM by default.
**TypeScript**
```typescript
import { test, expect } from "@playwright/test"
test("interact with web components using Shadow DOM", async ({ page }) => {
await page.goto("/design-system-demo")
// getByRole pierces shadow roots automatically
await page.getByRole("button", { name: "Open menu" }).click()
// locator() with CSS also pierces
await page.locator("my-dropdown").getByRole("option", { name: "Settings" }).click()
// Nested web components — each shadow root is pierced
await page
.locator("my-app")
.locator("my-sidebar")
.getByRole("link", { name: "Dashboard" })
.click()
// Assertions pierce too
await expect(page.locator("my-card").getByText("Welcome back")).toBeVisible()
// getByTestId pierces shadow DOM
await expect(page.getByTestId("user-avatar")).toBeVisible()
})
```
**JavaScript**
```javascript
const { test, expect } = require("@playwright/test")
test("interact with web components using Shadow DOM", async ({ page }) => {
await page.goto("/design-system-demo")
await page.getByRole("button", { name: "Open menu" }).click()
await page.locator("my-dropdown").getByRole("option", { name: "Settings" }).click()
await page
.locator("my-app")
.locator("my-sidebar")
.getByRole("link", { name: "Dashboard" })
.click()
await expect(page.locator("my-card").getByText("Welcome back")).toBeVisible()
})
```
### Closed Shadow DOM Workaround
**Use when**: A third-party component uses `attachShadow({ mode: 'closed' })`, which blocks Playwright's auto-piercing.
**Avoid when**: The shadow root is open (the default). Auto-piercing handles open roots.
Override `attachShadow` before the page loads to force open mode.
**TypeScript**
```typescript
import { test, expect } from "@playwright/test"
test("access closed shadow DOM by forcing open mode", async ({ page }) => {
// Intercept attachShadow before the page scripts run
await page.addInitScript(() => {
const originalAttachShadow = Element.prototype.attachShadow
Element.prototype.attachShadow = function (init: ShadowRootInit) {
return originalAttachShadow.call(this, { ...init, mode: "open" })
}
})
await page.goto("/third-party-widget")
// Now the previously closed shadow root is accessible
await page.locator("closed-component").getByRole("button", { name: "Action" }).click()
await expect(page.locator("closed-component").getByText("Done")).toBeVisible()
})
```
**JavaScript**
```javascript
const { test, expect } = require("@playwright/test")
test("access closed shadow DOM by forcing open mode", async ({ page }) => {
await page.addInitScript(() => {
const originalAttachShadow = Element.prototype.attachShadow
Element.prototype.attachShadow = function (init) {
return originalAttachShadow.call(this, { ...init, mode: "open" })
}
})
await page.goto("/third-party-widget")
await page.locator("closed-component").getByRole("button", { name: "Action" }).click()
await expect(page.locator("closed-component").getByText("Done")).toBeVisible()
})
```
### Web Components with Slots and Custom Events
**Use when**: Testing web components that use `<slot>` for content projection or dispatch custom events.
**Avoid when**: The component does not use slots or custom events.
**TypeScript**
```typescript
import { test, expect } from "@playwright/test"
test("slotted content is visible through web component", async ({ page }) => {
await page.goto("/components-demo")
// Content projected into a <slot> is in the light DOM (not shadow)
// Playwright sees it at its original location
const card = page.locator("my-card")
await expect(card.getByRole("heading", { name: "Product Title" })).toBeVisible()
await expect(card.getByText("Product description here")).toBeVisible()
})
test("listen for custom events from web components", async ({ page }) => {
await page.goto("/components-demo")
// Set up a listener for a custom event
const eventPromise = page.evaluate(() => {
return new Promise<{ detail: unknown }>((resolve) => {
document
.querySelector("my-color-picker")!
.addEventListener(
"color-change",
(e: Event) => resolve({ detail: (e as CustomEvent).detail }),
{ once: true }
)
})
})
// Trigger the event by interacting with the component
await page.locator("my-color-picker").getByRole("button", { name: "Red" }).click()
const event = await eventPromise
expect(event.detail).toEqual({ color: "#ff0000" })
})
```
**JavaScript**
```javascript
const { test, expect } = require("@playwright/test")
test("slotted content is visible through web component", async ({ page }) => {
await page.goto("/components-demo")
const card = page.locator("my-card")
await expect(card.getByRole("heading", { name: "Product Title" })).toBeVisible()
await expect(card.getByText("Product description here")).toBeVisible()
})
test("listen for custom events from web components", async ({ page }) => {
await page.goto("/components-demo")
const eventPromise = page.evaluate(() => {
return new Promise((resolve) => {
document
.querySelector("my-color-picker")
.addEventListener("color-change", (e) => resolve({ detail: e.detail }), { once: true })
})
})
await page.locator("my-color-picker").getByRole("button", { name: "Red" }).click()
const event = await eventPromise
expect(event.detail).toEqual({ color: "#ff0000" })
})
```
## Decision Guide
| Scenario | Approach | Why |
| ------------------------------------ | ------------------------------------------------- | ------------------------------------------------- |
| Content inside `<iframe>` | `page.frameLocator('selector')` | Returns a scoped locator for the iframe document |
| Multiple iframes on page | Use `title`, `name`, or `src` attribute selectors | More stable than index-based `nth()` |
| Nested iframes | Chain `frameLocator().frameLocator()` | Each call scopes one level deeper |
| Cross-origin iframe | Same as any iframe -- `frameLocator()` | Playwright handles cross-origin transparently |
| URL check or `evaluate` inside frame | `page.frame({ url })` (Frame API) | FrameLocator does not expose URL or evaluate |
| Open Shadow DOM | Standard locators -- no changes needed | Playwright pierces open shadow roots by default |
| Closed Shadow DOM | `addInitScript` to override `attachShadow` | Forces closed roots to open before page loads |
| Slotted content in Web Components | Locate within the custom element tag | Slotted content is light DOM, accessible normally |
| Non-piercing CSS (rare) | `css:light=selector` | Explicitly restricts to light DOM only |
## Anti-Patterns
| Don't Do This | Problem | Do This Instead |
| ------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------ |
| `page.locator('#element-inside-iframe')` | Locators do not cross iframe boundaries | `page.frameLocator('iframe').locator('#element')` |
| `page.frameLocator('iframe').frameLocator('iframe')` without specific selectors | Matches wrong iframes when multiple exist | Use specific attributes: `frameLocator('iframe[title="..."]')` |
| `page.$('>>> .shadow-element')` | `>>>` piercing selector is not standard in Playwright | Use `page.locator('host-element').getByRole(...)` -- auto-piercing works |
| Using `contentFrame()` on a locator for routine interactions | More complex API than `frameLocator` for simple cases | Use `frameLocator()` -- simpler, auto-waits |
| `page.evaluate` to query inside shadow DOM | Bypasses Playwright's auto-waiting and retry logic | Use `page.locator()` which auto-pierces |
| Hardcoding iframe index (`nth(0)`) when attributes are available | Index changes when iframes are added/removed | Use `title`, `name`, or `src` pattern |
## Troubleshooting
| Symptom | Cause | Fix |
| ------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Locator times out inside iframe | Using `page.locator()` instead of `frameLocator().locator()` | Switch to `page.frameLocator('selector').locator(...)` |
| `frameLocator` returns no elements | Iframe not yet loaded when locator resolves | `frameLocator` auto-waits; check that the iframe selector matches |
| Cross-origin iframe content inaccessible | Rare: specific browser security policy | Playwright handles cross-origin; ensure you are not using `page.frame()` with wrong URL |
| Shadow DOM element not found with `locator()` | Shadow root is closed (`mode: 'closed'`) | Use `addInitScript` to override `attachShadow` to force open mode |
| `getByRole` finds elements from wrong shadow root | Multiple web components have elements with the same role and name | Scope the locator: `page.locator('my-specific-component').getByRole(...)` |
| Slotted content not found | Searching inside shadow root instead of light DOM | Slotted content stays in light DOM; locate it through the parent custom element |
| `frame.evaluate()` returns null | Frame navigated away or was removed from DOM | Re-acquire the frame reference after navigation |
## Related
- [core/locators.md](locators.md) -- locator fundamentals including frame and shadow DOM basics
- [core/browser-apis.md](browser-apis.md) -- testing browser APIs that may live inside iframes
- [core/canvas-and-webgl.md](canvas-and-webgl.md) -- canvas elements inside iframes or web components
- [core/debugging.md](debugging.md) -- using Playwright Inspector to identify iframe boundaries and shadow roots
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |