Getting Started
Core Concepts
Troubleshooting
Testing your Next.js application ensures your features work reliably across different environments and build setups. Next.js provides built-in tools and configuration support for automated testing, allowing you to run end-to-end tests using Playwright and component or unit tests using Jest.
Next.js includes a dedicated command to set up and run tests using Playwright, a modern end-to-end testing framework for web applications.
To use Playwright with Next.js testing commands, your project must enable the test proxy experimental configuration option in your configuration file:
// next.config.js
module.exports = {
experimental: {
testProxy: true,
},
Warning
Running the built-in test command requires experimental.testProxy: true to be enabled in your configuration. If this is missing, the command will exit with an error.
To run your tests, execute the experimental test command through your terminal:
npx next experimental-testSupported test runners: playwright. Sources: packages/next/src/cli/next-test.ts.
If no configuration file for Playwright exists in your project directory when you run the command, Next.js will automatically generate a default configuration file (playwright.config.ts for TypeScript projects or playwright.config.js for JavaScript projects) and prompt you to create your first test.
When using Playwright for end-to-end testing, you can use helper utilities provided by @next/playwright to control navigation behavior, such as running tests with instant navigation enabled.
The instant helper function lets you run a block of test code where navigations render prefetched UI immediately and wait for callbacks to complete before streaming dynamic data.
import { test } from '@playwright/test'
import { instant } from '@next/playwright'
test('my test with instant navigation', async ({ page, baseURL }) => {
await instant(page, async () => {
await page.goto('/dashboard')
// Perform assertions or interactions here
}, { baseURL })
})Note
Nesting instant() calls is not supported. Ensure you await each instant() call fully before starting another.
Next.js provides an integration utility via next/jest to configure Jest automatically for your application, supporting React testing patterns, module path mapping, and asset transforms.
To set up Jest in your application, create a configuration file at your project root using next/jest:
// jest.config.js
const nextJest = require('next/jest')
const createJestConfig = nextJest({
// Provide the path to your Next.js app to load next.config.js and .env files in your test environment
dir: './',
})
/** @type {import('jest').Config} */
const customJestConfig = {
testEnvironment: 'jest-environment-jsdom',
setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
}
module.exports = createJestConfig(customJestConfig)The following table summarizes key packages, tools, and configurations available for testing your application:
Tip
If you are migrating an existing Create React App project to Next.js, code transformations will automatically map your old test scripts to use Jest and update your dependencies accordingly.