Beginner’s Guide to Playwright Testing in Next.js

Building modern web applications comes with the responsibility of ensuring they perform correctly across different devices, browsers, and user interactions. If you’re developing with Next.js, a powerful React framework, incorporating automated testing from the start can save you from bugs, regression s, and unexpected failures in production.

This guide introduces Playwright, a modern end-to-end testing framework from Microsoft and demonstrates how to integrate it into a Next.js project. By the end, you’ll have a basic app with route navigation and playwright test that verify pages render and behave correctly.

Why Use Playwright with Next.js

Next.js enables fast, scalable React applications with feature live server-side rendering (SSR), static site generation (SSG), dynamic routing and API routes.

Playwright helps you simulate real user action like clicking, navigating and filling out form in a browser environment. It’s:

• Fast and reliable
• Headless (run without UI), or headed (for debugging)
• Multi-browser (Chromium, Firefox, WebKit)
• Great for full end-to-end testing

Together, they create a perfect testing stack

Prerequisites

Before we start, make sure you have the following:

• Node.js v16 or above
• npm or yarn
• Basic familiarity with JavaScript, Next.js and React

Step 1: Create a New Next.js App

Let’s start with a fresh project. Open your terminal and run:

npx create-next-app@latest nextjs-playwright-demo
cd nextjs-playwright-demo

Once the setup is completed, start your development server:

npm run dev

You should see the default Next.js homepage at https://localhost:3000

Step 2: Add Pages and Navigation

Let’s add two simple routes: Home and About

Create about.tsx

// src/app/about/page.tsx
export default function About() {
    return (
        <h2>About Page</h2>
    )
}

Update the Home Page with a Link

Edit src/app/page.tsx:

import Link from "next/link";

export default function App() {
    return (
        <div>
            <h2>Home Page</h2>
            <Link href="/about">Go to about</Link>
        </div>
    )
}

You now have two routes ready to be tested.

Step 3: Install Playwright

Install Playwright globally and its dependencies

npm install -g playwright

It installs playwright test library and browsers (Chromium, Firefox, Webkit)

Step 4: Initialize Playwright

Run:

npm init playwright

This sets up:

• playwright.config.ts for playwright configurations
• tests/ directory for your test files
• Install dev dependency in the project

Step 5: Write Playwright Tests for Your App

Create a test file: tests/routes.spec.ts

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

test("Home page render correctly", async ({ page }) => {
    await page.goto("http://localhost:3000/");
    await expect(page.locator("h2")).toHaveText(/Home Page/);
});

test("About page renders correctly", async ({ page }) => {
    await page.goto("http://localhost:3000/about");
    await expect(page.locator("h2")).toHaveText(/About Page/);
});

test("User can navigate from Home to About Page", async ({ page }) => {
    await page.goto("http://localhost:3000/");
    await page.click("text=Go to About");
    await page.waitForURL("/about");
    await expect(page).toHaveURL("/about");
    await expect(page.locator("h2")).toHaveText(/About Page/);
});

What’s Happening?

• The first test visits the home page and checks heading text
• The second test goes directly to the About page
• The third simulates clicking a link to navigate between routes

Step 6: Run Your Tests

To run all tests:

npx playwright test

You should see output like:

Run in the headed mode (visible browser) for debugging:

npx playwright test --headed

Launch the interactive test runner:

npx playwright test --ui

Step 7: Trace and Debug Failures

Playwright provides a powerful trace viewer to debug flaky or failed tests.

Enable tracing in playwright.config.ts:

Then show the report with

npx playwright show-report

This opens a UI where you can replay each step of your test.

What You’ve Learned

In this tutorial, you’ve:

• Create a basic Next.js application
• Set up routing between pages
• Installed and configured Playwright
• Wrote end-to-end test to validate route rendering and navigation
• Learned how to run, debug and show-report your tests

Next Steps

This is the just the beginning. Playwright can also test:

• API endpoints
• Form submissions
• Dynamic content loading
• Authentication flows
• Responsive behavior

Conclusion

Combining Next.js with Playwright gives you confidence in your app’s behavior. It empowers you to automate UI testing in a way that simulates real user interactions. Even for small apps, this testing workflow can save you from major bugs and regressions.

Source: Read More