How to Add a Fixed Wait in Playwright (Equivalent to Cypress cy.wait())

Use page.waitForTimeout(milliseconds) or frame.waitForTimeout(milliseconds) to pause test execution for a specific duration without checking any condition, just like Cypress's cy.wait() command.

When migrating from Cypress to Playwright, developers often need a way to introduce a hard pause in their tests. While Playwright emphasizes conditional waiting strategies, the framework does provide a mechanism for fixed wait in Playwright through the waitForTimeout method available on both Page and Frame objects in the microsoft/playwright repository.

The waitForTimeout API Implementation

Playwright implements fixed waits as thin wrappers that forward the request to the underlying browser channel. In packages/playwright-core/src/client/page.ts at lines 784-785, the Page class delegates waitForTimeout calls directly to its main frame:

async waitForTimeout(timeout: number): Promise<void> {
  return this._wrapApiCall(async () => {
    await this._mainFrame.waitForTimeout(timeout);
  });
}

Similarly, the Frame implementation in packages/playwright-core/src/client/frame.ts at lines 448-449 handles the actual timer logic by forwarding to the channel:

async waitForTimeout(timeout: number): Promise<void> {
  await this._channel.waitForTimeout({ timeout });
}

The TypeScript definitions in packages/playwright-core/types/types.d.ts at lines 5214-5226 explicitly document that this API is intended only for debugging and should not be used in production tests.

How to Use Fixed Waits in Playwright

Basic Page-Level Fixed Wait

To pause execution for a specific number of milliseconds on the main page:

// Pause for 2 seconds
await page.waitForTimeout(2000);

Frame-Level Fixed Wait

When working with iframes or nested frames, apply the fixed wait to a specific frame:

const frame = page.frame({ url: /example/ });
await frame.waitForTimeout(500);

Debugging Scenarios

Use fixed waits sparingly for visual confirmation during debugging:

await page.waitForTimeout(1000);
await page.screenshot({ path: 'debug.png' });

Alternatives to Fixed Waits in Playwright

While Cypress developers often rely on cy.wait() for timing issues, Playwright offers superior conditional waiting strategies that make tests more stable and faster.

Wait for Element Visibility

Instead of guessing how long an animation takes, wait for the element to actually appear:

await expect(page.locator('#result')).toBeVisible({ timeout: 5000 });

Wait for Custom Conditions

Use waitForFunction to poll until a specific JavaScript condition returns true:

await page.waitForFunction(() => window.someFlag === true, null, { timeout: 3000 });

Wait for Network Idle

Wait until there are no network connections for at least 500ms:

await page.waitForLoadState('networkidle');

Summary

• page.waitForTimeout(ms) and frame.waitForTimeout(ms) provide fixed delays equivalent to Cypress's cy.wait().
• The implementation resides in packages/playwright-core/src/client/page.ts (lines 784-785) and packages/playwright-core/src/client/frame.ts (lines 448-449).
• According to the TypeScript definitions in packages/playwright-core/types/types.d.ts (lines 5214-5226), this API is debugging-only and not recommended for production tests.
• Always prefer conditional waits (waitForFunction, expect matchers, or waitForLoadState) over fixed waits to maintain test reliability and execution speed.

Frequently Asked Questions

What is the Playwright equivalent of Cypress cy.wait()?

The direct equivalent is page.waitForTimeout(milliseconds), which pauses execution for a fixed duration without checking any conditions. However, unlike Cypress where cy.wait() is commonly used for timing, Playwright explicitly marks this API as debugging-only according to the source code in packages/playwright-core/types/types.d.ts.

Why does Playwright discourage fixed waits in production tests?

Fixed waits introduce flakiness and unnecessary delays because they don't account for varying network speeds, CPU load, or animation durations. As documented in the TypeScript definitions at lines 5214-5226, waitForTimeout is intended only for debugging scenarios where you need to observe browser state manually.

How do I wait for a specific condition instead of using a fixed timer?

Use page.waitForFunction() to poll a JavaScript predicate, or use Playwright's built-in assertions like expect(locator).toBeVisible(). These methods accept a timeout parameter but resolve immediately when the condition is met, making tests both faster and more reliable than blind pauses.

Can I use waitForTimeout on iframe elements?

Yes, the Frame class implements the same waitForTimeout method at packages/playwright-core/src/client/frame.ts lines 448-449. Access the frame via page.frame() or page.frameLocator(), then call await frame.waitForTimeout(1000) to pause execution within that specific frame context.

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