---
title: "Testing Your Application"
description: "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,..."
last_updated: "2026-09-23T10:57:21.239757+00:00"
canonical_url: "https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/configuration/testing-your-application"
---

## Overview

### Overview

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. 

---

## Setting Up and Running Tests with Playwright

### Overview

Next.js includes a dedicated command to set up and run tests using **Playwright**, a modern end-to-end testing framework for web applications.

### Prerequisites and Execution

To use Playwright with Next.js testing commands, your project must enable the test proxy experimental configuration option in your configuration file:

```javascript
// 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:

```bash
npx next experimental-test
```

Supported 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.

---

## Instant Navigation Testing

### Overview

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.

### Using the Instant Navigation Helper

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.

```typescript
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.

---

## Setting Up and Running Tests with Jest

### Overview

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.

### Configuring Jest

To set up Jest in your application, create a configuration file at your project root using `next/jest`:

```javascript
// 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)
```

---

## Workflow and Testing Utilities Reference

The following table summarizes key packages, tools, and configurations available for testing your application:

| Tool / Package | Purpose | Configuration / Command |
| :--- | :--- | :--- |
| **Playwright** | End-to-end browser testing | `npx next experimental-test` |
| **Jest** | Unit and integration testing | `next/jest` wrapper |
| **@next/playwright** | Testing utilities (e.g., instant navigation) | Imported in test files |

> [!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.

## Related

- [Error Handling Debugging](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/troubleshooting/error-handling-debugging)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/llms.txt) for all pages in this wiki.