Next.js App Router RSC Test Environment Separation Strategy by Component Type with Vitest

I remember spending a long time scratching my head wondering "why won't this render?" when I first tried to test RSCs using the traditional Jest + jsdom approach. In hindsight, the reason was obvious. RSCs are designed to run only on the server, not in the browser, so they are fundamentally incompatible with the browser environment that jsdom simulates.

After reading this article, developers building with Next.js App Router will be able to decide which Vitest environment to use for each type of RSC. We'll walk through synchronous RSCs, asynchronous RSCs, and the experimental vitest-plugin-rsc, all with working code examples. The key is environment separation — attempting to test server components and client components in the same environment is where most problems begin.

If you're already using Next.js App Router and have experience writing tests with RTL or Playwright, this article connects directly to that knowledge. We won't cover what RSC itself is — we focus on test environment configuration.

Core Concepts

Why RSCs Break Traditional Testing Approaches

RSCs run exclusively in the Node.js server runtime. They can directly query databases or call APIs using async/await, and their code is never sent to the client because it's not included in the bundle. This design provides performance benefits, but from a testing perspective it's a headache.

When you try to render() an RSC with environment: 'jsdom', React attempts to execute the server component in a client environment, triggering a cascade of unexpected errors. The solution is proper environment separation, and the strategy differs by component type.

Strategy by Component Type — The Big Picture First

The most common mistake in practice is ignoring this table and trying to test all components in the same environment.

How the "use client" Boundary Affects Testing

// ServerComponent.tsx — RSC (runs only on server, no "use client")
export default async function ServerComponent() {
  const data = await db.query('SELECT * FROM posts')
  return <PostList posts={data} />
}
 
// PostList.tsx — Client Component
'use client'
export default function PostList({ posts }) {
  const [selected, setSelected] = useState(null)
  // ...
}

The "use client" boundary is the dividing line between server and client execution in the RSC tree. The key is to think of your test environments as divided along this same boundary.

Practical Application

Synchronous RSC: Validating in a node Environment with renderToStaticMarkup

A pure server component that only receives props and renders without any data fetching is the simplest case. There's one important caveat here. When you set environment: 'node', there is no DOM, so you cannot use @testing-library/react's render() as-is. RTL uses react-dom internally, and react-dom requires a document object. I didn't know this at first and was caught off guard by the "document is not defined" error when I tried using render() directly.

Instead, using renderToStaticMarkup from react-dom/server lets you validate against an HTML string without needing a DOM.

// vitest.config.ts
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
 
export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'node', // Pure Node.js environment without DOM
  },
})

// UserCard.tsx — Synchronous RSC (no 'use client', runs on server only)
export default function UserCard({ name, role }: { name: string; role: string }) {
  return (
    <div>
      <h2>{name}</h2>
      <span>{role}</span>
    </div>
  )
}

// UserCard.test.tsx
import { renderToStaticMarkup } from 'react-dom/server'
import UserCard from './UserCard'
 
test('renders the user name and role', () => {
  const html = renderToStaticMarkup(<UserCard name="Alice" role="Engineer" />)
  expect(html).toContain('Alice')
  expect(html).toContain('Engineer')
})

If you want to configure a different environment per file, you can also add a // @vitest-environment node comment at the top of the test file. This lets you keep the global config as jsdom while running only specific files in node mode.

Asynchronous RSC: Direct await of the Component Function + MSW

Honestly, the first time I saw this pattern I thought "is this really right?" Instead of render(<PostList />), you call the component function directly and render its result — this is a practical workaround born from Vitest's lack of official support for async RSCs. Because MSW intercepts fetch in the Node.js environment, it works without any external API.

// PostList.tsx (Async RSC)
export default async function PostList() {
  const posts = await fetch('/api/posts').then(r => r.json())
  return (
    <ul>
      {posts.length === 0 ? (
        <li data-testid="empty">No posts available</li>
      ) : (
        posts.map((p: { id: number; title: string }) => (
          <li key={p.id}>{p.title}</li>
        ))
      )}
    </ul>
  )
}

// PostList.test.tsx
import { setupServer } from 'msw/node'
import { http, HttpResponse } from 'msw'
import { render, screen } from '@testing-library/react'
import PostList from './PostList'
 
const server = setupServer(
  http.get('/api/posts', () =>
    HttpResponse.json([
      { id: 1, title: 'First Post' },
      { id: 2, title: 'Second Post' },
    ])
  )
)
 
beforeAll(() => server.listen())
afterEach(() => server.resetHandlers())
afterAll(() => server.close())
 
test('renders the list of posts', async () => {
  const jsx = await PostList() // direct await instead of render()
  render(jsx)
  expect(await screen.findByText('First Post')).toBeInTheDocument()
  expect(await screen.findByText('Second Post')).toBeInTheDocument()
})
 
test('shows an empty state message when the list is empty', async () => {
  server.use(
    http.get('/api/posts', () => HttpResponse.json([]))
  )
  const jsx = await PostList()
  render(jsx)
  expect(screen.getByTestId('empty')).toBeInTheDocument()
})

What is MSW (Mock Service Worker)? It's a library that intercepts network requests using a service worker. Since v2, it stably supports fetch interception in Node.js environments, making it usable for server component testing.

Since the JSX obtained from await PostList() requires a DOM the moment it's passed to render(), it's natural to keep environment: 'jsdom' (the default) for this pattern.

vitest-plugin-rsc: An Experimental Approach That Reproduces the RSC Execution Model

This third-party plugin released by the Storybook team enables direct unit testing of RSCs in Vitest. It internally runs a separate react-server environment and react_client environment to more closely reproduce the actual RSC execution model. Because it's still in an experimental stage, approach production adoption with caution.

// ServerComponent.tsx — Plugin test target
export default async function ServerComponent({ title }: { title: string }) {
  return (
    <section>
      <h1>{title}</h1>
      <p>Content rendered on the server.</p>
    </section>
  )
}

// vitest.config.ts
import { defineConfig } from 'vitest/config'
import { vitestPluginRSC } from 'vitest-plugin-rsc'
 
export default defineConfig({
  plugins: [vitestPluginRSC()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: 'chromium' }],
    },
  },
})

// ServerComponent.test.tsx
import { renderServer } from 'vitest-plugin-rsc/testing-library'
import { screen } from '@testing-library/react'
import ServerComponent from './ServerComponent'
 
test('server component renders the correct heading', async () => {
  await renderServer(<ServerComponent title="Hello RSC" />)
  expect(screen.getByRole('heading')).toHaveTextContent('Hello RSC')
})

When you first add this plugin to CI, build times increase noticeably due to the Playwright process spin-up. A practical approach is to use E2E tests to cover the important cases alongside it.

Playwright E2E: Protecting Critical Flows with a Real Environment

When data fetching plays a central role in async RSCs, or when Next.js server APIs like cookies() and headers() are involved, E2E testing is the most realistic option. Since it spins up a real server and accesses it via a browser, you can verify behavior without complex mocking.

// e2e/posts.spec.ts
import { test, expect } from '@playwright/test'
 
test('posts list page renders correctly', async ({ page }) => {
  await page.goto('/posts')
  await expect(page.getByRole('list')).toBeVisible()
  await expect(page.getByRole('listitem').first()).toContainText(/post/i)
})
 
test('redirects to login page when not authenticated', async ({ page }) => {
  await page.goto('/dashboard')
  await expect(page).toHaveURL('/login')
})

Pros and Cons Analysis

Advantages

Disadvantages and Caveats

The Most Common Mistakes in Practice

1. Using RTL render() as-is in environment: 'node' — A pure node environment has no DOM, so react-dom won't work. Thinking "it's a server component so node environment must be right," you change the config and then get hit with "document is not defined." Use renderToStaticMarkup, or keep the jsdom environment and use the await Component() pattern.
2. Using render(<AsyncComponent />) directly on an async RSC — An async component won't work properly in that form. Calling it directly with await AsyncComponent() or using the plugin is the practical approach.
3. Running unit tests without mocking Next.js server APIs — Calling cookies() or headers() inside a component will throw errors in the test environment. This pitfall is hard to avoid because the official Next.js examples omit test environment configuration. Mocking in the form of vi.mock('next/headers', () => ({ cookies: () => ({ get: vi.fn() }) })) is required.

Closing Thoughts

The most counterintuitive point in RSC testing is not the concept of "separating environments" itself, but the fact that you can't use RTL as-is in a node environment. You think "it's a server component, so node environment must be right," you change the config, use render(), and get a DOM error. Once you get past this hurdle, the rest flows more naturally than you'd expect.

Three steps you can try right now:

1. Pick the simplest synchronous RSC you have and write a test for it with renderToStaticMarkup. Install with pnpm add -D vitest @vitejs/plugin-react @testing-library/react @testing-library/jest-dom and set environment: 'node' in vitest.config.ts.
2. If you have async RSCs, install with pnpm add -D msw, intercept fetch with setupServer, and apply the await ComponentFunction() pattern. The kettanaito/nextjs-rsc-testing example is a useful starting point.
3. Writing Playwright E2E coverage for your single most critical path — like login or checkout — combined with Vitest unit tests, creates a robust safety net. If cookies() and headers() mocking feels complex, starting with E2E first is also a valid choice.

References

• Component testing RSCs | Storybook Blog
• storybookjs/vitest-plugin-rsc | GitHub
• Testing with Vitest | Next.js Official Docs
• kettanaito/nextjs-rsc-testing | GitHub
• Running Tests with RTL and Vitest on Async RSCs | Aurora Scharff
• Browser Mode | Vitest Official Docs
• Component Testing | Vitest Official Docs
• Testing Async RSCs with Vitest | pronextjs.dev
• nickserv/rsc-testing | GitHub
• Vitest Introduces Browser Mode as Alternative to JSDOM | InfoQ
• Storybook + Vitest + Next.js RSC Component Testing | Mamezou Developer Portal