How to Use Playwright with Next.js for End-to-End Testing

To use Playwright with Next.js, install Playwright in your Next.js project, write test scripts that launch your Next.js app, and run browser automation to test pages. You can start your Next.js server and then run Playwright tests to simulate user actions and verify UI behavior.

Syntax

Playwright test scripts use async functions to launch browsers, open pages, and interact with elements. You import Playwright's testing library, define test cases with test(), and use page to navigate and check content.

Key parts:

• test(): Defines a test case.
• page.goto(url): Opens a URL in the browser.
• page.click(selector): Simulates a click on an element.
• expect(): Checks conditions like visibility or text.

typescript

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

test('basic test', async ({ page }) => {
  await page.goto('http://localhost:3000');
  await expect(page).toHaveTitle(/Next.js/);
  await page.click('text=About');
  await expect(page).toHaveURL(/about/);
});

Example

This example shows how to write a Playwright test for a Next.js app running locally. It opens the homepage, checks the title, clicks a link, and verifies the URL changed.

typescript

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

test('homepage navigation test', async ({ page }) => {
  // Open the Next.js app running on localhost
  await page.goto('http://localhost:3000');

  // Check the page title contains 'Next.js'
  await expect(page).toHaveTitle(/Next.js/);

  // Click a link with text 'About'
  await page.click('text=About');

  // Verify the URL changed to /about
  await expect(page).toHaveURL(/about/);
});

Output

Running 1 test using 1 worker
  ✓  homepage navigation test (3s)

1 passed (3s)

Common Pitfalls

Common mistakes when using Playwright with Next.js include:

• Not starting the Next.js server before running tests, causing connection errors.
• Using incorrect selectors that don't match rendered elements.
• Ignoring asynchronous page loading, leading to flaky tests.
• Not waiting for navigation or elements before assertions.

Always start your Next.js app with npm run dev or npm start before running Playwright tests.

typescript

/* Wrong: Running test without starting Next.js server */
import { test, expect } from '@playwright/test';

test('fails if server not running', async ({ page }) => {
  await page.goto('http://localhost:3000'); // This will fail if server is down
});

/* Right: Start server first, then run tests */
// Run `npm run dev` in one terminal
// Then run `npx playwright test` in another terminal

Quick Reference

Tips for using Playwright with Next.js:

• Start your Next.js server before tests.
• Use page.goto() to open pages.
• Use text or CSS selectors to find elements.
• Use expect() to check page state.
• Run tests with npx playwright test.

Key Takeaways

Always start your Next.js server before running Playwright tests to avoid connection errors.

Use Playwright's async API to navigate pages and interact with UI elements in your Next.js app.

Write clear selectors and wait for page events to make tests reliable and stable.

Run Playwright tests with the command 'npx playwright test' after installing Playwright.

Use assertions like 'expect' to verify page titles, URLs, and element visibility.