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

> Learn how ego-browser default timeouts work and how to configure them. Optimize your tests by setting custom timeout values for smoother execution.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-08-04

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/state.ts). At lines 37–38, the `state` object declares `defaultTimeout` with an initial value of `10000`:

```ts
// 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`](https://github.com/citrolabs/ego-lite/blob/main/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:

```ts
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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) at lines 86–94, provides the public API for modifying `state.defaultTimeout`:

```js
// 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:

```js
// 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:

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

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

```

## Practical Code Examples

```js
// 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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/state.ts) | Defines `state.defaultTimeout` with initial value `10000` |
| [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) | Implements `page.setDefaultTimeout()` to mutate state |
| [`package/ego-browser/src/driver/waits.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/waits.ts) | Demonstrates timeout resolution in `waitForFunction`, `waitForURL`, etc. |
| [`package/ego-browser/src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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.