BrowserUtils
BrowserUtils wraps Puppeteer to provide a clean, high-level API for browser automation. All methods operate on the active page — which can be changed via activeTab(), activePopup(), etc.
Quick Start
const utils = new BrowserUtils(context);
await utils.goto("https://example.com");
await utils.click("#login-btn");
await utils.type("#email", "user@test.com");
await utils.type("#password", "secret", { mode: "paste" });
await utils.click("#submit");
const text = await utils.getText(".welcome");Default Timeouts
| Method | Default Timeout | Behavior on Fail |
|---|---|---|
click | waitTimeout: 2000ms, delay: 1000ms | Throw |
type | waitTimeout: 0 (instant) | Throw |
getText | waitTimeout: 0 (instant) | null (soft) |
exists | 4000ms | false (soft) |
waitForElement | 8000ms | null (soft) |
goto | 60000ms (hardcoded), waitUntil: load | Throw |
waitForNavigation | 16000ms, waitUntil: load | Throw |
activeIframe | waitTimeout: 0 (instant) | Throw |
activeNewTab | timeout: 0 (instant) | false (soft) |
activePopup | timeout: 0 (instant) | false (soft) |
waitForNewTab | 8000ms | Throw |
waitForPopup | 8000ms | Throw |
screenshot | — | null (soft) |
waitTimeout Pattern
Methods with waitTimeout default to 0 (instant query via $()). Pass waitTimeout only when you need to wait:
// Instant — element must already exist in DOM
await utils.type("#input", "hello");
await utils.getText(".price");
// Wait up to 8s for element to appear, then act
await utils.type("#lazy-input", "hello", { waitTimeout: 8000 });
await utils.getText(".lazy-el", { waitTimeout: 8000 });Tab & Popup Management
// Switch + work on popup
await utils.click("#connect-wallet");
const popupReady = await utils.activePopup({ matcher: "MetaMask", timeout: 8000 });
if (!popupReady) {
logger.warn("Popup did not open — skip wallet approval");
return;
}
await utils.click("#approve");
await utils.activeDefault(); // back to original tab
// Switch by index
await utils.activeTab(1); // go to second tab
await utils.activeDefault(); // back to original tab
// Cleanup
await utils.closeCurrentTab();
await utils.closeOtherTabs();Iframe Support
await utils.activeIframe("#my-iframe");
await utils.click("#btn-in-iframe");
await utils.activeMainFrame(); // exit iframeLast updated on