Skip to main content

Next.js Testing Overview

Testing is a critical part of building reliable and maintainable Next.js applications. In this comprehensive guide, we'll explore the fundamentals of testing in Next.js, the different types of tests you can write, and the tools that make testing easier.

Introduction to Testing in Next.js​

Testing ensures that your application works as expected and helps prevent regressions when making changes. Next.js applications can be tested at different levels using various testing methodologies and tools.

As a React-based framework, Next.js benefits from the rich testing ecosystem available to React applications, with some additional considerations for Next.js-specific features like server-side rendering (SSR), API routes, and static site generation (SSG).

Why Testing Matters​

Before diving into the specifics, let's understand why testing is so important:

  • Prevents bugs and regressions: Tests help catch issues before they reach production
  • Documents code behavior: Tests serve as living documentation of how your code should work
  • Enables refactoring: With good tests, you can confidently make changes to your codebase
  • Improves code quality: Writing testable code often leads to better architecture
  • Increases development speed: Automated tests save time compared to manual testing

Types of Tests for Next.js Applications​

Unit Tests​

Unit tests focus on testing individual functions, components, or modules in isolation. They are fast to run and help ensure that small pieces of your application work correctly.

javascript
// Example unit test for a utility function
import { formatCurrency } from '../utils/formatters';

describe('formatCurrency', () => {
  it('formats a number as USD currency', () => {
    // Input
    const amount = 1234.56;
    
    // Expected output
    const expected = '$1,234.56';
    
    // Test
    expect(formatCurrency(amount)).toBe(expected);
  });
});

Component Tests​

Component tests verify that your React components render and behave correctly. With Next.js, you need to consider both client-side and server-rendered components.

jsx
// Example component test using React Testing Library
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import Counter from '../components/Counter';

describe('Counter Component', () => {
  it('increments the count when button is clicked', async () => {
    // Render the component
    render(<Counter initialCount={0} />);
    
    // Verify initial state
    expect(screen.getByText('Count: 0')).toBeInTheDocument();
    
    // Simulate a user clicking the button
    await userEvent.click(screen.getByRole('button', { name: /increment/i }));
    
    // Verify the new state
    expect(screen.getByText('Count: 1')).toBeInTheDocument();
  });
});

Integration Tests​

Integration tests check how different parts of your application work together. In Next.js, this might include testing data fetching, routing, or form submissions.

jsx
// Example integration test for a form submission
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import ContactForm from '../components/ContactForm';

describe('ContactForm', () => {
  it('submits form data and shows success message', async () => {
    // Mock API call
    global.fetch = jest.fn(() => 
      Promise.resolve({
        ok: true,
        json: () => Promise.resolve({ success: true })
      })
    );
    
    render(<ContactForm />);
    
    // Fill out the form
    await userEvent.type(screen.getByLabelText(/name/i), 'John Doe');
    await userEvent.type(screen.getByLabelText(/email/i), '[email protected]');
    await userEvent.type(screen.getByLabelText(/message/i), 'Hello world');
    
    // Submit the form
    await userEvent.click(screen.getByRole('button', { name: /submit/i }));
    
    // Verify success message appears
    expect(await screen.findByText(/thanks for your message/i)).toBeInTheDocument();
    
    // Verify API was called with correct data
    expect(fetch).toHaveBeenCalledWith('/api/contact', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        name: 'John Doe',
        email: '[email protected]',
        message: 'Hello world'
      })
    });
  });
});

End-to-End (E2E) Tests​

E2E tests simulate real user interactions in a browser environment, testing your application from start to finish.

javascript
// Example E2E test with Cypress
describe('Authentication Flow', () => {
  it('allows a user to sign in', () => {
    // Visit the home page
    cy.visit('/');
    
    // Navigate to login page
    cy.findByRole('link', { name: /sign in/i }).click();
    
    // Fill out the login form
    cy.findByLabelText(/email/i).type('[email protected]');
    cy.findByLabelText(/password/i).type('password123');
    
    // Submit the form
    cy.findByRole('button', { name: /sign in/i }).click();
    
    // Verify user is logged in
    cy.findByText(/welcome back/i).should('be.visible');
    cy.url().should('include', '/dashboard');
  });
});

Testing Tools for Next.js​

Next.js works with various testing tools. Here are the most commonly used ones:

Jest​

Jest is the most popular JavaScript testing framework and comes pre-configured with Next.js projects created using create-next-app.

bash
# Installing Jest and related packages
npm install --save-dev jest @testing-library/react @testing-library/jest-dom

Basic Jest configuration in jest.config.js:

javascript
const nextJest = require('next/jest');

const createJestConfig = nextJest({
  // Provide the path to your Next.js app to load next.config.js and .env files
  dir: './',
});

// Add any custom config to be passed to Jest
const customJestConfig = {
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  testEnvironment: 'jest-environment-jsdom',
};

// createJestConfig is exported this way to ensure that next/jest can load the Next.js config
module.exports = createJestConfig(customJestConfig);

React Testing Library​

React Testing Library helps test React components in a way that resembles how users interact with them.

jsx
// Example of React Testing Library with Next.js
import { render, screen } from '@testing-library/react';
import HomePage from '../pages/index';

describe('Home Page', () => {
  it('renders the welcome message', () => {
    render(<HomePage />);
    expect(screen.getByRole('heading', { name: /welcome to next\.js/i })).toBeInTheDocument();
  });
});

Cypress​

Cypress is a powerful E2E testing tool that can be used to test Next.js applications.

bash
# Installing Cypress
npm install --save-dev cypress

Example cypress.config.js:

javascript
const { defineConfig } = require('cypress');

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    supportFile: false,
  },
});

Testing-Library/Cypress​

Combines Cypress with Testing Library's user-centric querying methods:

bash
npm install --save-dev @testing-library/cypress

Next.js-Specific Testing Considerations​

Testing Pages with Data Fetching​

Next.js pages often fetch data using getStaticProps, getServerSideProps, or getInitialProps. Here's how to test them:

jsx
// Testing a page with getStaticProps
import { render, screen } from '@testing-library/react';
import BlogPost from '../pages/blog/[slug]';

describe('BlogPost Page', () => {
  it('renders blog post content', () => {
    // Mock props that would be returned from getStaticProps
    const props = {
      post: {
        title: 'Test Blog Post',
        content: 'This is a test blog post content.'
      }
    };
    
    render(<BlogPost {...props} />);
    
    expect(screen.getByRole('heading', { name: 'Test Blog Post' })).toBeInTheDocument();
    expect(screen.getByText('This is a test blog post content.')).toBeInTheDocument();
  });
});

Testing API Routes​

Next.js API routes can be tested by mocking request and response objects:

javascript
import { createMocks } from 'node-mocks-http';
import handler from '../pages/api/hello';

describe('API Route: /api/hello', () => {
  it('returns a greeting message', async () => {
    // Create mock request and response
    const { req, res } = createMocks({
      method: 'GET',
    });
    
    // Call the API handler
    await handler(req, res);
    
    // Check the response
    expect(res._getStatusCode()).toBe(200);
    expect(JSON.parse(res._getData())).toEqual({ 
      message: 'Hello World' 
    });
  });
});

Best Practices for Testing Next.js Applications​

  1. Test components in isolation: Focus on testing one component at a time.

  2. Mock external dependencies: Use Jest's mocking capabilities for APIs, databases, etc.

  3. Test both client and server-side functionality: Next.js applications run on both sides.

  4. Use realistic test data: Test with data that represents what your application will actually handle.

  5. Test responsiveness: Ensure your components work across different screen sizes.

  6. Implement continuous integration: Run your tests automatically when code is pushed.

Setting Up a Testing Workflow in a Next.js Project​

Here's a step-by-step guide to set up testing in a new Next.js project:

1. Create a Next.js project (if you don't have one)​

bash
npx create-next-app@latest my-tested-app
cd my-tested-app

2. Install testing dependencies​

bash
npm install --save-dev jest @testing-library/react @testing-library/jest-dom @testing-library/user-event jest-environment-jsdom

3. Create Jest configuration files​

Create jest.config.js:

javascript
const nextJest = require('next/jest');

const createJestConfig = nextJest({
  dir: './',
});

const customJestConfig = {
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  testEnvironment: 'jest-environment-jsdom',
  testPathIgnorePatterns: ['<rootDir>/.next/', '<rootDir>/node_modules/'],
};

module.exports = createJestConfig(customJestConfig);

Create jest.setup.js:

javascript
// Import jest-dom testing library
import '@testing-library/jest-dom';

4. Update package.json scripts​

json
"scripts": {
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "lint": "next lint",
  "test": "jest",
  "test:watch": "jest --watch"
}

5. Create your first test​

Create a directory for tests and add a simple test:

bash
mkdir __tests__

Create __tests__/index.test.js:

jsx
import { render, screen } from '@testing-library/react';
import Home from '../pages/index';

describe('Home page', () => {
  it('renders a heading', () => {
    render(<Home />);
    
    const heading = screen.getByRole('heading', {
      name: /welcome to next\.js/i,
    });
    
    expect(heading).toBeInTheDocument();
  });
});

6. Run your tests​

bash
npm test

Real-World Testing Example: Building a Todo App​

Let's consider a simple Todo app built with Next.js and see how we might test various parts of it:

Component Test for TodoItem​

jsx
// __tests__/components/TodoItem.test.jsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import TodoItem from '../../components/TodoItem';

describe('TodoItem', () => {
  const mockTodo = { id: '1', text: 'Learn Testing', completed: false };
  const mockToggleTodo = jest.fn();
  const mockDeleteTodo = jest.fn();

  beforeEach(() => {
    // Reset mock functions
    mockToggleTodo.mockReset();
    mockDeleteTodo.mockReset();
  });

  it('renders the todo text', () => {
    render(
      <TodoItem 
        todo={mockTodo} 
        onToggle={mockToggleTodo} 
        onDelete={mockDeleteTodo} 
      />
    );
    
    expect(screen.getByText('Learn Testing')).toBeInTheDocument();
  });

  it('calls toggle function when checkbox is clicked', async () => {
    render(
      <TodoItem 
        todo={mockTodo} 
        onToggle={mockToggleTodo} 
        onDelete={mockDeleteTodo} 
      />
    );
    
    const checkbox = screen.getByRole('checkbox');
    await userEvent.click(checkbox);
    
    expect(mockToggleTodo).toHaveBeenCalledWith('1');
  });

  it('calls delete function when delete button is clicked', async () => {
    render(
      <TodoItem 
        todo={mockTodo} 
        onToggle={mockToggleTodo} 
        onDelete={mockDeleteTodo} 
      />
    );
    
    const deleteButton = screen.getByRole('button', { name: /delete/i });
    await userEvent.click(deleteButton);
    
    expect(mockDeleteTodo).toHaveBeenCalledWith('1');
  });

  it('shows completed styling when todo is completed', () => {
    const completedTodo = { ...mockTodo, completed: true };
    
    render(
      <TodoItem 
        todo={completedTodo} 
        onToggle={mockToggleTodo} 
        onDelete={mockDeleteTodo} 
      />
    );
    
    const todoText = screen.getByText('Learn Testing');
    expect(todoText).toHaveClass('completed');
  });
});

API Route Test​

javascript
// __tests__/api/todos.test.js
import { createMocks } from 'node-mocks-http';
import handler from '../../pages/api/todos';

describe('Todos API', () => {
  it('creates a new todo', async () => {
    const { req, res } = createMocks({
      method: 'POST',
      body: {
        text: 'Buy milk'
      }
    });
    
    await handler(req, res);
    
    expect(res._getStatusCode()).toBe(201);
    const data = JSON.parse(res._getData());
    expect(data.todo).toHaveProperty('id');
    expect(data.todo.text).toBe('Buy milk');
    expect(data.todo.completed).toBe(false);
  });
  
  it('returns 400 if todo text is missing', async () => {
    const { req, res } = createMocks({
      method: 'POST',
      body: {}
    });
    
    await handler(req, res);
    
    expect(res._getStatusCode()).toBe(400);
    const data = JSON.parse(res._getData());
    expect(data.message).toBe('Todo text is required');
  });
});

E2E Test with Cypress​

javascript
// cypress/e2e/todo.cy.js
describe('Todo Application', () => {
  beforeEach(() => {
    // Reset todo state before each test
    cy.request('POST', '/api/reset-todos');
    cy.visit('/');
  });
  
  it('allows users to add and complete todos', () => {
    // Add a new todo
    cy.get('[data-testid=new-todo-input]').type('Learn Cypress');
    cy.get('[data-testid=add-todo-button]').click();
    
    // Verify todo was added
    cy.get('[data-testid=todo-item]').should('have.length', 1);
    cy.contains('Learn Cypress');
    
    // Mark todo as completed
    cy.get('[data-testid=todo-checkbox]').click();
    
    // Verify todo is marked as completed
    cy.get('[data-testid=todo-text]').should('have.class', 'completed');
    
    // Delete the todo
    cy.get('[data-testid=delete-todo-button]').click();
    
    // Verify todo was removed
    cy.get('[data-testid=todo-item]').should('have.length', 0);
  });
});

Summary​

Testing Next.js applications involves multiple strategies across different levels:

  • Unit tests examine small pieces of code in isolation
  • Component tests verify React components render and behave correctly
  • Integration tests check how parts of your application work together
  • E2E tests simulate real user interactions and workflows

Next.js provides excellent support for testing through its integration with Jest and compatibility with tools like React Testing Library and Cypress. By implementing a comprehensive testing strategy, you can ensure your Next.js applications are reliable, maintainable, and provide a great user experience.

Additional Resources​

Exercises for Practice​

  1. Set up a testing environment in a Next.js project from scratch
  2. Write tests for a simple component that displays user information
  3. Create tests for a Next.js API route that handles form submissions
  4. Write an E2E test for a login flow using Cypress
  5. Test a page that uses getStaticProps to fetch data
  6. Implement tests for a component that uses React context for state management

By working through these exercises, you'll gain practical experience with the various testing strategies and tools available for Next.js applications.


If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)