Frames and shadow DOM
Enter iframes with a frame locator, then keep the same role and label vocabulary. Locators cross open shadow roots automatically.
- Iframes Enter a frame and keep your vocabulary
- Shadow DOM Web components need no special selector
- Navigation inside A frame has its own lifecycle
Iframes
Enter a frame and keep your vocabulary
A frame locator returns locators. Payment widgets, embedded editors, and consent banners are addressed with the same roles and labels as the host page.
Interact inside an iframe →$page->frameLocator('#checkout')
->getByLabel('Card number')
->fill('4242 4242 4242 4242');
Shadow DOM
Web components need no special selector
Locators cross open shadow roots on their own, so custom elements use the same locator methods as ordinary page markup.
Pierce shadow DOM →
Navigation inside
A frame has its own lifecycle
Frames load, navigate, and detach independently of the page. Each one can be awaited on its own terms rather than through a global sleep.
Navigation and waiting →
Next step
Move from the tour to working code.
Choose the explanation, recipe, or runnable example that matches what you need next.
Common questions
Before you wire it into a suite.
Do iframe locators work like page locators?
Yes. Start with a frame locator, then use role, label, text, and filters inside the frame just like you would on the page.
Can locators pierce Shadow DOM?
Open shadow roots are handled by locators. Closed shadow roots are intentionally not reachable and need product-level test hooks or public behavior assertions.
Why do frames make tests flaky?
Frames have their own lifecycle. Wait for the frame or target element directly instead of assuming the outer page navigation means the embedded content is ready.