[RFC] Vite Plugin for Next.js Component Testing with Vitest

[valentinpalkovic]

Summary

This RFC proposes a new Vite plugin, vite-plugin-nextjs, to enable component testing for Next.js components within a Vitest environment. This plugin aims to leverage Vitest's new browser mode, enabling visual component rendering and testing and addressing the limitations of the existing next/jest.js plugin.

Problem Statement

When a React component renders inside Next.js, its behavior can reflect LOTS of context. Obvious context includes things like environment variables and “smart” handling of images, fonts, and various CSS styling systems. Subtle context includes things like the compiler settings that affect the actual output code. In testing, accurately mocking/emulating this context can be the difference between a useful test and false positives/negatives.

The next/jest.js plugin is a solution for mocking a component’s environment. It offers several advantages for mocking components, mainly focusing on non-visual testing environments. However, it has notable limitations:

• It mocks essential parts of a component that are crucial for visual rendering.
• CSS, SASS, and SCSS handling is unsupported.
• Images are ignored.
• next/font is entirely mocked.

These limitations make next/jest.js unsuitable for visual component testing. In contrast, Vitest, with its experimental browser mode, can render components in a natural browser environment, allowing for more comprehensive visual testing and assertions.

Goals

• Provide a Vite plugin that can transpile Next.js components for component/unit testing in a jsdom/real browser environment, supporting the following features and Next.js related packages:
  • next/font
  • next/image
  • next/router
  • next/navigation
  • next/cache
  • next/head
  • next/link
  • CSS/SASS and SCSS handling
  • Automatic loading of environment variables
  • Respecting the user’s Next.js config
  • Setting up Next.js custom SWC transpiler respecting custom SWC options to register experimental SWC plugins
• The plugin can be used with Vite to provide an alternative to @storybook/nextjs' Webpack builder.
• Ensure compatibility with Storybook's portable stories API to facilitate component testing in Vitest. Currently, portable stories are not supported in Next.js with Vitest, only with Jest.
• Support the automation of transforming stories into unit tests interpretable by Vitest, referencing the ongoing RFC: [Storybook RFC #28386]([RFC] Storybook Vitest integration #28386).
• (Optional) Support fast refresh.

Non-goals

• The Vite plugin does not provide mocking wrappers for next/navigation, next/router, or any other API, which requires a React Context setup. Therefore, rendering more complex components that require additional context setup only works inside Storybook as a plugin for Storybook’s Vite builder or when doing tests with Vitest in conjunction with portable stories.
• Next.js’ features that require using Babel instead of SWC will not be supported. Additionally, the user’s custom Babel settings are also ignored.
• Next.js’ custom SASS/CSS compiler options like those found at https://nextjs.org/docs/app/building-your-application/styling/sass#customizing-sass-options are not supported. Instead, users must rely on Vite’s CSS settings to configure the CSS/SCSS/SASS compilation.

Implementation

Registering the Plugin

To register the vite-plugin-nextjs in vitest.config.ts, the following configuration is proposed:

import { defineConfig } from 'vite';
import nextJs from 'vite-plugin-nextjs';

export default defineConfig({
  plugins: [
    nextJs(),
  ],
  test: {
    environment: 'jsdom',
    // or 'browser' for experimental browser mode
    // browser: {
      // enabled: true,
      // name: 'chrom
    // }
  },
});

Usage

The plugin assumes the following prerequisites:

• Storybook 8.x or higher is used.
• Testing Library is installed.
• Vitest is installed and configured.
• Optional: Vitest's experimental browser mode is enabled.

Prelude: Portable Stories API

Understanding the portable stories API is essential before diving into the implementation. For more information, refer to Portable Stories API Documentation.

Vitest Plugin: Implementation Example

Example of mounting a Next.js component using Testing Library and the portable stories API:

import { test, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import { composeStories } from '@storybook/react';

import * as stories from './Button.stories';

const { Primary, Secondary } = composeStories(stories);

test('renders primary button with default args', () => {
  render(<Primary />);
  const buttonElement = screen.getByText('Text coming from args in stories file!');
  expect(buttonElement).not.toBeNull();
});

test('renders primary button with overridden props', () => {
  render(<Primary>Hello world</Primary>);
  const buttonElement = screen.getByText(/Hello world/i);
  expect(buttonElement).not.toBeNull();
});

The plugin respects CSS, fonts, and images, allowing the component to be displayed visually true to the original in Vitest's browser mode.

When [Storybook RFC #28386](#28386) gets implemented, it will even not be necessary to write dedicated tests via Vitest. Vitest will be able to recognize .stories.js|ts files and transform them on the fly to component tests featured by Vitest.

Deliverables

1. Plugin Codebase: The complete implementation of the vite-plugin-nextjs.
2. Documentation: Detailed usage instructions, including setup and configuration.
3. Examples: Sample projects demonstrating the plugin in action with Storybook and Vitest.
4. Automated Tests: Unit tests for the plugin itself to ensure reliability and maintainability.

Risks

• Compatibility Issues: Potential conflicts with existing Storybook and Next.js configurations.
• Maintenance: Keeping the plugin up-to-date with evolving versions of Next.js, Vitest, and Storybook.

Unresolved Questions

• How will the plugin handle complex Next.js features such as dynamic imports and API routes?
• What level of support will be provided for various CSS-in-JS solutions commonly used with Next.js?
• Are there any additional features or configurations that users might require?

Alternatives considered / Abandoned Ideas

Enhancing next/jest.js: Modifying the existing Jest plugin to support visual testing. This would mean though that we couldn’t provide a solution for the Vitest community.

[shilman]

This is released in 8.3!