Real applications do not fit into one flat document. A payment form comes in an iframe from Stripe, a map widget from a third-party service, an OAuth screen opens on someone else's domain, and a design system hides its markup inside web components and the shadow DOM. A test that can only click elements of the main page stumbles on exactly the most expensive scenarios - payment and sign-in. So professional E2E must be able to step across these boundaries.

It is worth starting with how an iframe differs from the shadow DOM, because the approaches differ. An iframe is a nested separate document with its own tree, often from another domain; an ordinary locator of the main page does not reach into it. The shadow DOM is an encapsulated subtree inside the same document, used by web components; it is not a separate document but a hidden part of the current one. The first requires an explicit entry, the second Playwright mostly handles by itself.

For an iframe there is frameLocator. page.frameLocator('iframe[title="Card payment"]') returns an object inside which the same semantic locators work as on the page: getByRole, getByLabel, getByText. That is, inside the frame you describe elements exactly as outside - the only difference is that you first explicitly state which frame to enter. Nested frames are addressed with a chain of frameLocator, step by step.

The frame itself is addressed by a stable trait, not by an ordinal number. The title attribute, the name or the frame's accessible name will survive a rearrangement of widgets on the page, whereas an nth-child over the list of iframes breaks at any change of surroundings. This is the same user-contract principle as with ordinary locators: describe the frame by its stable meaning, not by its position in the markup.

It helps to see both techniques side by side once - entering a frame and working with a web component - so as not to confuse them while writing a scenario. Below is a click on a button inside a payment iframe and access to an element inside a custom component; you return to this pair when a main-page locator hits the boundary of a nested document or encapsulation.

With the shadow DOM the situation is simpler, and this is an important practical relief. Playwright's semantic locators by role and text pierce the open shadow DOM by default: getByRole and getByText find an element inside a web component just as in ordinary markup, with no separate API. For web-component design systems this means tests are written the usual way, and encapsulation stays an implementation detail the scenario need not know about.