Testing Server Actions in Isolation

A route handler test still constructs a Request. A server action needs less than that: it is an async function whose argument is a FormData — a standard global in Node 18+ — and whose return value must be serializable across the React server boundary. Nothing about that signature requires React, a browser, or a running server, so the test is almost anticlimactic:

// app/items/actions.ts
'use server'
import { z } from 'zod'

const schema = z.object({
  title: z.string().trim().min(3, 'Title is too short'),
  qty: z.coerce.number().int().positive(),
})

export type AddState = { ok: boolean; id?: string; errors?: Record<string, string> }

export async function addItem(_prev: AddState, formData: FormData): Promise<AddState> {
  const parsed = schema.safeParse(Object.fromEntries(formData))
  if (!parsed.success) {
    return { ok: false, errors: Object.fromEntries(
      parsed.error.issues.map((i) => [i.path[0], i.message]),
    ) }
  }
  const id = await createItem(parsed.data)
  revalidatePath('/items')
  return { ok: true, id }
}

import { it, expect, vi } from 'vitest'
import { addItem } from './actions'

it('creates an item and returns its id', async () => {
  vi.mocked(createItem).mockResolvedValue('item_9')

  const fd = new FormData()
  fd.set('title', '  Slate Mug  ')
  fd.set('qty', '3')

  expect(await addItem({ ok: false }, fd)).toEqual({ ok: true, id: 'item_9' })
})

Why this works is worth stating precisely, because it explains both the power and the trap. The 'use server' directive is a build-time marker: the bundler extracts the export into an RPC endpoint for the browser to call. During vitest run no bundler runs, so the export is exactly what it looks like — an async function you can import and await. The directive changes how production consumes the module, not what the module is.

That also reveals the trap. Serialization is enforced at the RPC boundary, not inside your test process. An action that returns { ok: true, createdAt: new Date() } passes a direct test and then throws in production, because Date crosses the wire as {} — or the reverse, depending on the path. A direct test cannot see that; you cover it once at a higher layer (see End-to-End Tests with Playwright) and, better, keep the returned state to strings, numbers, booleans, and plain objects by habit.

FormData mirrors what a real form posts, including the details people forget:

const fd = new FormData()
fd.set('title', 'Slate Mug')   // text fields — strings, even numeric ones
fd.set('qty', '3')             // the server must coerce '3' → 3
fd.append('tags', 'ceramic')   // repeated keys need append(), not set()
fd.append('tags', 'gift')

Because inputs are always strings on the wire, z.coerce.number() in the schema is not optional — it is the difference between the test passing and the deployed action rejecting qty: '3'. Object.fromEntries(formData) collapses repeated keys, so multi-value fields must be read with formData.getAll('tags'); a test with a single tag will not surface that.

Two escape hatches behave exactly as they do in route handlers: redirect('/items') and notFound() work by throwing, so they appear in a test as a rejection, not a returned state:

await expect(publishItem(validForm()))
  .rejects.toMatchObject({ digest: expect.stringContaining('NEXT_REDIRECT') })

Keep the two categories separate in your head — thrown control flow (redirect, notFound) versus returned data (validation errors, success payloads) — because only the second shows up in the state you assert, and mixing them up is why an action test suddenly reports an unhandled error.

State-first actions (the useActionState shape, _prev plus formData) take one extra line of setup: pass a previous state explicitly. Call the previous-state argument what it is — the initial state the form would render with — and the test reads like the reducer it is driving.

The returned state is the action's public API, so the tests should walk every branch a form can produce. Four branches exist in almost every create-style action, and each one maps to input you can construct:

Each row needs exactly two doubles: the database module and the session lookup.

const { createItem, getSession } = vi.hoisted(() => ({
  createItem: vi.fn(),
  getSession: vi.fn(),
}))

vi.mock('@/lib/db', () => ({ createItem }))
vi.mock('@/lib/auth', () => ({ getSession }))
vi.mock('next/cache', () => ({ revalidatePath: vi.fn() }))

import { revalidatePath } from 'next/cache'
import { addItem } from './actions'

afterEach(() => vi.clearAllMocks())

it('rejects a title under three characters without touching the database', async () => {
  getSession.mockResolvedValue({ user: { id: 'u1' } })
  const fd = new FormData()
  fd.set('title', 'x')
  fd.set('qty', '1')

  const state = await addItem({ ok: false }, fd)

  expect(state.errors).toEqual({ title: 'Title is too short' })
  expect(createItem).not.toHaveBeenCalled()
  expect(revalidatePath).not.toHaveBeenCalled()
})

it('rejects anonymous callers before any insert', async () => {
  getSession.mockResolvedValue(null)
  const state = await addItem({ ok: false }, validForm())
  expect(state).toMatchObject({ code: 'unauthorized' })
  expect(createItem).not.toHaveBeenCalled()
})

Three details carry the value. The negative assertions — expect(createItem).not.toHaveBeenCalled() — are what make the validation test meaningful: without them, an action that skips validation and fails later at the database would still "pass" a test that only checked the returned error shape. The vi.hoisted factory exists because vi.mock runs above your imports; a top-level const referenced by the factory throws Cannot access 'createItem' before initialization. And mocking next/cache lets you assert revalidatePath('/items') — revalidation is observable behavior, not an implementation detail, and forgetting it is the classic "list doesn't refresh after add" bug.

Where do you stop stubbing? At the I/O edge only: the DB client, the session lookup, the mailer. Mocking your own validation helpers or the schema would assert the mock's behavior instead of the action's — the same rule from Testing Route Handlers, one layer over. The schema must run for real, because schema-plus-branch is precisely what this test exists to protect.

One failure branch deserves special handling: database errors that are not validation errors. A unique-constraint violation arrives as an exception (P2002 from Prisma, a 23505 code from Postgres) and your action catches it to produce the friendly conflict message. Test it by rejecting the mock:

it('maps a unique-violation to a field error', async () => {
  createItem.mockRejectedValue(Object.assign(new Error('duplicate'), { code: 'P2002' }))
  const state = await addItem({ ok: false }, validForm())
  expect(state.errors.title).toMatch(/already exists/i)
})

Branches like this one — exception → user-facing message — never appear in a happy-path test, and a direct invocation makes them a five-line case instead of a staging reproduction.

One assertion ties the form to the storage layer together: the payload handed to the database.

expect(createItem).toHaveBeenCalledWith({ title: 'Slate Mug', qty: 3 })

That single line proves three transformations at once — the trim() ran, the string '3' was coerced to the number 3, and stray form fields never reached the insert. The returned state says nothing about any of them: { ok: true, id } looks identical whether the row was written with padded whitespace or the wrong type, which is exactly how a "works in the UI, wrong in the database" bug survives every shallow test.

Direct invocation proves the action's logic. It says nothing about the machinery around it, and the machinery is where several production failures live. Being explicit about the gap is what keeps the test suite honest.

Wiring. A common production bug: the action is correct, but the form never passes formData — someone wrote onClick={() => addItem()} instead of binding the form action, so every submit posts an empty FormData and validation fails. A direct test with a hand-built FormData cannot see it. The component-level version closes the gap while keeping the action mocked:

const action = vi.fn().mockResolvedValue({ ok: false, errors: { title: 'too short' } })

render(
  <ActionStateForm action={action} />,   // <form action={formAction}> via useActionState
)

await user.type(screen.getByLabelText('Title'), 'x')
await user.click(screen.getByRole('button', { name: 'Add item' }))

expect(action).toHaveBeenCalledWith(expect.anything(), expect.any(FormData))
expect(await screen.findByRole('alert')).toHaveTextContent(/too short/i)

That asserts the plumbing — formData arrives, errors from the returned state render into the alert, the button disables while pending — all without a server. If the disabled state comes from useFormStatus, drive it the same way the component layer pins loading states: an action stub that never resolves holds the form in its pending branch deterministically.

Progressive enhancement. Next wires server actions into real HTML form submissions: with JavaScript disabled, the form still posts and the action still runs on the server. A jsdom component test never exercises that path, and neither does a direct invocation. One Playwright test does:

test('adding an item works with JavaScript disabled', async ({ browser }) => {
  const context = await browser.newContext({
    javaScriptEnabled: false,
    storageState: '.auth/user.json',
  })
  const page = await context.newPage()
  await page.goto('/items/new')
  await page.getByLabel('Title').fill('Slate Mug')
  await page.getByRole('button', { name: 'Add item' }).click()
  await expect(page.getByText('Slate Mug')).toBeVisible()
  await context.close()
})

That protects the failure mode where a onClick handler quietly replaces the form action and the no-JS path dies without anyone noticing.

Serialization. The direct test runs in plain Node, so new Date(), Map, and class instances sail through where the RPC boundary would reject them. The cheapest insurance is a single test that round-trips the state through structuredClone, the same mechanism React uses:

const state = await addItem({ ok: false }, validForm())
expect(() => structuredClone(state)).not.toThrow()

It does not replace one real end-to-end submit, but it catches the Date-in-state mistake at test speed.

Auth and origin checks. Server Actions in production verify the request's Origin against the Host header and reject cross-site posts; middleware may gate the route before the action is ever dispatched. Neither layer exists in a direct call — by design, since the action is just a function there. That is the argument for one end-to-end test that starts at the browser: log in, submit the real form over the wire, and observe the revalidated list. End-to-End Tests with Playwright builds exactly that, webServer config and session reuse included.

The practical allocation: direct tests for every branch (fast, dozens of them), a component test for the wiring, and one E2E per critical action for serialization, origin checks, and middleware. Teams that skip the middle layer end up debugging useActionState regressions in staging; teams that skip the last one discover the origin check when a customer's embedded iframe breaks checkout.