Core Playwright Concepts
Managing waits and timeouts effectively
Managing waits involves mastering Playwright’s built-in auto-waiting mechanisms to handle the asynchronous nature of web applications. Proper configuration prevents brittle tests by ensuring actions occur only when elements are truly ready for interaction. You must reach for these strategies when standard auto-waiting fails due to complex animations, slow network requests, or non-standard UI patterns.
Understanding Auto-waiting Mechanisms
Playwright is designed to be inherently asynchronous, meaning it performs a series of actionable checks before executing any interaction method like click or fill. When you instruct a locator to interact with an element, Playwright automatically ensures that the element is visible, stable, receives events, and is enabled. This 'auto-waiting' eliminates the need for manual sleep statements, which are notoriously unreliable in dynamic web environments. By verifying these states, the framework ensures that your test script is synchronized with the browser's actual rendering cycle. If an element does not meet these criteria within the default timeout period, Playwright will throw a timeout error, providing actionable feedback about which check failed. Understanding that these checks occur implicitly allows you to write cleaner, more resilient code that focuses on intent rather than explicitly managing the low-level lifecycle of DOM nodes.
// Playwright waits for the element to be actionable automatically.
// No manual wait is required here.
await page.getByRole('button', { name: 'Submit' }).click();Configuring Global and Action Timeouts
While auto-waiting covers most scenarios, you will inevitably encounter environments where application response times vary drastically, such as under heavy load or across different testing infrastructures. Playwright offers granular control over how long the framework waits before declaring an action a failure. You can set a global timeout for all tests within the configuration file, or override this on a per-action basis using the 'timeout' option. This is critical for preventing flaky tests in environments with slow network latencies or long-running database queries. By increasing the timeout specifically for intensive operations rather than increasing it globally, you maintain efficient test execution for the majority of the suite while ensuring stability for the outliers. Mastering this balance is essential for maintaining a high-performance test suite that fails fast when errors occur while remaining forgiving enough to handle legitimate, albeit slow, background processes.
// Set a specific timeout for a single long-running action
await page.getByRole('button', { name: 'Export' }).click({ timeout: 10000 });Waiters for State Changes
Sometimes, your application state relies on conditions that cannot be expressed purely through standard actions, such as waiting for a specific class to be removed or for an element to disappear entirely from the DOM. In these instances, you utilize explicit assertion-based waiting. By using the 'expect' library, Playwright polls the application state until the condition is met or the timeout is exceeded. Because these assertions are designed to be retriable, they act as sophisticated waiting mechanisms that synchronize the test execution with the asynchronous updates of the user interface. This is fundamentally different from 'sleep' because the test proceeds the exact millisecond the condition is satisfied, keeping the suite fast. Using assertions for state management is the standard way to ensure that your test remains 'data-driven' by the UI, rather than 'time-driven' by arbitrary delays that break whenever server performance fluctuates.
// Polls until the element is hidden or the timeout is reached
await expect(page.locator('.spinner')).toBeHidden();Waiting for Network Traffic
Modern web applications frequently perform background operations that do not change the DOM immediately, such as fetching data via internal API requests. To manage these, you can use network response waiting. This approach allows your test to pause until a specific network request reaches a successful status code. This is significantly more robust than waiting for a UI change, as the network request is often the source of truth for the application's readiness. By explicitly waiting for these events, you ensure that the subsequent interactions are performed against the intended data, preventing race conditions where the test tries to click a button before the data required for that button's functionality has even been loaded by the browser. It creates a tightly coupled dependency between your test's logic and the underlying application's API architecture, which is generally a best practice for complex single-page applications.
// Wait for a specific API call to complete
await page.waitForResponse(response => response.url().includes('/api/data') && response.status() === 200);Handling Non-Standard UI Elements
Occasionally, you will work with third-party components or legacy code that defies standard auto-waiting expectations, such as elements that are technically present in the DOM but hidden behind an overlay or rendered in an unreachable shadow root. In these complex scenarios, you must explicitly force interactions or wait for specific element properties. This might involve evaluating JavaScript within the page context to verify the state of a custom component or using manual 'waitFor' methods on selectors to ensure the element reaches a specific visual state. When you move beyond the default auto-waiting, you become responsible for the stability of that interaction. Always favor the built-in locators and assertions where possible, but use these advanced techniques only as a bridge for the small subset of UI patterns that standard interactions cannot reliably navigate or identify on their own.
// Manually waiting for a custom element property
const locator = page.locator('my-component');
await locator.evaluate(node => node.isReady === true);Key points
- Playwright automatically waits for elements to be visible and stable before performing actions.
- Manual sleep commands should be avoided as they cause brittle tests and slow execution times.
- Global and per-action timeouts can be configured to accommodate slower test environments.
- Retriable assertions act as the primary mechanism for waiting until the UI reaches a desired state.
- Waiting for network responses ensures that test steps are synchronized with data availability.
- The 'expect' library provides polling mechanisms that execute as fast as the application allows.
- Advanced wait requirements should be handled by evaluating custom logic within the browser context.
- Synchronizing tests with application state is the key to achieving a deterministic and reliable suite.
Common mistakes
- Mistake: Using `page.waitForTimeout(5000)` to handle slow loading elements. Why it's wrong: It causes flaky tests and wastes execution time, as the test will always wait the full duration even if the element appears instantly. Fix: Use auto-waiting locators or Web-First assertions like `expect(locator).toBeVisible()`.
- Mistake: Mixing Playwright's auto-waiting locators with manual sleep statements. Why it's wrong: Manual sleeps create race conditions where the state may change immediately after the sleep finishes. Fix: Rely on Playwright's built-in actionability checks which automatically wait for elements to be stable, visible, and enabled.
- Mistake: Setting the global `expect` timeout too low for slow environments. Why it's wrong: Tests fail intermittently on CI due to network jitter or resource contention. Fix: Use the `timeout` option within specific assertions or increase the global timeout in the configuration file to accommodate slow environments.
- Mistake: Assuming `page.waitForLoadState('networkidle')` is always the best way to wait for a page. Why it's wrong: Modern applications often have continuous background activity (like tracking or polling), causing `networkidle` to wait indefinitely. Fix: Wait for specific elements or network responses relevant to the action being performed.
- Mistake: Over-reliance on `page.waitForSelector` instead of locators. Why it's wrong: `waitForSelector` does not chain with other actions and makes the code verbose. Fix: Use locator-based assertions that handle waiting implicitly as part of the action chain.
Interview questions
What is the default timeout for Playwright actions and why is it important?
In Playwright, the default timeout for most actions like click, fill, or press is 30 seconds. This is a critical feature because it automatically waits for the target element to be actionable—meaning it is visible, stable, and ready to receive interaction—before failing. This 'auto-waiting' mechanism significantly reduces flakiness in tests compared to manual sleep commands, as it allows the test to proceed as soon as the application is ready, rather than waiting for an arbitrary amount of time.
How can you globally configure timeouts in a Playwright project?
You can define global timeouts within the 'playwright.config.ts' file. Specifically, you can set the 'actionTimeout' property to limit the duration of individual actions like clicks, and the 'testTimeout' property to cap the total execution time for each test file. Configuring these globally ensures consistency across your test suite, helping you catch performance regressions early by failing tests that exceed expected response times while avoiding excessive waiting during CI/CD runs.
What is the difference between an 'expect' assertion timeout and an action timeout?
An action timeout is attached to a specific interaction, like clicking a button, and it triggers if the element fails to become actionable within that timeframe. Conversely, an 'expect' assertion timeout, which defaults to 5 seconds, is specifically designed for polling the DOM until a state matches your expectation. You can override the assertion timeout using 'expect.poll()' or by passing a timeout option, such as 'expect(locator).toBeVisible({ timeout: 10000 })'. This separation allows you to handle slow-loading UI elements differently from interactive elements.
Compare the use of 'page.waitForLoadState()' versus 'page.waitForURL()' for managing navigation waits.
While both manage navigation, 'page.waitForLoadState()' is a general approach that pauses execution until a specific lifecycle state is reached, such as 'load', 'domcontentloaded', or 'networkidle'. It is useful for generic page navigation. 'page.waitForURL()', however, is more precise; it specifically waits for the browser's navigation to complete and the URL to match a specific pattern. I prefer 'waitForURL' when dealing with complex routing, as it verifies that the application actually finished navigating to the expected destination, whereas 'networkidle' can sometimes be unreliable if background requests never cease.
How would you handle a scenario where an element appears but is covered by a loading spinner?
To handle elements covered by loading spinners, you should rely on Playwright's built-in actionability checks, which verify if an element is hidden by other elements. If the element is technically in the DOM but blocked, the click action will fail with a timeout error. The best strategy is to explicitly wait for the loading spinner to disappear using 'await expect(spinner).not.toBeVisible()'. By awaiting the disappearance of the blocker, you guarantee the target element becomes the top-most layer, ensuring the subsequent click interacts correctly.
When should you use 'page.waitForResponse()' instead of simple action-based waiting?
You should use 'page.waitForResponse()' when the next state of your application depends on a background API call rather than a UI change. For example, if you click a 'Save' button and need to verify data persistence before moving on, you can write: 'const responsePromise = page.waitForResponse(resp => resp.url().includes('/api/save') && resp.status() === 200); await page.click('#save-btn'); await responsePromise;'. This is far superior to 'waitForTimeout', as it synchronizes your test execution precisely with the network layer, preventing race conditions where the UI might reflect a change before the server has actually processed the request.
Check yourself
1. When is it appropriate to use a hardcoded timeout like `page.waitForTimeout()`?
- A.When an element takes more than 30 seconds to appear on the screen.
- B.When testing animations or deliberate delays where no assertion can track the state.
- C.To ensure the browser has time to finish rendering before taking a screenshot.
- D.Never, it should be avoided entirely in production test suites.
Show answer
D. Never, it should be avoided entirely in production test suites.
Option 3 is the only acceptable answer because hardcoded waits are anti-patterns that induce flakiness. Option 1 is incorrect because you should use a custom timeout on an assertion, not a fixed sleep. Option 2 is a common misconception; animations should be bypassed or handled by checking the final state. Option 3 is incorrect because assertions handle readiness.
2. A test fails because an element is present in the DOM but hidden by a loading spinner. How should you handle this?
- A.Increase the default global timeout in the config file.
- B.Use `page.waitForTimeout()` to wait for the spinner to disappear.
- C.Use an assertion like `expect(locator).toBeVisible()` to trigger Playwright's auto-waiting.
- D.Use `page.reload()` until the element is clickable.
Show answer
C. Use an assertion like `expect(locator).toBeVisible()` to trigger Playwright's auto-waiting.
Option 2 is the correct approach because Web-First assertions automatically wait for the element to meet actionability criteria (visibility, stability). Option 0 is a workaround that doesn't fix the race condition. Option 1 is an anti-pattern. Option 3 is inefficient and unreliable.
3. What happens if you use `page.click('button')` on an element that is currently obscured by a transparent overlay?
- A.Playwright waits until the element is actionable (no longer obscured) before clicking.
- B.Playwright throws an error immediately because the element is not reachable.
- C.Playwright clicks the overlay instead of the button.
- D.Playwright ignores the overlay and clicks the button regardless.
Show answer
A. Playwright waits until the element is actionable (no longer obscured) before clicking.
Playwright's auto-waiting mechanism performs actionability checks, including checking if the element is obscured by other elements. Option 1 is wrong because it waits, not fails. Options 2 and 3 are incorrect because Playwright avoids ambiguous actions by waiting for the element to be ready.
4. Why is `expect(locator).toHaveText('Success')` preferred over `await page.innerText('selector')` followed by a manual comparison?
- A.Because `innerText` is deprecated in Playwright.
- B.Because the assertion automatically retries until the text matches, whereas manual retrieval happens only once.
- C.Because `innerText` cannot handle dynamic content.
- D.Because `innerText` requires a separate `waitForSelector` call every time.
Show answer
B. Because the assertion automatically retries until the text matches, whereas manual retrieval happens only once.
Option 1 is correct because Web-First assertions implement a retry-loop that polls the element state. Option 0 is false. Option 2 is false. Option 3 is incorrect as `innerText` just returns a single snapshot, which is often insufficient for dynamic web applications.
5. If your tests are consistently timing out on CI but passing locally, what is the most robust strategy?
- A.Add a blanket `waitForTimeout` of 10 seconds to every step.
- B.Use `page.waitForLoadState('networkidle')` at the start of every test.
- C.Increase the test timeout globally in the config and improve the efficiency of the assertions.
- D.Reduce the number of assertions to speed up the test execution.
Show answer
C. Increase the test timeout globally in the config and improve the efficiency of the assertions.
Option 2 is the best practice as it addresses environment-specific slowness by adjusting the timeout limit, while keeping the logic resilient. Option 0 is a bad practice. Option 1 is unreliable. Option 3 is wrong because removing assertions reduces test coverage.