Playwright setOffline and navigator.onLine: what the docs don't say

What the docs say

The entire entry for BrowserContext.setOffline on playwright.dev is the signature, the boolean parameter, and one sentence:

await browserContext.setOffline(offline);
// offline (boolean) Whether to emulate network being offline for the browser context.

That is everything. Nothing about navigator.onLine, nothing about the window offline event, nothing about whether the three browser engines behave the same way. People search for this question because the docs do not answer it, not because the answer is hidden.

The good news: the answer is in the open-source implementation, two files deep. The rest of this page is that walk.

What Chromium actually does

The call chain on Chromium starts at the BrowserContext, hops through CRPage, and lands in CRNetworkManager. In packages/playwright-core/src/server/chromium/crNetworkManager.ts, lines 229 through 250:

async setOffline(offline: boolean) {
  if (offline === this._offline)
    return;
  this._offline = offline;
  await this._forEachSession(info => this._setOfflineForSession(info));
}

private async _setOfflineForSession(info: SessionInfo, initial?: boolean) {
  if (initial && !this._offline)
    return;
  if (info.workerFrame)
    return;
  await info.session.send('Network.emulateNetworkConditions', {
    offline: this._offline,
    latency: 0,
    downloadThroughput: -1,
    uploadThroughput: -1
  });
}

The load-bearing line is the protocol send. Playwright is asking Chromium to flip an internal flag via the same CDP command Network.emulateNetworkConditions that Chrome DevTools' throttling panel uses. The Chromium implementation of that command flips navigator.onLine to false, dispatches a window offline event, and starts failing outgoing HTTP and HTTPS requests. The latency and throughput fields are present because the same CDP method handles network throttling; setting throughput to -1 disables the throttle so only the offline flag is in play.

So in Chromium, the chain is: your test code, the Playwright client, the Playwright server, one CDP command, one browser-engine flag. The boolean you read with page.evaluate(() => navigator.onLine) reflects that flag, and it returns false.

What WebKit does differently

WebKit does not speak CDP. It speaks its own Web Inspector protocol, which is similar in shape but uses different method names. Playwright has a parallel implementation in packages/playwright-core/src/server/webkit/wkPage.ts, lines 1068 through 1070:

async updateOffline() {
  await this._updateState('Network.setEmulateOfflineState', {
    offline: !!this._browserContext._options.offline,
  });
}

Same idea, different method. Playwright is asking WebKit to flip the equivalent internal flag via Network.setEmulateOfflineState. That command, on the WebKit side, also flips navigator.onLine and fires the offline event. The reason it shows up in support questions more often than the Chromium version is the timing bug below.

Per-engine behaviour matrix

Same Playwright API, three engines, three slightly different shapes. This is the part the docs flatten into "emulates network being offline".

Issue numbers refer to the microsoft/playwright issue tracker; #34402 was closed as not planned, so the workaround is permanent: navigate first, then setOffline.

The four traps the docs also skip

Each of these is a closed or stale issue in the Playwright repo. None of them appear on the BrowserContext API page. All four can produce a green run that ships a broken offline experience, so they are worth knowing.

The six-step verification recipe

Drop this into any test where you want to confirm navigator.onLine actually flipped and the offline event actually fired. It works across all three engines if you keep the order.

As a runnable spec:

import { test, expect } from '@playwright/test';

test('setOffline flips navigator.onLine and fires the offline event', async ({ page, context }) => {
  // 1. Navigate first (avoids issue #34402 on WebKit and Firefox).
  await page.goto('/');

  // 2. Install the offline listener while still online.
  const offlineFired = page.evaluate(() => new Promise<string>((resolve) => {
    addEventListener('offline', () => resolve('fired'), { once: true });
  }));

  // 3. Flip offline. Internally:
  //    Chromium -> Network.emulateNetworkConditions { offline: true, ... }
  //    WebKit   -> Network.setEmulateOfflineState   { offline: true }
  await context.setOffline(true);

  // 4. The boolean reflects the engine flag.
  expect(await page.evaluate(() => navigator.onLine)).toBe(false);

  // 5. The JS event fired in the page context.
  expect(await offlineFired).toBe('fired');

  // 6. Restore so the next test on this worker is not poisoned.
  await context.setOffline(false);
  expect(await page.evaluate(() => navigator.onLine)).toBe(true);
});

If the boolean assertion in step 4 fails, you are almost certainly on the pre-navigation timing bug; check that page.goto ran before setOffline. If the event assertion in step 5 fails but the boolean passes, the engine acked the protocol command but skipped the JS event; that is worth a new Playwright issue with the engine and version.

When setOffline is the wrong tool

Three cases where the right answer is not setOffline at all.

• You want to fail one request, not all. Use page.route with route.abort('internetdisconnected'). setOffline is context-wide, so it cannot scope.
• You need slow network, not no network. Drop to a raw CDP session and call Network.emulateNetworkConditions with real latency and throughput values. Chromium only.
• You need to test reconnect behaviour. setOffline followed by setOffline(false) gives you the cleanest transition, but pair it with an explicit addEventListener('online', ...) assertion so you know the app saw the recovery, not just that the request layer recovered.

Frequently asked questions about setOffline and navigator.onLine

A short closing

The Playwright BrowserContext API is one of the most polished surfaces in any test framework, but the offline section is genuinely underdocumented. The good news is that the behaviour is fully knowable from the source: a few dozen lines in two files tell you exactly which protocol command flips your boolean, which engines have a timing bug, and which adjacent layers (service workers, WebSockets, raw CDP) do not behave the way the metaphor suggests. The next time the docs feel thin, read the source; the codebase rewards it.