activeNewTab

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

Signature


const activated = await utils.activeNewTab(options?)

Return Value

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

Parameters

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

Examples


// Switch immediately (tab must already exist)
const ok = await utils.activeNewTab();
if (!ok) {
  logger.warn("New tab was not found — skipping tab-specific work");
  return;
}
 
// Wait up to 8s for tab to appear, then switch
await utils.click("#open-link");
const activated = await utils.activeNewTab({ timeout: 8000 });
if (!activated) {
  logger.warn("No new tab opened after clicking #open-link");
  return;
}
 
await utils.type("#input", "hello");  // types on new tab
await utils.activeDefault();          // back to original tab

Error Handling

activeNewTab() uses soft-fail semantics. It returns false if no matching tab is found instead of throwing. This prevents a missing or slow tab from crashing the whole flow.

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