Unit Testing Next.js Server Actions: Covering Form Handling, Authentication, and Error Handling with Vitest

// vitest.config.mts
import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";
import tsconfigPaths from "vite-tsconfig-paths";
 
export default defineConfig({
  plugins: [tsconfigPaths(), react()],
  test: {
    environment: "happy-dom",
    globals: true,
    setupFiles: ["./vitest.setup.ts"],
  },
});

// Common structure for all Action test files
import { describe, it, expect, vi, beforeEach } from "vitest";
 
// Mock declarations always go at the top
vi.mock("@/lib/auth", () => ({ getSession: vi.fn() }));
vi.mock("@/lib/db", () => ({ savePost: vi.fn() }));
// Add the following if the Action uses cookies or headers
vi.mock("next/headers", () => ({ cookies: vi.fn(), headers: vi.fn() }));
// Add the following if the Action calls redirect()
vi.mock("next/navigation", () => ({ redirect: vi.fn() }));
// Add the following if the Action calls revalidatePath/revalidateTag
vi.mock("next/cache", () => ({
  revalidatePath: vi.fn(),
  revalidateTag: vi.fn(),
}));
 
import { getSession } from "@/lib/auth";
 
describe("...", () => {
  beforeEach(() => vi.clearAllMocks()); // Always reset
});

// actions/create-post.ts
"use server";
import { z } from "zod";
import { getSession } from "@/lib/auth";
import { savePost } from "@/lib/db";
import { revalidatePath } from "next/cache";
 
const schema = z.object({
  title: z.string().min(1, "제목을 입력해주세요"),
});
 
export async function createPost(prevState: unknown, formData: FormData) {
  // Auth check runs independently inside the Action, not relying on the component
  const session = await getSession();
  if (!session) return { error: "Unauthorized" };
 
  const result = schema.safeParse({ title: formData.get("title") });
  if (!result.success) return { error: result.error.flatten().fieldErrors };
 
  try {
    await savePost({ title: result.data.title, userId: session.userId });
    revalidatePath("/posts"); // Invalidate cache on success
    return { success: true };
  } catch {
    return { error: "저장에 실패했습니다. 잠시 후 다시 시도해주세요." };
  }
}

// actions/create-post.test.ts
import { describe, it, expect, vi, beforeEach } from "vitest";
import { createPost } from "./create-post";
 
vi.mock("@/lib/auth", () => ({ getSession: vi.fn() }));
vi.mock("@/lib/db", () => ({ savePost: vi.fn() }));
vi.mock("next/cache", () => ({ revalidatePath: vi.fn() }));
 
import { getSession } from "@/lib/auth";
import { savePost } from "@/lib/db";
import { revalidatePath } from "next/cache";
 
describe("createPost — authentication", () => {
  beforeEach(() => vi.clearAllMocks());
 
  it("returns an Unauthorized error for unauthenticated users", async () => {
    vi.mocked(getSession).mockResolvedValue(null);
 
    const fd = new FormData();
    fd.append("title", "Hello");
    const result = await createPost(undefined, fd);
 
    expect(result).toEqual({ error: "Unauthorized" });
    expect(savePost).not.toHaveBeenCalled();
  });
 
  it("saves the post and invalidates the cache for authenticated users", async () => {
    vi.mocked(getSession).mockResolvedValue({ userId: "u1" });
    vi.mocked(savePost).mockResolvedValue({ id: "post-1" });
 
    const fd = new FormData();
    fd.append("title", "Valid Title");
    const result = await createPost(undefined, fd);
 
    expect(result).toEqual({ success: true });
    expect(savePost).toHaveBeenCalledOnce();
    expect(revalidatePath).toHaveBeenCalledWith("/posts");
  });
});

// actions/admin-delete.ts
"use server";
import { getSession } from "@/lib/auth";
import { savePost } from "@/lib/db";
 
export async function adminDeleteAction(prevState: unknown, formData: FormData) {
  const session = await getSession();
  if (!session) return { error: "Unauthorized" };
  if (session.role !== "ADMIN") return { error: "Forbidden" }; // Role check
 
  const targetId = formData.get("targetId") as string;
  try {
    await savePost({ id: targetId, deleted: true, userId: session.userId });
    return { success: true };
  } catch {
    return { error: "삭제에 실패했습니다." };
  }
}

// actions/admin-delete.test.ts
import { describe, it, expect, vi, beforeEach } from "vitest";
import { adminDeleteAction } from "./admin-delete";
 
vi.mock("@/lib/auth", () => ({ getSession: vi.fn() }));
vi.mock("@/lib/db", () => ({ savePost: vi.fn() }));
 
import { getSession } from "@/lib/auth";
import { savePost } from "@/lib/db";
 
describe("adminDeleteAction — role-based access control", () => {
  beforeEach(() => vi.clearAllMocks());
 
  it("denies access for the USER role", async () => {
    vi.mocked(getSession).mockResolvedValue({ userId: "u1", role: "USER" });
 
    const fd = new FormData();
    const result = await adminDeleteAction(undefined, fd);
 
    expect(result).toEqual({ error: "Forbidden" });
    expect(savePost).not.toHaveBeenCalled();
  });
 
  it("processes the request normally for the ADMIN role", async () => {
    vi.mocked(getSession).mockResolvedValue({ userId: "u1", role: "ADMIN" });
    vi.mocked(savePost).mockResolvedValue({ id: "item-123" });
 
    const fd = new FormData();
    fd.append("targetId", "item-123");
    const result = await adminDeleteAction(undefined, fd);
 
    expect(result.success).toBe(true);
  });
});

// actions/signup.test.ts (excerpt)
import { describe, it, expect, vi, beforeEach } from "vitest";
import { signupAction } from "./signup";
 
vi.mock("@/lib/auth", () => ({ getSession: vi.fn() }));
 
import { getSession } from "@/lib/auth";
 
describe("signupAction — email validation", () => {
  beforeEach(() => vi.clearAllMocks());
 
  const cases = [
    { email: "",              expected: "이메일을 입력해주세요" },
    { email: "not-email",     expected: "올바른 이메일 형식이 아닙니다" },
    { email: "valid@test.com", expected: null }, // No error
  ];
 
  it.each(cases)(
    "verifies validation result for email '$email'",
    async ({ email, expected }) => {
      vi.mocked(getSession).mockResolvedValue({ userId: "u1" });
 
      const fd = new FormData();
      fd.append("email", email);
      const result = await signupAction(undefined, fd);
 
      if (expected) {
        expect(result.error?.email?.[0]).toBe(expected);
      } else {
        expect(result.error).toBeUndefined();
      }
    }
  );
});

// actions/create-post.test.ts (error handling + redirect section)
import { describe, it, expect, vi, beforeEach } from "vitest";
import { createPost } from "./create-post";
import { loginAction } from "./login"; // An Action written with the same pattern as createPost
 
vi.mock("@/lib/auth", () => ({ getSession: vi.fn() }));
vi.mock("@/lib/db", () => ({ savePost: vi.fn() }));
vi.mock("next/cache", () => ({ revalidatePath: vi.fn() }));
vi.mock("next/navigation", () => ({ redirect: vi.fn() })); // Must be mocked
 
import { getSession } from "@/lib/auth";
import { savePost } from "@/lib/db";
import { redirect } from "next/navigation";
 
describe("createPost — error handling", () => {
  beforeEach(() => vi.clearAllMocks());
 
  it("returns a user-friendly error message when the DB save fails", async () => {
    vi.mocked(getSession).mockResolvedValue({ userId: "u1" });
    vi.mocked(savePost).mockRejectedValue(new Error("Connection timeout"));
 
    const fd = new FormData();
    fd.append("title", "My Post");
    const result = await createPost(undefined, fd);
 
    expect(result).toEqual({
      error: "저장에 실패했습니다. 잠시 후 다시 시도해주세요.",
    });
  });
});
 
describe("loginAction — redirect", () => {
  beforeEach(() => vi.clearAllMocks());
 
  it("redirects to the dashboard on successful login", async () => {
    vi.mocked(getSession).mockResolvedValue({ userId: "u1" });
 
    const fd = new FormData();
    fd.append("email", "user@test.com");
    fd.append("password", "correct-pass");
 
    await loginAction(undefined, fd);
 
    expect(redirect).toHaveBeenCalledWith("/dashboard");
  });
});