activePopup

Switch to a popup and make it the active page. Default timeout is 0 (instant) — the popup must already exist unless you pass a timeout.

Signature


const activated = await utils.activePopup(options?)

Return Value

Type	Description
`Promise<boolean>`	`true` when a matching popup was found and activated, `false` when no popup matched before timeout

Parameters

Param	Type	Default	Description
`options.matcher`	`string \| RegExp`	—	Match the popup’s title or URL
`options.timeout`	`number`	`0`	Max wait time (ms). Default: instant

Examples


// Wait for popup, then switch
await utils.click("#connect-wallet");
const popupReady = await utils.activePopup({ matcher: "MetaMask", timeout: 8000 });
if (!popupReady) {
  logger.warn("MetaMask popup was not found — cannot approve request");
  return;
}
 
await utils.click("#approve");
await utils.activeDefault();  // back to original tab
 
// Switch immediately (popup must already exist)
const activated = await utils.activePopup({ matcher: "MetaMask" });
if (!activated) {
  logger.warn("MetaMask popup is not currently open");
}

Error Handling

activePopup() uses soft-fail semantics. It returns false if no matching popup is found instead of throwing. This lets flows handle optional wallet/auth popups without crashing the profile.

Non-critical activation steps such as focus emulation and stealth script re-application are caught internally and logged as warnings when they fail.