Playwright Error Index

Quick-reference for specific Playwright error messages. Find your error, understand the cause, apply the fix.

How to use: Search this file for the exact error text you see in your terminal or test report. Each entry gives you the cause and a working fix.

Locator & Element Errors

"locator.click: Target closed"

Cause: The page or frame navigated away (or was closed) before Playwright finished executing the action on the element.

Common triggers:

Clicking a link that triggers navigation while another action is still pending
A form submit causes a page reload before a subsequent click() or fill() resolves
Calling page.close() or context.close() in a finally block that races with an in-flight action
An unhandled exception in the application triggers an error page redirect

Fix: Wait for navigation to complete before performing the next action, or use Promise.all to coordinate the click and navigation together.

// TypeScript — wait for navigation caused by clicking a link
await Promise.all([
  page.waitForURL('**/dashboard'),
  page.getByRole('link', { name: 'Dashboard' }).click(),
]);

// JavaScript — same pattern
await Promise.all([
  page.waitForURL('**/dashboard'),
  page.getByRole('link', { name: 'Dashboard' }).click(),
]);

If the page is closing intentionally (e.g., a popup), capture a reference before the action:

// TypeScript — handle popup that closes itself
const popupPromise = page.waitForEvent('popup');
await page.getByRole('button', { name: 'Open popup' }).click();
const popup = await popupPromise;
await popup.waitForLoadState();
// interact with popup before it closes
await popup.getByRole('button', { name: 'Confirm' }).click();

// JavaScript — handle popup that closes itself
const popupPromise = page.waitForEvent('popup');
await page.getByRole('button', { name: 'Open popup' }).click();
const popup = await popupPromise;
await popup.waitForLoadState();
await popup.getByRole('button', { name: 'Confirm' }).click();

"waiting for locator('...') to be visible"

Cause: Playwright's auto-waiting timed out because the element never appeared in the DOM or remained hidden (e.g., display: none, visibility: hidden, zero size, or behind aria-hidden).

Common triggers:

The element renders conditionally and the condition was not met (missing data, unauthenticated state)
Content loads asynchronously and the locator was evaluated before the API response arrived
The selector is wrong — typo in role, name, or test ID
The element exists but is off-screen or inside a collapsed container
CSS animation or transition keeps the element at opacity: 0 without making it visible to Playwright

Fix: First confirm the locator matches what you expect using the Playwright Inspector. Then ensure the precondition for the element to appear is met.

// TypeScript — debug: check what the locator resolves to
console.log(await page.getByRole('button', { name: 'Submit' }).count());
// If 0, the element is not in the DOM — check your selector or page state

// Correct approach: wait for the data to load first
await page.waitForResponse(resp =>
  resp.url().includes('/api/data') && resp.status() === 200
);
await expect(page.getByRole('button', { name: 'Submit' })).toBeVisible();

// JavaScript — same approach
console.log(await page.getByRole('button', { name: 'Submit' }).count());

await page.waitForResponse(resp =>
  resp.url().includes('/api/data') && resp.status() === 200
);
await expect(page.getByRole('button', { name: 'Submit' })).toBeVisible();

"locator.click: Error: strict mode violation"

Cause: The locator matched more than one element and Playwright's strict mode (enabled by default) refuses to act on ambiguous matches.

Common triggers:

Using getByRole('button') when multiple buttons exist on the page
Using getByText('Save') when both "Save" and "Save as draft" are present
Partial text matching when exact: true is needed
The same component is rendered multiple times (e.g., in a list)

Fix: Make the locator more specific so it resolves to exactly one element.

// TypeScript

// BAD — matches multiple buttons
await page.getByRole('button', { name: 'Save' }).click();

// GOOD — use exact matching
await page.getByRole('button', { name: 'Save', exact: true }).click();

// GOOD — scope to a specific container
await page.getByRole('dialog')
  .getByRole('button', { name: 'Save' }).click();

// GOOD — use .first(), .last(), .nth() when order is meaningful
await page.getByRole('listitem').first().click();

// GOOD — chain with filter for list items
await page.getByRole('listitem')
  .filter({ hasText: 'Project Alpha' })
  .getByRole('button', { name: 'Delete' }).click();

// JavaScript

// BAD — matches multiple buttons
await page.getByRole('button', { name: 'Save' }).click();

// GOOD — use exact matching
await page.getByRole('button', { name: 'Save', exact: true }).click();

// GOOD — scope to a specific container
await page.getByRole('dialog')
  .getByRole('button', { name: 'Save' }).click();

// GOOD — use .first(), .last(), .nth() when order is meaningful
await page.getByRole('listitem').first().click();

// GOOD — chain with filter for list items
await page.getByRole('listitem')
  .filter({ hasText: 'Project Alpha' })
  .getByRole('button', { name: 'Delete' }).click();

"Error: expect(locator).toBeVisible() — locator resolved to X elements"

Cause: Same root cause as strict mode violation above — the assertion's locator matched multiple elements, so Playwright cannot determine which one to assert on.

Common triggers:

Same as strict mode violation triggers above
Writing expect(page.locator('.item')).toBeVisible() when there are many .item elements

Fix: Narrow the locator to a single element (see strict mode violation fix above). Alternatively, if you intentionally want to check all matches:

// TypeScript — assert count instead of visibility
await expect(page.getByRole('listitem')).toHaveCount(5);

// Or assert on a specific one
await expect(page.getByRole('listitem').first()).toBeVisible();

// Or assert all are visible with a loop
for (const item of await page.getByRole('listitem').all()) {
  await expect(item).toBeVisible();
}

// JavaScript — assert count instead of visibility
await expect(page.getByRole('listitem')).toHaveCount(5);

// Or assert on a specific one
await expect(page.getByRole('listitem').first()).toBeVisible();

// Or assert all are visible with a loop
for (const item of await page.getByRole('listitem').all()) {
  await expect(item).toBeVisible();
}

"locator.fill: Error: Element is not an , or [contenteditable] element"</h3> Cause: <code>fill()</code> only works on <code><input></code>, <code><textarea></code>, or elements with <code>contenteditable</code>. The locator resolved to a different element type (e.g., a <code><div></code>, <code><label></code>, or the <code><form></code> itself). Common triggers: <ul dir="auto"> <li>Locating by label text but the label and input are not properly associated via <code>for</code>/<code>id</code></li> <li>Using <code>getByText()</code> instead of <code>getByLabel()</code> or <code>getByRole('textbox')</code></li> <li>Custom components that wrap the actual <code><input></code> in a styled <code><div></code></li> <li>Rich text editors that use <code>contenteditable</code> on an inner element, not the outer wrapper</li> </ul> Fix: Target the actual input element. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // BAD — targets the label, not the input await page.getByText('Email').fill('user@example.com'); // GOOD — getByLabel finds the associated input await page.getByLabel('Email').fill('user@example.com'); // GOOD — target by role await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com'); // For contenteditable rich text editors await page.locator('[contenteditable="true"]').fill('Hello world'); // If fill() still doesn't work (e.g., custom widget), use keyboard input await page.getByRole('textbox', { name: 'Email' }).click(); await page.keyboard.type('user@example.com'); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // BAD — targets the label, not the input await page.getByText('Email').fill('user@example.com'); // GOOD — getByLabel finds the associated input await page.getByLabel('Email').fill('user@example.com'); // GOOD — target by role await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com'); // For contenteditable rich text editors await page.locator('[contenteditable="true"]').fill('Hello world'); // If fill() still doesn't work (e.g., custom widget), use keyboard input await page.getByRole('textbox', { name: 'Email' }).click(); await page.keyboard.type('user@example.com'); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/locators.md">core/locators.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/forms-and-validation.md">core/forms-and-validation.md</a> <hr> <h3 id="user-content-error-elementhandle-click-node-is-not-an-element" dir="auto">"Error: elementHandle.click: Node is not an Element"</h3> Cause: You are using the legacy ElementHandle API and the handle has gone stale — the underlying DOM node was removed or replaced by a re-render. Common triggers: <ul dir="auto"> <li>Storing an <code>elementHandle</code> in a variable and using it after a navigation or React/Vue re-render</li> <li>Using <code>page.$()</code> or <code>page.$$()</code> instead of Locator API</li> <li>Framework hydration replaces the server-rendered node with a client-rendered one</li> </ul> Fix: Switch from ElementHandle to Locator. Locators re-query the DOM on every action and never go stale. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // BAD — stale handle const button = await page.$('button.submit'); // ... page re-renders ... await button!.click(); // Node is not an Element // GOOD — locator always re-queries const button = page.getByRole('button', { name: 'Submit' }); // ... page re-renders ... await button.click(); // works fine </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // BAD — stale handle const button = await page.$('button.submit'); // ... page re-renders ... await button.click(); // Node is not an Element // GOOD — locator always re-queries const button = page.getByRole('button', { name: 'Submit' }); // ... page re-renders ... await button.click(); // works fine </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/locators.md">core/locators.md</a> <hr> <h3 id="user-content-error-locator-click-timeout-30000ms-exceeded" dir="auto">"Error: locator.click: Timeout 30000ms exceeded"</h3> Cause: The element was found in the DOM but was not actionable within the timeout. "Actionable" means visible, stable (not animating), enabled, and not obscured by another element. Common triggers: <ul dir="auto"> <li>An overlay, modal, or toast is covering the element</li> <li>The element is disabled (<code>disabled</code> attribute or <code>aria-disabled="true"</code>)</li> <li>CSS animation has not completed (element is still moving)</li> <li>A loading spinner overlays the button</li> <li>The element is outside the viewport and Playwright's auto-scroll failed</li> </ul> Fix: Identify what is blocking the action using traces, then address it. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // Step 1: Enable tracing to diagnose // In playwright.config.ts: // use: { trace: 'on-first-retry' } // Then run: npx playwright show-trace trace.zip // Common fix: wait for the overlay to disappear await expect(page.locator('.loading-overlay')).toBeHidden(); await page.getByRole('button', { name: 'Submit' }).click(); // Common fix: force click when you know the overlay is benign // (use sparingly — this skips actionability checks) await page.getByRole('button', { name: 'Submit' }).click({ force: true }); // Common fix: wait for the element to be enabled await expect(page.getByRole('button', { name: 'Submit' })).toBeEnabled(); await page.getByRole('button', { name: 'Submit' }).click(); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // Common fix: wait for the overlay to disappear await expect(page.locator('.loading-overlay')).toBeHidden(); await page.getByRole('button', { name: 'Submit' }).click(); // Common fix: force click (use sparingly) await page.getByRole('button', { name: 'Submit' }).click({ force: true }); // Common fix: wait for the element to be enabled await expect(page.getByRole('button', { name: 'Submit' })).toBeEnabled(); await page.getByRole('button', { name: 'Submit' }).click(); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/assertions-and-waiting.md">core/assertions-and-waiting.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/debugging.md">core/debugging.md</a> <hr> <h2 id="user-content-navigation-page-errors" dir="auto">Navigation & Page Errors</h2> <hr> <h3 id="user-content-page-goto-net-err_connection_refused" dir="auto">"page.goto: net::ERR_CONNECTION_REFUSED"</h3> Cause: Playwright could not connect to the target URL. The server is not running or is not listening on the expected host/port. Common triggers: <ul dir="auto"> <li>Forgot to start the dev server before running tests</li> <li>Dev server is on a different port than <code>baseURL</code> in config</li> <li>Server is listening on <code>127.0.0.1</code> but test uses <code>localhost</code> (or vice versa) and the OS resolves them differently</li> <li>In CI, the application build/start step failed silently</li> <li>Docker container networking: the app runs inside a container but the test tries to reach <code>localhost</code></li> </ul> Fix: Use the <code>webServer</code> config option to let Playwright start and manage the dev server automatically. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript — playwright.config.ts import { defineConfig } from '@playwright/test'; export default defineConfig({ webServer: { command: 'npm run dev', url: '<a href="http://localhost:3000" class="link">http://localhost:3000</a>', reuseExistingServer: !process.env.CI, timeout: 120_000, // 2 minutes for server start }, use: { baseURL: '<a href="http://localhost:3000" class="link">http://localhost:3000</a>', }, }); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript — playwright.config.js const { defineConfig } = require('@playwright/test'); module.exports = defineConfig({ webServer: { command: 'npm run dev', url: '<a href="http://localhost:3000" class="link">http://localhost:3000</a>', reuseExistingServer: !process.env.CI, timeout: 120_000, }, use: { baseURL: '<a href="http://localhost:3000" class="link">http://localhost:3000</a>', }, }); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/configuration.md">core/configuration.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/ci/ci-github-actions.md">ci/ci-github-actions.md</a> <hr> <h3 id="user-content-page-goto-timeout-30000ms-exceeded" dir="auto">"page.goto: Timeout 30000ms exceeded"</h3> Cause: The page did not reach the <code>load</code> state (by default) within the navigation timeout. The server responded but the page took too long to fully load. Common triggers: <ul dir="auto"> <li>Large assets (images, fonts, scripts) slow the page load</li> <li>Third-party scripts (analytics, ads) blocking the load event</li> <li>The page makes many API calls before becoming interactive</li> <li>The server responded with a redirect chain that takes too long</li> </ul> Fix: Use a more appropriate <code>waitUntil</code> option or increase the navigation timeout. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // Use 'domcontentloaded' instead of 'load' if you don't need all assets await page.goto('/dashboard', { waitUntil: 'domcontentloaded' }); // Or increase the navigation timeout for known slow pages await page.goto('/dashboard', { timeout: 60_000 }); // Or set it globally in config // playwright.config.ts export default defineConfig({ use: { navigationTimeout: 60_000, }, }); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript await page.goto('/dashboard', { waitUntil: 'domcontentloaded' }); await page.goto('/dashboard', { timeout: 60_000 }); // playwright.config.js module.exports = defineConfig({ use: { navigationTimeout: 60_000, }, }); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/configuration.md">core/configuration.md</a> <hr> <h3 id="user-content-error-page-goto-navigation-failed-because-page-was-closed" dir="auto">"Error: page.goto: Navigation failed because page was closed!"</h3> Cause: The page or browser context was closed while <code>goto()</code> was still in progress. This typically happens in teardown/cleanup race conditions. Common triggers: <ul dir="auto"> <li><code>afterEach</code> or a fixture closes the page/context before navigation completes</li> <li>Another test or hook called <code>browser.close()</code> prematurely</li> <li>A test failed and the cleanup ran while an async navigation was still pending</li> <li>Using <code>test.fixme()</code> or <code>test.skip()</code> after an async operation has started</li> </ul> Fix: Ensure cleanup only runs after all page operations complete. Use fixtures for lifecycle management instead of manual <code>afterEach</code>. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // BAD — race condition between test body and cleanup test.afterEach(async ({ page }) => { await page.close(); // may race with in-flight navigation }); // GOOD — let Playwright manage page lifecycle via fixtures // Playwright automatically creates and destroys the page per test // No manual cleanup needed // If you need custom cleanup, make sure to await all navigation first test('navigates to dashboard', async ({ page }) => { const responsePromise = page.waitForResponse('/api/user'); await page.goto('/dashboard'); await responsePromise; // ensure all async ops are done // test assertions here }); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript — same pattern test('navigates to dashboard', async ({ page }) => { const responsePromise = page.waitForResponse('/api/user'); await page.goto('/dashboard'); await responsePromise; // test assertions here }); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/fixtures-and-hooks.md">core/fixtures-and-hooks.md</a> <hr> <h3 id="user-content-page-waitfornavigation-timeout-30000ms-exceeded" dir="auto">"page.waitForNavigation: Timeout 30000ms exceeded"</h3> Cause: <code>waitForNavigation()</code> waited for a full page navigation that never happened. In SPAs, client-side routing does not trigger a navigation event. Common triggers: <ul dir="auto"> <li>Using <code>waitForNavigation()</code> with a SPA that uses React Router, Vue Router, or Next.js client-side navigation</li> <li>The navigation already happened before <code>waitForNavigation()</code> was called (race condition)</li> <li>Using the deprecated pattern when <code>waitForURL()</code> is the correct replacement</li> </ul> Fix: Replace <code>waitForNavigation()</code> with <code>waitForURL()</code> which works with both SPAs and traditional page loads. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // BAD — deprecated, race-prone, doesn't work with SPA routing await page.waitForNavigation(); // GOOD — works with SPAs and full navigations await page.getByRole('link', { name: 'Dashboard' }).click(); await page.waitForURL('/dashboard'); // GOOD — combine with glob patterns await page.waitForURL(/\/dashboard\/\d+/); // GOOD — for SPA route changes, assert on visible content await page.getByRole('link', { name: 'Settings' }).click(); await expect(page.getByRole('heading', { name: 'Settings' })).toBeVisible(); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // BAD — deprecated, race-prone await page.waitForNavigation(); // GOOD — works with SPAs and full navigations await page.getByRole('link', { name: 'Dashboard' }).click(); await page.waitForURL('/dashboard'); // GOOD — combine with glob patterns await page.waitForURL(/\/dashboard\/\d+/); // GOOD — for SPA route changes, assert on visible content await page.getByRole('link', { name: 'Settings' }).click(); await expect(page.getByRole('heading', { name: 'Settings' })).toBeVisible(); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/assertions-and-waiting.md">core/assertions-and-waiting.md</a> <hr> <h3 id="user-content-error-frame-goto-frame-was-detached" dir="auto">"Error: frame.goto: Frame was detached"</h3> Cause: The iframe was removed from the DOM (detached) while Playwright was navigating or interacting with it. Common triggers: <ul dir="auto"> <li>The parent page re-rendered and recreated the iframe element</li> <li>JavaScript on the parent page removed and re-added the iframe</li> <li>A SPA route change unmounted the component containing the iframe</li> <li>An ad iframe reloaded itself</li> </ul> Fix: Re-acquire the frame reference after the parent page updates. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // BAD — frame reference becomes stale const frame = page.frameLocator('#my-iframe'); // ... parent page re-renders ... await frame.getByRole('button').click(); // Frame was detached // GOOD — use frameLocator (re-evaluates each time) // frameLocator itself is lazy, but the frame it points to must exist await expect(page.frameLocator('#my-iframe').getByRole('button')).toBeVisible(); await page.frameLocator('#my-iframe').getByRole('button').click(); // GOOD — wait for the iframe to be present after a re-render await expect(page.locator('#my-iframe')).toBeAttached(); await page.frameLocator('#my-iframe').getByRole('button').click(); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // GOOD — frameLocator re-evaluates lazily await expect(page.frameLocator('#my-iframe').getByRole('button')).toBeVisible(); await page.frameLocator('#my-iframe').getByRole('button').click(); // GOOD — wait for the iframe to be present after a re-render await expect(page.locator('#my-iframe')).toBeAttached(); await page.frameLocator('#my-iframe').getByRole('button').click(); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/iframes-and-shadow-dom.md">core/iframes-and-shadow-dom.md</a> <hr> <h2 id="user-content-test-framework-errors" dir="auto">Test Framework Errors</h2> <hr> <h3 id="user-content-error-test-timeout-of-30000ms-exceeded" dir="auto">"Error: Test timeout of 30000ms exceeded"</h3> Cause: The entire test (including all hooks and assertions) did not complete within the configured test timeout. Common triggers: <ul dir="auto"> <li>Waiting for an element that never appears (wrong locator, missing data)</li> <li>Unresolved <code>page.waitForEvent()</code> — the expected event never fires</li> <li>Slow test environment (CI with limited resources)</li> <li>Too many sequential actions in a single test</li> <li>A <code>beforeEach</code> hook performs expensive setup (login, data seeding)</li> </ul> Fix: Identify the slow step using <code>test.step()</code> and traces, then either fix the root cause or adjust the timeout. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // Increase timeout for a specific slow test test('generates large report', async ({ page }) => { test.setTimeout(120_000); // 2 minutes for this test only // ... }); // Increase timeout globally in config // playwright.config.ts export default defineConfig({ timeout: 60_000, // 60 seconds per test }); // Better: diagnose with test.step() to find what's slow test('checkout flow', async ({ page }) => { await test.step('add item to cart', async () => { await page.goto('/products'); await page.getByRole('button', { name: 'Add to Cart' }).click(); }); await test.step('complete checkout', async () => { await page.getByRole('link', { name: 'Cart' }).click(); await page.getByRole('button', { name: 'Checkout' }).click(); }); }); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript test('generates large report', async ({ page }) => { test.setTimeout(120_000); // ... }); // playwright.config.js module.exports = defineConfig({ timeout: 60_000, }); test('checkout flow', async ({ page }) => { await test.step('add item to cart', async () => { await page.goto('/products'); await page.getByRole('button', { name: 'Add to Cart' }).click(); }); await test.step('complete checkout', async () => { await page.getByRole('link', { name: 'Cart' }).click(); await page.getByRole('button', { name: 'Checkout' }).click(); }); }); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/configuration.md">core/configuration.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/debugging.md">core/debugging.md</a> <hr> <h3 id="user-content-error-expect-received-tomatchsnapshot" dir="auto">"Error: expect(received).toMatchSnapshot()"</h3> Cause: The current screenshot or text does not match the stored baseline snapshot. Common triggers: <ul dir="auto"> <li>Legitimate UI changes that require updating the snapshot</li> <li>Different rendering between local and CI (fonts, anti-aliasing, OS-level rendering)</li> <li>Dynamic content (timestamps, random IDs, ads) that changes between runs</li> <li>Different viewport sizes or device emulation settings between environments</li> </ul> Fix: Update the snapshot if the change is intentional, or mask/hide dynamic areas. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // Update snapshots after intentional changes // Run: npx playwright test --update-snapshots // Mask dynamic content before taking a screenshot await expect(page).toHaveScreenshot('dashboard.png', { mask: [ page.locator('.timestamp'), page.locator('.random-ad'), ], maxDiffPixelRatio: 0.01, // allow 1% pixel difference }); // Use text snapshot with a sanitizer for dynamic values const content = await page.getByRole('main').textContent(); const sanitized = content!.replace(/\d{4}-\d{2}-\d{2}/g, 'DATE'); expect(sanitized).toMatchSnapshot('dashboard-content.txt'); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // Update snapshots: npx playwright test --update-snapshots await expect(page).toHaveScreenshot('dashboard.png', { mask: [ page.locator('.timestamp'), page.locator('.random-ad'), ], maxDiffPixelRatio: 0.01, }); const content = await page.getByRole('main').textContent(); const sanitized = content.replace(/\d{4}-\d{2}-\d{2}/g, 'DATE'); expect(sanitized).toMatchSnapshot('dashboard-content.txt'); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/visual-regression.md">core/visual-regression.md</a> <hr> <h3 id="user-content-error-browsertype-launch-executable-doesn-t-exist" dir="auto">"Error: browserType.launch: Executable doesn't exist"</h3> Cause: The Playwright browser binaries are not installed on this machine or they were installed for a different Playwright version. Common triggers: <ul dir="auto"> <li>Fresh clone of a project without running the install step</li> <li>Upgrading <code>@playwright/test</code> without reinstalling browsers</li> <li>CI environment missing the install step</li> <li>Using <code>npm ci</code> which cleans <code>node_modules</code> but does not trigger the browser install postinstall script</li> <li>Multiple Playwright versions installed (global vs local)</li> </ul> Fix: Install the browsers. <pre class="code-block"><code class="chroma language-bash display"># Install all browsers npx playwright install # Install only the browser you need (faster in CI) npx playwright install chromium # Install browsers with OS dependencies (needed in CI/Docker) npx playwright install --with-deps # If you're on a CI Dockerfile, add this to your Dockerfile # RUN npx playwright install --with-deps chromium </code></pre>For CI pipelines, always include the install step: <pre class="code-block"><code class="chroma language-yaml display"># GitHub Actions example - name: Install Playwright Browsers run: npx playwright install --with-deps </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/ci/ci-github-actions.md">ci/ci-github-actions.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/ci/docker-and-containers.md">ci/docker-and-containers.md</a> <hr> <h3 id="user-content-error-cannot-use-import-statement-outside-a-module" dir="auto">"Error: Cannot use import statement outside a module"</h3> Cause: Node.js is running the test file as CommonJS but the file uses ES module <code>import</code> syntax without the right configuration. Common triggers: <ul dir="auto"> <li>Missing or misconfigured <code>tsconfig.json</code></li> <li>Using <code>.ts</code> files without <code>@playwright/test</code> properly resolving TypeScript</li> <li><code>package.json</code> does not have <code>"type": "module"</code> but test files use <code>import</code></li> <li>Running test files directly with <code>node</code> instead of through <code>npx playwright test</code></li> <li>Conflicting Babel or ts-node configuration</li> </ul> Fix: Ensure TypeScript is configured correctly and always run tests through the Playwright CLI. <pre class="code-block"><code class="chroma language-bash display"># Always run tests through the Playwright CLI — never with node directly npx playwright test # NOT this: # node tests/example.spec.ts <-- will fail </code></pre><pre class="code-block"><code class="chroma language-typescript display">// TypeScript — tsconfig.json (minimal working config) { "compilerOptions": { "target": "ES2020", "module": "ESNext", "moduleResolution": "bundler", "strict": true, "esModuleInterop": true, "skipLibCheck": true } } </code></pre>If using JavaScript without TypeScript: <pre class="code-block"><code class="chroma language-javascript display">// JavaScript — ensure package.json has "type": "module" // Or rename files to .mjs // In playwright.config.js — use require if package.json lacks "type": "module" const { defineConfig } = require('@playwright/test'); module.exports = defineConfig({ /* ... / }); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/configuration.md">core/configuration.md</a> <hr> <h3 id="user-content-error-fixture-xxx-has-already-been-registered" dir="auto">"Error: fixture "xxx" has already been registered"</h3> Cause: A custom fixture was defined with the same name in multiple <code>test.extend()</code> calls that got merged, or the same fixture name was registered twice in the same extension. Common triggers: <ul dir="auto"> <li>Two different fixture files both define a fixture with the same name</li> <li>Importing the extended <code>test</code> object from multiple files that each add overlapping fixtures</li> <li>Copy-pasting fixture definitions without renaming</li> </ul> Fix: Ensure each fixture name is unique across your merged fixture chain. Use a single fixture file that combines all extensions. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // BAD — two separate extensions with the same fixture name // fixtures/auth.ts export const test = base.extend<{ user: User }>({ user: async ({}, use) => { / ... / }, }); // fixtures/data.ts — CONFLICT: "user" already exists export const test = base.extend<{ user: User }>({ user: async ({}, use) => { / ... */ }, }); // GOOD — single combined fixture file // fixtures/index.ts import { test as base } from '@playwright/test'; type MyFixtures = { authenticatedUser: User; testData: TestData; }; export const test = base.extend<MyFixtures>({ authenticatedUser: async ({}, use) => { const user = await createUser(); await use(user); await deleteUser(user); }, testData: async ({}, use) => { const data = await seedData(); await use(data); await cleanupData(data); }, }); export { expect } from '@playwright/test'; </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // GOOD — single combined fixture file // fixtures/index.js const { test: base } = require('@playwright/test'); const test = base.extend({ authenticatedUser: async ({}, use) => { const user = await createUser(); await use(user); await deleteUser(user); }, testData: async ({}, use) => { const data = await seedData(); await use(data); await cleanupData(data); }, }); module.exports = { test }; </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/fixtures-and-hooks.md">core/fixtures-and-hooks.md</a> <hr> <h2 id="user-content-network-api-errors" dir="auto">Network & API Errors</h2> <hr> <h3 id="user-content-page-route-pattern-should-start-with" dir="auto">"page.route: Pattern should start with..."</h3> Cause: The URL pattern passed to <code>page.route()</code> does not match the expected format. Playwright expects a glob pattern (starting with <code>/</code> or <code>http</code>), a regex, or a predicate function. Common triggers: <ul dir="auto"> <li>Passing a bare path like <code>/api/users</code> instead of <code>/api/users</code></li> <li>Missing the <code></code> glob prefix for relative patterns</li> <li>Passing an object or invalid type instead of a string/regex</li> </ul> Fix: Use the correct pattern format. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // BAD — bare path without glob prefix await page.route('/api/users', route => route.fulfill({ body: '[]' })); // GOOD — glob pattern await page.route('/api/users', route => route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify([{ id: 1, name: 'Alice' }]), }) ); // GOOD — regex pattern await page.route(/\/api\/users\/\d+/, route => route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ id: 1, name: 'Alice' }), }) ); // GOOD — predicate function for complex matching await page.route( url => url.pathname.startsWith('/api/') && url.searchParams.has('filter'), route => route.fulfill({ body: '[]' }) ); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // GOOD — glob pattern await page.route('/api/users', route => route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify([{ id: 1, name: 'Alice' }]), }) ); // GOOD — regex pattern await page.route(/\/api\/users\/\d+/, route => route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ id: 1, name: 'Alice' }), }) ); // GOOD — predicate function await page.route( url => url.pathname.startsWith('/api/') && url.searchParams.has('filter'), route => route.fulfill({ body: '[]' }) ); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/network-mocking.md">core/network-mocking.md</a> <hr> <h3 id="user-content-error-apirequestcontext-get-connect-econnrefused" dir="auto">"Error: apiRequestContext.get: connect ECONNREFUSED"</h3> Cause: The API request made via <code>request.get()</code> (or <code>.post()</code>, <code>.put()</code>, etc.) could not connect to the target server. Same underlying issue as <code>page.goto: net::ERR_CONNECTION_REFUSED</code> but for API testing. Common triggers: <ul dir="auto"> <li>API server not running when using <code>request</code> fixture</li> <li>Wrong <code>baseURL</code> in the config or in the API request context</li> <li>Running API tests against a service that hasn't started yet</li> <li>In CI, the API service container is not ready</li> </ul> Fix: Ensure the API server is running. Use <code>webServer</code> config to auto-start it, or add a health check. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript — playwright.config.ts import { defineConfig } from '@playwright/test'; export default defineConfig({ webServer: [ { command: 'npm run start:api', url: '<a href="http://localhost:4000/health" class="link">http://localhost:4000/health</a>', reuseExistingServer: !process.env.CI, }, { command: 'npm run start:web', url: '<a href="http://localhost:3000" class="link">http://localhost:3000</a>', reuseExistingServer: !process.env.CI, }, ], use: { baseURL: '<a href="http://localhost:3000" class="link">http://localhost:3000</a>', }, }); // In tests, use the request fixture with explicit baseURL for API calls test('fetch users', async ({ request }) => { const response = await request.get('<a href="http://localhost:4000/api/users" class="link">http://localhost:4000/api/users</a>'); expect(response.ok()).toBeTruthy(); }); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript — playwright.config.js const { defineConfig } = require('@playwright/test'); module.exports = defineConfig({ webServer: [ { command: 'npm run start:api', url: '<a href="http://localhost:4000/health" class="link">http://localhost:4000/health</a>', reuseExistingServer: !process.env.CI, }, { command: 'npm run start:web', url: '<a href="http://localhost:3000" class="link">http://localhost:3000</a>', reuseExistingServer: !process.env.CI, }, ], use: { baseURL: '<a href="http://localhost:3000" class="link">http://localhost:3000</a>', }, }); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/api-testing.md">core/api-testing.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/configuration.md">core/configuration.md</a> <hr> <h3 id="user-content-request-was-not-handled-get-https" dir="auto">"Request was not handled: GET https://..."</h3> Cause: A route handler was registered with <code>page.route()</code> using <code>{ times: N }</code> or <code>page.unrouteAll()</code> was called, and a subsequent request matching that pattern was not intercepted — Playwright warns you that a request fell through. Common triggers: <ul dir="auto"> <li>Using <code>page.route()</code> with <code>{ times: 1 }</code> but the app makes the same request more than once</li> <li>Calling <code>route.fallback()</code> or <code>route.continue()</code> without a handler to catch it</li> <li>Calling <code>page.unrouteAll({ behavior: 'wait' })</code> mid-test and the app makes another request</li> </ul> Fix: Ensure your route handler covers all expected requests, or let unhandled requests pass through. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // BAD — only handles the first request, second one is unhandled await page.route('/api/data', route => route.fulfill({ body: '{}' }), { times: 1 } ); // GOOD — handle all requests to this URL await page.route('/api/data', route => route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ items: [] }), }) ); // GOOD — if you only want to intercept once, use waitForResponse for subsequent await page.route('/api/data', route => route.fulfill({ body: '{"items": []}' }), { times: 1 } ); // For the second call, let it go to the real server (no route needed) </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // GOOD — handle all requests to this URL await page.route('**/api/data', route => route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ items: [] }), }) ); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/network-mocking.md">core/network-mocking.md</a> <hr> <h2 id="user-content-authentication-state-errors" dir="auto">Authentication & State Errors</h2> <hr> <h3 id="user-content-error-browsercontext-storagestate-no-such-file" dir="auto">"Error: browserContext.storageState: No such file"</h3> Cause: The <code>storageState</code> path referenced in the config or test does not point to an existing file. The auth state file has not been generated yet. Common triggers: <ul dir="auto"> <li>Running tests before running the auth setup project</li> <li>The <code>globalSetup</code> or auth setup project did not complete successfully</li> <li>The file path in the config does not match the path used in the setup</li> <li><code>.gitignore</code> excluded the storage state file and it was not regenerated after a fresh clone</li> <li>CI cache expired and the state file was not recreated</li> </ul> Fix: Ensure the auth setup runs first and the file path is consistent. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript — playwright.config.ts import { defineConfig } from '@playwright/test'; const authFile = 'playwright/.auth/user.json'; export default defineConfig({ projects: [ // Setup project runs first and creates the auth state file { name: 'setup', testMatch: /.\.setup\.ts/, }, { name: 'chromium', use: { storageState: authFile, }, dependencies: ['setup'], // ensures setup runs first }, ], }); // auth.setup.ts import { test as setup, expect } from '@playwright/test'; const authFile = 'playwright/.auth/user.json'; setup('authenticate', async ({ page }) => { await page.goto('/login'); await page.getByLabel('Email').fill('user@example.com'); await page.getByLabel('Password').fill('password123'); await page.getByRole('button', { name: 'Sign in' }).click(); await page.waitForURL('/dashboard'); // Save the authenticated state await page.context().storageState({ path: authFile }); }); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript — playwright.config.js const { defineConfig } = require('@playwright/test'); const authFile = 'playwright/.auth/user.json'; module.exports = defineConfig({ projects: [ { name: 'setup', testMatch: /.\.setup\.js/, }, { name: 'chromium', use: { storageState: authFile, }, dependencies: ['setup'], }, ], }); // auth.setup.js const { test: setup, expect } = require('@playwright/test'); const authFile = 'playwright/.auth/user.json'; setup('authenticate', async ({ page }) => { await page.goto('/login'); await page.getByLabel('Email').fill('user@example.com'); await page.getByLabel('Password').fill('password123'); await page.getByRole('button', { name: 'Sign in' }).click(); await page.waitForURL('/dashboard'); await page.context().storageState({ path: authFile }); }); </code></pre>Ensure the auth directory exists and is in <code>.gitignore</code>: <pre class="code-block"><code class="chroma language-bash display">mkdir -p playwright/.auth echo "playwright/.auth/" >> .gitignore </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/authentication.md">core/authentication.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/auth-flows.md">core/auth-flows.md</a> <hr> <h3 id="user-content-error-target-page-context-or-browser-has-been-closed" dir="auto">"Error: Target page, context or browser has been closed"</h3> Cause: Code attempted to use a <code>page</code>, <code>context</code>, or <code>browser</code> object that has already been closed or disposed. Common triggers: <ul dir="auto"> <li>Using a <code>page</code> reference after <code>page.close()</code> was called</li> <li>Storing a <code>page</code> or <code>context</code> in a module-level variable and reusing it across tests</li> <li>A fixture tore down the browser context while an async callback was still running</li> <li>A <code>beforeAll</code> created a context that was closed before all tests finished using it</li> <li>Using <code>browser.newContext()</code> manually and forgetting to manage its lifecycle</li> </ul> Fix: Never store page/context references in shared mutable state. Use Playwright fixtures for lifecycle management. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // BAD — shared module-level variable let sharedPage: Page; test.beforeAll(async ({ browser }) => { sharedPage = await browser.newPage(); }); test.afterAll(async () => { await sharedPage.close(); }); test('first', async () => { await sharedPage.goto('/'); // might fail if afterAll from another describe ran first }); // GOOD — use the built-in page fixture (one per test, auto-managed) test('first', async ({ page }) => { await page.goto('/'); // always a fresh, open page }); // GOOD — for shared state across tests, use a worker-scoped fixture import { test as base } from '@playwright/test'; export const test = base.extend<{}, { adminContext: BrowserContext }>({ adminContext: [async ({ browser }, use) => { const context = await browser.newContext(); await use(context); await context.close(); }, { scope: 'worker' }], }); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // GOOD — use the built-in page fixture test('first', async ({ page }) => { await page.goto('/'); }); // GOOD — for shared state, use a worker-scoped fixture const { test: base } = require('@playwright/test'); const test = base.extend({ adminContext: [async ({ browser }, use) => { const context = await browser.newContext(); await use(context); await context.close(); }, { scope: 'worker' }], }); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/fixtures-and-hooks.md">core/fixtures-and-hooks.md</a> <hr> <h2 id="user-content-ci-specific-errors" dir="auto">CI-Specific Errors</h2> <hr> <h3 id="user-content-error-browsertype-launch-browser-closed-unexpectedly" dir="auto">"Error: browserType.launch: Browser closed unexpectedly"</h3> Cause: The browser process crashed immediately after launch, usually because required OS-level dependencies are missing in the CI environment. Common triggers: <ul dir="auto"> <li>Running on a minimal Docker image (e.g., <code>node:alpine</code>) without browser dependencies</li> <li>Missing shared libraries (<code>libgbm</code>, <code>libnss3</code>, <code>libatk-bridge</code>, etc.) on Linux CI</li> <li>Insufficient shared memory (<code>/dev/shm</code> too small) — browsers use shared memory for rendering</li> <li>Running as root in Docker without <code>--no-sandbox</code> (Chromium refuses to run as root with sandbox)</li> <li>Out-of-memory kill on CI (browser process is OOM-killed by the OS)</li> </ul> Fix: Install OS-level dependencies and configure the environment. <pre class="code-block"><code class="chroma language-bash display"># Install browsers with their OS dependencies (recommended) npx playwright install --with-deps chromium # If using Docker, use the official Playwright image # Dockerfile FROM mcr.microsoft.com/playwright:v1.50.0-noble WORKDIR /app COPY . . RUN npm ci RUN npx playwright install chromium CMD ["npx", "playwright", "test"] </code></pre>For shared memory issues: <pre class="code-block"><code class="chroma language-yaml display"># GitHub Actions — increase /dev/shm jobs: test: runs-on: ubuntu-latest container: image: mcr.microsoft.com/playwright:v1.50.0-noble options: --shm-size=2gb # Docker run — increase shared memory # docker run --shm-size=2gb my-test-image </code></pre>For running as root in Docker: <pre class="code-block"><code class="chroma language-typescript display">// TypeScript — playwright.config.ts (only for Docker/CI) export default defineConfig({ use: { launchOptions: { args: process.env.CI ? ['--no-sandbox', '--disable-setuid-sandbox'] : [], }, }, }); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript — playwright.config.js module.exports = defineConfig({ use: { launchOptions: { args: process.env.CI ? ['--no-sandbox', '--disable-setuid-sandbox'] : [], }, }, }); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/ci/ci-github-actions.md">ci/ci-github-actions.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/ci/docker-and-containers.md">ci/docker-and-containers.md</a> <hr> <h3 id="user-content-error-playwright-test-needs-to-be-invoked-via-npx-playwright-test" dir="auto">"Error: Playwright Test needs to be invoked via 'npx playwright test'"</h3> Cause: The test file was executed directly with <code>node</code> or <code>ts-node</code> instead of through the Playwright test runner. Common triggers: <ul dir="auto"> <li>Running <code>node tests/example.spec.ts</code> or <code>ts-node tests/example.spec.ts</code></li> <li>A misconfigured IDE run configuration that invokes <code>node</code> directly</li> <li>Using Jest or Mocha to run Playwright test files that import from <code>@playwright/test</code></li> <li>A CI script that calls the wrong command</li> </ul> Fix: Always use the Playwright CLI to run tests. <pre class="code-block"><code class="chroma language-bash display"># Correct invocations npx playwright test # run all tests npx playwright test tests/login.spec.ts # run specific file npx playwright test --grep "login" # run tests matching pattern npx playwright test --project=chromium # run specific project npx playwright test --debug # run with inspector # If using a package.json script # package.json # "scripts": { "test:e2e": "playwright test" } npm run test:e2e </code></pre>For IDE configuration (VS Code): <pre class="code-block"><code class="chroma language-json display">// .vscode/settings.json — install the Playwright VS Code extension instead of custom configs { "playwright.reuseBrowser": true } </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/configuration.md">core/configuration.md</a> <hr> <h2 id="user-content-additional-common-errors" dir="auto">Additional Common Errors</h2> <hr> <h3 id="user-content-error-page-evaluate-execution-context-was-destroyed" dir="auto">"Error: page.evaluate: Execution context was destroyed"</h3> Cause: The page navigated or reloaded while <code>page.evaluate()</code> was executing JavaScript in the browser context. Common triggers: <ul dir="auto"> <li>Calling <code>evaluate()</code> while the page is in the middle of a navigation</li> <li>A timer or event on the page triggers a redirect during evaluation</li> <li>Running <code>evaluate()</code> in a <code>beforeEach</code> that races with <code>page.goto()</code></li> </ul> Fix: Ensure the page is stable before evaluating. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // BAD — evaluate races with navigation await page.goto('/dashboard'); const title = await page.evaluate(() => document.title); // context might be destroyed // GOOD — wait for load state first await page.goto('/dashboard'); await page.waitForLoadState('domcontentloaded'); const title = await page.evaluate(() => document.title); // GOOD — prefer locator-based assertions (no evaluate needed) await page.goto('/dashboard'); await expect(page).toHaveTitle('Dashboard'); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // GOOD — wait for load state first await page.goto('/dashboard'); await page.waitForLoadState('domcontentloaded'); const title = await page.evaluate(() => document.title); // GOOD — prefer locator-based assertions await page.goto('/dashboard'); await expect(page).toHaveTitle('Dashboard'); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/assertions-and-waiting.md">core/assertions-and-waiting.md</a> <hr> <h3 id="user-content-error-page-screenshot-cannot-take-a-screenshot-larger-than" dir="auto">"Error: page.screenshot: Cannot take a screenshot larger than..."</h3> Cause: The requested screenshot dimensions exceed Playwright's limit (typically 16384x16384 pixels). This happens with full-page screenshots of very long pages. Common triggers: <ul dir="auto"> <li><code>page.screenshot({ fullPage: true })</code> on an infinitely-scrolling page</li> <li>Pages with extremely tall content (long data tables, chat logs)</li> <li>CSS bugs that create enormous element heights</li> </ul> Fix: Clip the screenshot to a specific region or limit the viewport. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // BAD — might exceed size limits on tall pages await page.screenshot({ fullPage: true, path: 'full.png' }); // GOOD — clip to a specific region await page.screenshot({ path: 'clipped.png', clip: { x: 0, y: 0, width: 1280, height: 2000 }, }); // GOOD — screenshot a specific element instead await page.getByRole('main').screenshot({ path: 'main-content.png' }); // GOOD — set a reasonable viewport before full-page screenshot await page.setViewportSize({ width: 1280, height: 720 }); await page.screenshot({ fullPage: true, path: 'full.png' }); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // GOOD — clip to a specific region await page.screenshot({ path: 'clipped.png', clip: { x: 0, y: 0, width: 1280, height: 2000 }, }); // GOOD — screenshot a specific element await page.getByRole('main').screenshot({ path: 'main-content.png' }); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/visual-regression.md">core/visual-regression.md</a> <hr> <h3 id="user-content-error-waiting-for-locator-tobeattached" dir="auto">"Error: waiting for locator('...').toBeAttached()"</h3> Cause: The element never entered the DOM within the assertion timeout. Unlike <code>toBeVisible()</code>, <code>toBeAttached()</code> only checks DOM presence — but the element was never rendered at all. Common triggers: <ul dir="auto"> <li>The component is conditionally rendered and the condition is not met</li> <li>A network request that populates the data has not completed</li> <li>Wrong selector that does not match any element</li> <li>The element is rendered by a lazy-loaded chunk that has not downloaded yet</li> </ul> Fix: Verify the precondition for the element to render. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // Ensure the data loads before asserting await page.goto('/users'); await page.waitForResponse(resp => resp.url().includes('/api/users')); await expect(page.getByRole('table')).toBeAttached(); // For lazy-loaded content, wait longer or trigger the load await page.getByRole('tab', { name: 'Advanced' }).click(); await expect(page.getByTestId('advanced-panel')).toBeAttached({ timeout: 10_000 }); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript await page.goto('/users'); await page.waitForResponse(resp => resp.url().includes('/api/users')); await expect(page.getByRole('table')).toBeAttached(); await page.getByRole('tab', { name: 'Advanced' }).click(); await expect(page.getByTestId('advanced-panel')).toBeAttached({ timeout: 10_000 }); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/assertions-and-waiting.md">core/assertions-and-waiting.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/locators.md">core/locators.md</a> <hr> <h3 id="user-content-error-protocol-error-target-createtarget-failed-to-create-target" dir="auto">"Error: protocol error: Target.createTarget: Failed to create target"</h3> Cause: The browser could not create a new tab or context, usually due to resource exhaustion. Common triggers: <ul dir="auto"> <li>Opening too many pages or contexts without closing them</li> <li>Memory leak in tests — each test opens a context but never closes it</li> <li>Running many parallel workers on a resource-constrained CI machine</li> <li>Browser process is unstable after a previous crash</li> </ul> Fix: Reduce parallelism, close unused contexts, or use fewer workers. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript — playwright.config.ts export default defineConfig({ // Reduce parallelism if resources are limited workers: process.env.CI ? 2 : undefined, // Limit to one browser context per worker fullyParallel: false, // run test files serially within a worker }); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript — playwright.config.js module.exports = defineConfig({ workers: process.env.CI ? 2 : undefined, fullyParallel: false, }); </code></pre>If you manually create contexts, always close them: <pre class="code-block"><code class="chroma language-typescript display">// TypeScript test('multi-user test', async ({ browser }) => { const userContext = await browser.newContext(); const adminContext = await browser.newContext(); try { const userPage = await userContext.newPage(); const adminPage = await adminContext.newPage(); // ... test logic } finally { await userContext.close(); await adminContext.close(); } }); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript test('multi-user test', async ({ browser }) => { const userContext = await browser.newContext(); const adminContext = await browser.newContext(); try { const userPage = await userContext.newPage(); const adminPage = await adminContext.newPage(); // ... test logic } finally { await userContext.close(); await adminContext.close(); } }); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/ci/parallel-and-sharding.md">ci/parallel-and-sharding.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/multi-user-and-collaboration.md">core/multi-user-and-collaboration.md</a> <hr> <h3 id="user-content-error-expect-locator-tohavetext-expected-string-but-received-array" dir="auto">"Error: expect(locator).toHaveText() — expected string but received array"</h3> Cause: The locator matched multiple elements and <code>toHaveText()</code> returned an array of strings instead of a single string. Common triggers: <ul dir="auto"> <li>Using a broad locator like <code>page.locator('.item')</code> that matches a list</li> <li>Expecting a single heading but the selector matches multiple</li> <li>Not scoping the locator to a specific container</li> </ul> Fix: Either narrow the locator to one element or use the array form of <code>toHaveText()</code>. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // BAD — locator matches multiple elements await expect(page.locator('.item')).toHaveText('First Item'); // GOOD — narrow to one element await expect(page.locator('.item').first()).toHaveText('First Item'); // GOOD — assert against an array when multiple elements are expected await expect(page.locator('.item')).toHaveText([ 'First Item', 'Second Item', 'Third Item', ]); // GOOD — use a more specific locator await expect(page.getByRole('heading', { level: 1 })).toHaveText('Welcome'); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // GOOD — narrow to one element await expect(page.locator('.item').first()).toHaveText('First Item'); // GOOD — assert against an array await expect(page.locator('.item')).toHaveText([ 'First Item', 'Second Item', 'Third Item', ]); // GOOD — use a more specific locator await expect(page.getByRole('heading', { level: 1 })).toHaveText('Welcome'); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/assertions-and-waiting.md">core/assertions-and-waiting.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/locators.md">core/locators.md</a> <hr> <h3 id="user-content-error-page-waitforselector-timeout-30000ms-exceeded-deprecated" dir="auto">"Error: page.waitForSelector: Timeout 30000ms exceeded (deprecated)"</h3> Cause: <code>page.waitForSelector()</code> timed out. This method is deprecated in favor of locator-based assertions. Common triggers: <ul dir="auto"> <li>Using legacy <code>page.waitForSelector()</code> from older tutorials or migration from Puppeteer</li> <li>The selector does not match any element in the DOM</li> <li>The element exists but does not meet the state requirement (e.g., <code>{ state: 'visible' }</code> but element is hidden)</li> </ul> Fix: Replace <code>waitForSelector()</code> with locator-based assertions. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // BAD — deprecated, no auto-retry, not composable await page.waitForSelector('.loading', { state: 'hidden' }); await page.waitForSelector('.content', { state: 'visible' }); // GOOD — locator-based assertions with auto-retry await expect(page.locator('.loading')).toBeHidden(); await expect(page.locator('.content')).toBeVisible(); // GOOD — use role-based locators for even more resilience await expect(page.getByRole('progressbar')).toBeHidden(); await expect(page.getByRole('main')).toBeVisible(); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // BAD — deprecated await page.waitForSelector('.loading', { state: 'hidden' }); await page.waitForSelector('.content', { state: 'visible' }); // GOOD — locator-based assertions await expect(page.locator('.loading')).toBeHidden(); await expect(page.locator('.content')).toBeVisible(); // GOOD — role-based locators await expect(page.getByRole('progressbar')).toBeHidden(); await expect(page.getByRole('main')).toBeVisible(); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/locators.md">core/locators.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/assertions-and-waiting.md">core/assertions-and-waiting.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/migration/from-selenium.md">migration/from-selenium.md</a> <hr> <h3 id="user-content-error-test-was-expected-to-have-a-title-matching" dir="auto">"Error: Test was expected to have a title matching /.../"</h3> Cause: The <code>expect(page).toHaveTitle()</code> assertion failed because the page title did not match the expected value or pattern within the timeout. Common triggers: <ul dir="auto"> <li>The page has not finished loading and the title is still the initial empty or default value</li> <li>The SPA updates the document title asynchronously after rendering</li> <li>The expected title has a typo or does not match case-sensitively</li> <li>The page redirected to an error page with a different title</li> </ul> Fix: Ensure the page is fully loaded and use the correct expected value. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // toHaveTitle auto-retries, but ensure the page has loaded await page.goto('/dashboard'); await expect(page).toHaveTitle('Dashboard | MyApp'); // Use regex for flexible matching await expect(page).toHaveTitle(/Dashboard/); // Debug: check what the actual title is console.log(await page.title()); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript await page.goto('/dashboard'); await expect(page).toHaveTitle('Dashboard | MyApp'); // Use regex for flexible matching await expect(page).toHaveTitle(/Dashboard/); // Debug: check what the actual title is console.log(await page.title()); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/assertions-and-waiting.md">core/assertions-and-waiting.md</a> <hr> <h3 id="user-content-error-page-type-element-is-not-focusable" dir="auto">"Error: page.type: Element is not focusable"</h3> Cause: <code>page.type()</code> or <code>locator.type()</code> could not focus the target element before typing. The element may be hidden, disabled, or not an input. Common triggers: <ul dir="auto"> <li>The element is covered by an overlay or modal</li> <li>The element has <code>tabindex="-1"</code> and is not natively focusable</li> <li>Using <code>type()</code> instead of <code>fill()</code> — <code>fill()</code> is preferred in almost all cases</li> <li>The element is inside a Shadow DOM and the locator does not pierce it</li> </ul> Fix: Use <code>fill()</code> instead of <code>type()</code>. Only use <code>type()</code> when you specifically need to simulate individual keystrokes. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // BAD — type() is slower and more fragile await page.locator('#search').type('hello'); // GOOD — fill() clears and sets the value directly await page.getByRole('searchbox').fill('hello'); // When you truly need keystroke-by-keystroke input (e.g., autocomplete trigger) await page.getByRole('searchbox').pressSequentially('hello', { delay: 100 }); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // GOOD — fill() is preferred await page.getByRole('searchbox').fill('hello'); // Keystroke-by-keystroke when needed (e.g., autocomplete) await page.getByRole('searchbox').pressSequentially('hello', { delay: 100 }); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/locators.md">core/locators.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/forms-and-validation.md">core/forms-and-validation.md</a> <hr> <h3 id="user-content-error-page-setinputfiles-non-multiple-file-input-can-only-accept-single-file" dir="auto">"Error: page.setInputFiles: Non-multiple file input can only accept single file"</h3> Cause: Attempted to upload multiple files to an <code><input type="file"></code> that does not have the <code>multiple</code> attribute. Common triggers: <ul dir="auto"> <li>Passing an array of files to a single-file upload input</li> <li>The app uses a custom upload component that only handles one file at a time</li> </ul> Fix: Upload one file at a time, or ensure the input supports multiple files. <pre class="code-block"><code class="chroma language-typescript display">// TypeScript // BAD — input does not have multiple attribute await page.getByLabel('Upload file').setInputFiles([ 'file1.pdf', 'file2.pdf', // error: non-multiple input ]); // GOOD — single file await page.getByLabel('Upload file').setInputFiles('file1.pdf'); // GOOD — for multiple file input (must have multiple attribute in HTML) await page.getByLabel('Upload files').setInputFiles([ 'file1.pdf', 'file2.pdf', ]); // To clear the file input await page.getByLabel('Upload file').setInputFiles([]); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript // GOOD — single file await page.getByLabel('Upload file').setInputFiles('file1.pdf'); // GOOD — multiple files (input must have multiple attribute) await page.getByLabel('Upload files').setInputFiles([ 'file1.pdf', 'file2.pdf', ]); // To clear the file input await page.getByLabel('Upload file').setInputFiles([]); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/file-operations.md">core/file-operations.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/file-upload-download.md">core/file-upload-download.md</a> <hr> <h3 id="user-content-error-browser-newcontext-could-not-parse-content-type-application-json" dir="auto">"Error: browser.newContext: Could not parse content-type application/json"</h3> Cause: The <code>storageState</code> option was given a path to a file with invalid JSON content, or the file is not a valid Playwright storage state format. Common triggers: <ul dir="auto"> <li>The auth setup wrote an empty file or incomplete JSON</li> <li>The storage state file was corrupted or truncated</li> <li>Manually editing the storage state file and introducing a syntax error</li> <li>The auth setup failed silently (login did not complete) and saved an invalid state</li> </ul> Fix: Delete the storage state file and regenerate it. <pre class="code-block"><code class="chroma language-bash display"># Delete the corrupted file rm -f playwright/.auth/user.json # Re-run the setup npx playwright test --project=setup </code></pre>To prevent this, add error checking in the auth setup: <pre class="code-block"><code class="chroma language-typescript display">// TypeScript — auth.setup.ts import { test as setup, expect } from '@playwright/test'; const authFile = 'playwright/.auth/user.json'; setup('authenticate', async ({ page }) => { await page.goto('/login'); await page.getByLabel('Email').fill('user@example.com'); await page.getByLabel('Password').fill('password123'); await page.getByRole('button', { name: 'Sign in' }).click(); // Verify login actually succeeded before saving state await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible(); await page.context().storageState({ path: authFile }); }); </code></pre><pre class="code-block"><code class="chroma language-javascript display">// JavaScript — auth.setup.js const { test: setup, expect } = require('@playwright/test'); const authFile = 'playwright/.auth/user.json'; setup('authenticate', async ({ page }) => { await page.goto('/login'); await page.getByLabel('Email').fill('user@example.com'); await page.getByLabel('Password').fill('password123'); await page.getByRole('button', { name: 'Sign in' }).click(); // Verify login actually succeeded before saving state await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible(); await page.context().storageState({ path: authFile }); }); </code></pre>Related: <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/authentication.md">core/authentication.md</a>, <a href="/code/apunkt/SurfSense/src/commit/4ac994792bf3e68a4b8e3553db18661bf9879518/.cursor/skills/playwright-testing/auth-flows.md">core/auth-flows.md</a> <hr> <h2 id="user-content-quick-diagnostic-checklist" dir="auto">Quick Diagnostic Checklist</h2> When you hit an error not listed above, run through this checklist: <ol dir="auto"> <li>Read the full error — Playwright errors include the locator, action, and a snippet of the page state. The answer is often in the details.</li> <li>Enable traces — Add <code>trace: 'on'</code> temporarily or <code>trace: 'on-first-retry'</code> in config. Run <code>npx playwright show-trace trace.zip</code> to see screenshots, DOM, network, and console at the point of failure.</li> <li>Use the Playwright Inspector — Run <code>npx playwright test --debug</code> to step through the test interactively.</li> <li>Check the locator — Run <code>npx playwright codegen <url></code> to verify locators against the live page.</li> <li>Check the Playwright version — Run <code>npx playwright --version</code>. Ensure <code>@playwright/test</code> and browser binaries are the same version.</li> <li>Search the Playwright issue tracker — Many errors have known solutions in <a href="<a href="https://github.com/microsoft/playwright/issues" class="link">https://github.com/microsoft/playwright/issues</a>">github.com/microsoft/playwright/issues</a>.</li> </ol> </body></html>

58 KiB Executable file Raw Blame History

Playwright Error Index

Locator & Element Errors

"locator.click: Target closed"

"waiting for locator('...') to be visible"

"locator.click: Error: strict mode violation"

"Error: expect(locator).toBeVisible() — locator resolved to X elements"

58 KiB

Executable file

Raw Blame History