How Default Timeouts Work in ego‑browser and How to Configure Them

The ego‑browser library uses a single global default timeout of 10,000 milliseconds (10 seconds) that all wait helpers fall back to when no explicit timeout is provided, configurable at runtime via page.setDefaultTimeout().

All timeout-sensitive operations in ego‑browser share a unified default timeout mechanism. This design ensures consistent behavior across waits for selectors, network requests, page loads, and JavaScript functions. The timeout value lives in a mutable runtime state object and can be changed globally or overridden per call.

Where the Default Timeout Is Stored

The timeout configuration resides in a singleton state object defined in package/ego-browser/src/state.ts. At lines 37–38, the state object declares defaultTimeout with an initial value of 10000:

// package/ego-browser/src/state.ts
export const state = {
  defaultTimeout: 10000,  // 10 seconds in milliseconds
  // ... other runtime state
};

This state object is imported throughout the codebase, making state.defaultTimeout the single source of truth for timeout defaults.

How Helpers Resolve the Effective Timeout

Every wait helper in package/ego-browser/src/driver/waits.ts uses the same resolution pattern. At line 65 (waitForFunction) and line 92 (waitForURL), the effective timeout is computed as:

const timeout = options.timeout ?? state.defaultTimeout;

This nullish coalescing operator (??) gives precedence to any timeout value passed in options. If the caller omits the timeout, the global default applies. The same pattern appears in waitForLoadState, waitForRequest, waitForResponse, waitForSelector, and other helpers.

Configuring the Default Timeout

Change the Global Default at Runtime

The page.setDefaultTimeout() method, implemented in package/ego-browser/src/helpers.ts at lines 86–94, provides the public API for modifying state.defaultTimeout:

// Set all subsequent waits to use 30 seconds
await page.setDefaultTimeout(30000);

After this call, every helper that relies on the default timeout will wait up to 30 seconds. The change takes effect immediately and persists for the remainder of the session unless modified again.

Override Per-Call Without Changing the Global Default

You can still specify a one-off timeout for any individual operation:

// This navigation uses 5 seconds only, global default unchanged
await page.goto('https://example.com', { timeout: 5000 });

The explicit timeout: 5000 overrides state.defaultTimeout for this single call, leaving the global setting intact for future operations.

Reset to Built-In or Custom Baseline

To restore the original 10-second default or establish a new baseline:

// Restore factory default
await page.setDefaultTimeout(10000);

// Or set a project-specific baseline
await page.setDefaultTimeout(15000);

Practical Code Examples

// 1️⃣ Raise global default to 20 seconds for slow-loading sites
await page.setDefaultTimeout(20000);

// 2️⃣ This selector wait inherits the 20-second default
await page.waitForSelector('button.submit');

// 3️⃣ Override with a shorter timeout for this specific request
await page.waitForRequest('**/api/data', { timeout: 5000 });

// 4️⃣ Lower default for faster-failing subsequent operations
await page.setDefaultTimeout(3000);
await page.waitForSelector('.notification');  // uses 3 seconds

Key Source Files in ego‑browser

File	Purpose
package/ego-browser/src/state.ts	Defines state.defaultTimeout with initial value 10000
package/ego-browser/src/helpers.ts	Implements page.setDefaultTimeout() to mutate state
package/ego-browser/src/driver/waits.ts	Demonstrates timeout resolution in waitForFunction, waitForURL, etc.
package/ego-browser/src/format.ts	Documents the setDefaultTimeout helper

Summary

• ego‑browser stores one global default timeout in state.defaultTimeout, initialized to 10,000 ms (10 seconds).
• All wait helpers resolve timeouts with options.timeout ?? state.defaultTimeout, giving per-call overrides priority.
• Use page.setDefaultTimeout(ms) to change the global default at runtime without restarting the session.
• The mechanism is consistent across selector waits, network waits, navigation waits, and function polling.

Frequently Asked Questions

What is the default timeout in ego‑browser if I don't configure anything?

The default timeout is 10,000 milliseconds (10 seconds), defined in package/ego-browser/src/state.ts at lines 37–38. Any wait helper that does not receive an explicit timeout option will use this value.

Can I set different default timeouts for different page instances?

No. ego‑browser uses a singleton state object, so page.setDefaultTimeout() affects all operations across all pages in the same runtime. For different timeout behaviors, use per-call timeout options rather than changing the global default.

Does changing the default timeout affect already-running wait operations?

No. The timeout value is read at the start of each operation, so changes to state.defaultTimeout only affect waits that begin after the setDefaultTimeout() call completes. In-progress operations continue with the timeout they resolved at invocation time.

Which helpers respect the default timeout in ego‑browser?

All major wait and interaction helpers respect it, including waitForSelector, waitForFunction, waitForURL, waitForLoadState, waitForRequest, waitForResponse, and navigation methods like goto. Any method accepting an options object with an optional timeout property follows the options.timeout ?? state.defaultTimeout pattern.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}