Pause, debug, and wait in Playwright

Use page.pause() for interactive debugging and condition-based waits for unattended tests, with separate timeout settings.

Guance Editorial Team 2026-10-27 3 min read Updated 2026-10-27

Best practices

Illustration of software development and testing

Choose the kind of pause you need. await page.pause() opens interactive debugging through Playwright Inspector. await page.waitForTimeout(3000) waits a fixed three seconds and should be limited to debugging. For a real test, wait for a condition with a locator, a retrying assertion, or a specific navigation or response.

Pause at a debugging breakpoint

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

test('inspect a page', async ({ page }) => {
  await page.goto('https://example.com');
  await page.pause();
  // Continue with an action on your own test page.
});

Run in headed mode, for example with --headed. Inspector lets you step through actions, inspect locators, and read action logs. Remove the breakpoint before an unattended run or guard it explicitly for local debugging.

Use fixed waits only while investigating

await page.waitForTimeout(3000); // Always waits three seconds.

The delay does not express what the test needs. If the element appears after 100 milliseconds, the remaining wait is wasted. If it takes four seconds, the test still fails. Replace it with a condition once you understand the behavior.

Wait for a meaningful condition

These fragments belong inside a test with expect imported:

await page.locator('#result').waitFor(); // Defaults to waiting for visibility.
await expect(page.locator('#result')).toBeVisible();
await page.waitForURL(/\/dashboard/);

const responsePromise = page.waitForResponse(r => r.url().includes('/api/list'));
await page.getByRole('button', { name: 'Load' }).click();
await responsePromise;
// Also assert the expected result in the page.

Register response waits before the action that triggers the request. A response can arrive before a wait registered afterward, and receiving it does not necessarily mean rendering has finished.

Configure the relevant timeout

In Playwright Test, the test timeout defaults to 30 seconds and retrying assertions to five seconds. Actions and navigations have no separate default limit (0), but remain constrained by the test timeout. Do not confuse those runner defaults with standalone Playwright Library settings.

import { defineConfig } from '@playwright/test';

export default defineConfig({
  timeout: 60_000,
  expect: { timeout: 10_000 },
  use: { actionTimeout: 15_000 },
});

Frequently asked questions

Why do animations cause failures?

An element can be visible while still moving. Click actions perform stability checks, whereas a visibility assertion does not mean the element has stopped moving. Inspect endless animations and wait for the application's completion state, or stabilize irrelevant animation in the test environment. A fixed sleep only hides the timing assumption.

Can page.pause() block CI?

It requires headed mode and is not a breakpoint that unattended CI can be expected to skip. Keep it in local debugging code or use an explicit guard such as if (process.env.PWDEBUG) await page.pause();. Ensure the chosen debugging setup actually runs headed.

Why avoid networkidle for readiness?

Ongoing requests and polling can delay network idleness, while an idle network can still precede an application's usable state. Prefer a particular response or a visible result that matches the user flow.