Multiple Pages, portals and frames
Available since @pomeranian/core@Unreleased.
Keep one page-object tree per Playwright Page. If using rooted trees, create a separate application-root instance for each tab or popup. Roots are per-instance anchors, not global singleton Pages. Coordinate between trees in the test or fixture; a standalone object needs no root wrapper.
const secondPage = await context.newPage();
try {
await page.setContent("<h1>First tab</h1>");
await secondPage.setContent("<h1>Second tab</h1>");
const first = DomPageObject.create(page, "h1");
const second = DomPageObject.create(secondPage, "h1");
expect(first.root).toBeNull();
expect(second.root).toBeNull();
await expect(first.locator).toHaveText("First tab");
await expect(second.locator).toHaveText("Second tab");
} finally {
await secondPage.close();
}A popup can be obtained with page.waitForEvent("popup") around the action that opens it, then supplied to its own tree's inherited factory. A fixture can similarly supply a separate designated root. A Locator from another tab fails ownership validation even when the tabs share a browser context.
Global and portaled queries
await page.setContent("<main><button>Open</button></main><dialog open>Global dialog</dialog>");
const panel = DomPageObject.create(page, "main");
const button = DomPageObject.create(panel, ({ page, scope }) =>
(scope ?? page).getByRole("button"),
);
const dialog = DomPageObject.create(panel, ({ page }) => page.getByRole("dialog"));
await expect(button.locator).toHaveText("Open");
await expect(dialog.locator).toHaveText("Global dialog");The factory's scope is the nearest DOM ancestor, forwarded through groups. Use (scope ?? page) for scoped queries and page deliberately for a global dialog, dropdown or toast. Supplied Locators also retain their own query rather than composing automatically with a structural parent.
Same-Page frames
await page.setContent('<iframe srcdoc="<button>Inside frame</button>"></iframe>');
const input = page.frameLocator("iframe").getByRole("button");
const button = DomPageObject.create(page, input);
expect(button.locator).toBe(input);
await expect(button.locator).toHaveText("Inside frame");A frame Locator whose public page() is the associated Page is accepted. This is a Page ownership guarantee, not a guarantee that every combination of cross-frame queries is valid. Playwright enforces its frame and operation rules. For CSS, :scope refers to the inherited DOM scope; explicit sibling selectors may leave its subtree.