Alerts & Windows

JavaScript dialogs: alert, confirm, prompt

Native dialogs pause the page until they are handled, so a test that triggers one must deal with it. OrbitTest exposes the dialog text and gives you accept/dismiss controls:

await orbit.click("Trigger Alert");

expect(await orbit.alertText()).toBe("hello");
await orbit.acceptAlert();

// Prompt dialogs: provide the typed answer
await orbit.click("Ask name");
await orbit.acceptAlert({ promptText: "Abhay" });

// Confirm dialogs: choose Cancel
await orbit.click("Delete");
await orbit.dismissAlert();

Prompts and confirms.

When you need the full details, waitForAlert() returns the dialog’s type, message, url, and whether it was handled.

Browser notification permissions

Notification behavior depends on permission state, and a permission prompt in the middle of a test is a flake waiting to happen. Set the state deliberately in your setup:

await orbit.open("https://example.com");

await orbit.grantNotifications();
expect(await orbit.getNotificationPermission()).toBe("granted");

await orbit.denyNotifications("https://example.com");
expect(await orbit.getNotificationPermission()).toBe("denied");

await orbit.resetNotificationPermission();

Pass an origin string (or { origin }) to target a specific site; otherwise the current origin is used.

Windows, tabs, and popups

When a click opens a new tab or window, nothing switches automatically; you capture the new window explicitly, which keeps multi-window tests predictable:

const windows = await orbit.listWindows();
const main = windows.find(w => w.active);

await orbit.click("Open details");
const popup = await orbit.waitForWindow({ switchTo: true });

expect(await orbit.hasText("Details")).toBe(true);

await orbit.switchToWindow(main.id);   // back to the original
await orbit.closeWindow(popup.id);

The standard popup pattern: trigger, wait, switch, assert, return.

switchToWindow() and closeWindow() are flexible about how you identify a window. They accept:

An index: switchToWindow(0) for the first window.
A target id from listWindows() or waitForWindow().
URL or title text: switchToWindow("Invoice").
A regular expression or a predicate function for anything fancier.

newWindow(url) opens a fresh tab and switches to it by default; pass { switchTo: false } to open it in the background.

Patterns that keep these tests stable

Trigger first, then wait: click the thing that opens the popup, then waitForWindow(). Registering interest after the window opened is fine; assuming it opened instantly is not.
Always switch back. A test that ends focused on a popup leaves the next step of the same test in a confusing place. Keep a handle to the main window.
Close what you open. Leaked windows consume memory across a long suite.
For dialogs, assert the message text. “Are you sure you want to delete 3 items?” is product behavior worth checking, not just an obstacle to click through.

Frequently asked questions

My test hangs as soon as a dialog appears. Why?

A native dialog blocks the page, and the test is waiting for something behind it. Handle the dialog (acceptAlert/dismissAlert) right after the action that triggers it.

Can I test a flow that spans two windows side by side?

Yes. Keep both window handles and switchToWindow() between them as the flow alternates. Each switch makes the chosen window the target of subsequent orbit calls.

OrbitTest controls the browser session, and windows opened by your test through real clicks are tracked through CDP, so popup handling works without fighting a blocker.

Working with Elements — Clicking, typing, reading text with three text readers, waiting for state, and iterating collections with orbit.all().
Frames & Shadow DOM — Scope tests into iframes and open or closed shadow roots with orbit.frame() and orbit.shadow(), including nested paths.
Browser Storage — Cookies, localStorage, sessionStorage, saved login sessions with saveSession/loadSession, and session health checks.
Visual Automation — Test canvas, WebGL, and pixel-rendered UIs with coordinate actions, snapshots, pixel assertions, and color search.