Skip to content

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.

ts
  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 ​

ts
  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 ​

ts
  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.

Unreleased development documentation from main. APIs and prototypes are labelled separately.