重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
safe-action-testing by next-safe-action/skills
npx skills add https://github.com/next-safe-action/skills --skill safe-action-testing服务器 actions 是异步函数 — 在测试中直接调用它们:
// src/__tests__/actions.test.ts
import { describe, it, expect, vi } from "vitest";
import { createUser } from "@/app/actions";
describe("createUser", () => {
it("returns user data on valid input", async () => {
const result = await createUser({ name: "Alice", email: "alice@example.com" });
expect(result.data).toEqual({
id: expect.any(String),
name: "Alice",
});
expect(result.serverError).toBeUndefined();
expect(result.validationErrors).toBeUndefined();
});
it("returns validation errors on invalid input", async () => {
const result = await createUser({ name: "", email: "not-an-email" });
expect(result.data).toBeUndefined();
expect(result.validationErrors).toBeDefined();
expect(result.validationErrors?.email?._errors).toContain("Invalid email");
});
it("returns server error on duplicate email", async () => {
// 准备:创建第一个用户
await createUser({ name: "Alice", email: "alice@example.com" });
// 尝试重复创建
const result = await createUser({ name: "Bob", email: "alice@example.com" });
// 如果使用 returnValidationErrors:
expect(result.validationErrors?.email?._errors).toContain("Email already in use");
// 或者如果使用 throw + handleServerError:
// expect(result.serverError).toBe("Email already in use");
});
});
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
import { updatePost } from "@/app/actions";
describe("updatePost", () => {
it("updates the post", async () => {
const postId = "123e4567-e89b-12d3-a456-426614174000";
const boundAction = updatePost.bind(null, postId);
const result = await boundAction({
title: "Updated Title",
content: "Updated content",
});
expect(result.data).toEqual({ success: true });
});
it("returns validation error for invalid postId", async () => {
const boundAction = updatePost.bind(null, "not-a-uuid");
// 绑定参数验证错误会抛出 ActionBindArgsValidationError
await expect(boundAction({ title: "Test", content: "Test" }))
.rejects.toThrow();
});
});
通过创建具有特定中间件链的 actions 来测试中间件行为:
import { describe, it, expect, vi } from "vitest";
import { createSafeActionClient } from "next-safe-action";
import { z } from "zod";
// 模拟身份验证
vi.mock("@/lib/auth", () => ({
getSession: vi.fn(),
}));
import { getSession } from "@/lib/auth";
const authClient = createSafeActionClient().use(async ({ next }) => {
const session = await getSession();
if (!session?.user) throw new Error("Unauthorized");
return next({ ctx: { userId: session.user.id } });
});
const testAction = authClient.action(async ({ ctx }) => {
return { userId: ctx.userId };
});
describe("auth middleware", () => {
it("passes userId to action when authenticated", async () => {
vi.mocked(getSession).mockResolvedValue({
user: { id: "user-1", role: "user" },
});
const result = await testAction();
expect(result.data).toEqual({ userId: "user-1" });
});
it("returns server error when unauthenticated", async () => {
vi.mocked(getSession).mockResolvedValue(null);
const result = await testAction();
expect(result.serverError).toBeDefined();
});
});
使用 React Testing Library 的 renderHook:
import { describe, it, expect, vi } from "vitest";
import { renderHook, act, waitFor } from "@testing-library/react";
import { useAction } from "next-safe-action/hooks";
// 模拟 action
const mockAction = vi.fn();
describe("useAction", () => {
it("starts idle", () => {
const { result } = renderHook(() => useAction(mockAction));
expect(result.current.isIdle).toBe(true);
expect(result.current.isExecuting).toBe(false);
expect(result.current.result).toEqual({});
});
it("executes and returns data", async () => {
mockAction.mockResolvedValue({ data: { id: "1" } });
const { result } = renderHook(() =>
useAction(mockAction, {
onSuccess: vi.fn(),
})
);
act(() => {
result.current.execute({ name: "Alice" });
});
await waitFor(() => {
expect(result.current.hasSucceeded).toBe(true);
});
expect(result.current.result.data).toEqual({ id: "1" });
});
it("handles server errors", async () => {
mockAction.mockResolvedValue({ serverError: "Something went wrong" });
const onError = vi.fn();
const { result } = renderHook(() => useAction(mockAction, { onError }));
act(() => {
result.current.execute({});
});
await waitFor(() => {
expect(result.current.hasErrored).toBe(true);
});
expect(result.current.result.serverError).toBe("Something went wrong");
expect(onError).toHaveBeenCalled();
});
it("resets state", async () => {
mockAction.mockResolvedValue({ data: { id: "1" } });
const { result } = renderHook(() => useAction(mockAction));
act(() => {
result.current.execute({});
});
await waitFor(() => {
expect(result.current.hasSucceeded).toBe(true);
});
act(() => {
result.current.reset();
});
expect(result.current.isIdle).toBe(true);
expect(result.current.result).toEqual({});
});
});
import { flattenValidationErrors, formatValidationErrors } from "next-safe-action";
describe("validation error utilities", () => {
const formatted = {
_errors: ["Form error"],
email: { _errors: ["Invalid email"] },
name: { _errors: ["Too short", "Must start with uppercase"] },
};
it("flattenValidationErrors", () => {
const flattened = flattenValidationErrors(formatted);
expect(flattened.formErrors).toEqual(["Form error"]);
expect(flattened.fieldErrors.email).toEqual(["Invalid email"]);
expect(flattened.fieldErrors.name).toEqual(["Too short", "Must start with uppercase"]);
});
it("formatValidationErrors is identity", () => {
expect(formatValidationErrors(formatted)).toBe(formatted);
});
});
import { vi } from "vitest";
// 模拟 Next.js 导航
vi.mock("next/navigation", () => ({
// Digest 格式是 Next.js 内部实现 — 可能在不同版本间变化
redirect: vi.fn((url: string) => {
throw Object.assign(new Error("NEXT_REDIRECT"), {
digest: `NEXT_REDIRECT;push;${url};303;`,
});
}),
notFound: vi.fn(() => {
throw Object.assign(new Error("NEXT_NOT_FOUND"), {
digest: "NEXT_HTTP_ERROR_FALLBACK;404",
});
}),
}));
遵循项目约定:
packages/next-safe-action/src/__tests__/
├── happy-path.test.ts # 核心正常路径测试
├── validation-errors.test.ts # 验证错误工具
├── middleware.test.ts # 中间件链行为
├── navigation-errors.test.ts # 框架错误处理
├── navigation-immediate-throw.test.ts # 立即导航抛出
├── server-error.test.ts # 服务器错误处理
├── bind-args-validation-errors.test.ts # 绑定参数验证
├── returnvalidationerrors.test.ts # returnValidationErrors 行为
├── input-schema.test.ts # 输入模式测试
├── metadata.test.ts # 元数据测试
├── action-callbacks.test.ts # 服务器级回调
└── hooks-utils.test.ts # Hook 工具
运行测试:
# 所有测试
pnpm run test:lib
# 单个文件
cd packages/next-safe-action && npx vitest run ./src/__tests__/action-builder.test.ts
每周安装次数
62
代码仓库
首次出现
2026年3月6日
安全审计
已安装于
cursor61
gemini-cli61
amp61
github-copilot61
codex61
kimi-cli61
Server actions are async functions — call them directly in tests:
// src/__tests__/actions.test.ts
import { describe, it, expect, vi } from "vitest";
import { createUser } from "@/app/actions";
describe("createUser", () => {
it("returns user data on valid input", async () => {
const result = await createUser({ name: "Alice", email: "alice@example.com" });
expect(result.data).toEqual({
id: expect.any(String),
name: "Alice",
});
expect(result.serverError).toBeUndefined();
expect(result.validationErrors).toBeUndefined();
});
it("returns validation errors on invalid input", async () => {
const result = await createUser({ name: "", email: "not-an-email" });
expect(result.data).toBeUndefined();
expect(result.validationErrors).toBeDefined();
expect(result.validationErrors?.email?._errors).toContain("Invalid email");
});
it("returns server error on duplicate email", async () => {
// Setup: create first user
await createUser({ name: "Alice", email: "alice@example.com" });
// Attempt duplicate
const result = await createUser({ name: "Bob", email: "alice@example.com" });
// If using returnValidationErrors:
expect(result.validationErrors?.email?._errors).toContain("Email already in use");
// OR if using throw + handleServerError:
// expect(result.serverError).toBe("Email already in use");
});
});
import { updatePost } from "@/app/actions";
describe("updatePost", () => {
it("updates the post", async () => {
const postId = "123e4567-e89b-12d3-a456-426614174000";
const boundAction = updatePost.bind(null, postId);
const result = await boundAction({
title: "Updated Title",
content: "Updated content",
});
expect(result.data).toEqual({ success: true });
});
it("returns validation error for invalid postId", async () => {
const boundAction = updatePost.bind(null, "not-a-uuid");
// Bind args validation errors throw ActionBindArgsValidationError
await expect(boundAction({ title: "Test", content: "Test" }))
.rejects.toThrow();
});
});
Test middleware behavior by creating actions with specific middleware chains:
import { describe, it, expect, vi } from "vitest";
import { createSafeActionClient } from "next-safe-action";
import { z } from "zod";
// Mock auth
vi.mock("@/lib/auth", () => ({
getSession: vi.fn(),
}));
import { getSession } from "@/lib/auth";
const authClient = createSafeActionClient().use(async ({ next }) => {
const session = await getSession();
if (!session?.user) throw new Error("Unauthorized");
return next({ ctx: { userId: session.user.id } });
});
const testAction = authClient.action(async ({ ctx }) => {
return { userId: ctx.userId };
});
describe("auth middleware", () => {
it("passes userId to action when authenticated", async () => {
vi.mocked(getSession).mockResolvedValue({
user: { id: "user-1", role: "user" },
});
const result = await testAction();
expect(result.data).toEqual({ userId: "user-1" });
});
it("returns server error when unauthenticated", async () => {
vi.mocked(getSession).mockResolvedValue(null);
const result = await testAction();
expect(result.serverError).toBeDefined();
});
});
Use React Testing Library's renderHook:
import { describe, it, expect, vi } from "vitest";
import { renderHook, act, waitFor } from "@testing-library/react";
import { useAction } from "next-safe-action/hooks";
// Mock the action
const mockAction = vi.fn();
describe("useAction", () => {
it("starts idle", () => {
const { result } = renderHook(() => useAction(mockAction));
expect(result.current.isIdle).toBe(true);
expect(result.current.isExecuting).toBe(false);
expect(result.current.result).toEqual({});
});
it("executes and returns data", async () => {
mockAction.mockResolvedValue({ data: { id: "1" } });
const { result } = renderHook(() =>
useAction(mockAction, {
onSuccess: vi.fn(),
})
);
act(() => {
result.current.execute({ name: "Alice" });
});
await waitFor(() => {
expect(result.current.hasSucceeded).toBe(true);
});
expect(result.current.result.data).toEqual({ id: "1" });
});
it("handles server errors", async () => {
mockAction.mockResolvedValue({ serverError: "Something went wrong" });
const onError = vi.fn();
const { result } = renderHook(() => useAction(mockAction, { onError }));
act(() => {
result.current.execute({});
});
await waitFor(() => {
expect(result.current.hasErrored).toBe(true);
});
expect(result.current.result.serverError).toBe("Something went wrong");
expect(onError).toHaveBeenCalled();
});
it("resets state", async () => {
mockAction.mockResolvedValue({ data: { id: "1" } });
const { result } = renderHook(() => useAction(mockAction));
act(() => {
result.current.execute({});
});
await waitFor(() => {
expect(result.current.hasSucceeded).toBe(true);
});
act(() => {
result.current.reset();
});
expect(result.current.isIdle).toBe(true);
expect(result.current.result).toEqual({});
});
});
import { flattenValidationErrors, formatValidationErrors } from "next-safe-action";
describe("validation error utilities", () => {
const formatted = {
_errors: ["Form error"],
email: { _errors: ["Invalid email"] },
name: { _errors: ["Too short", "Must start with uppercase"] },
};
it("flattenValidationErrors", () => {
const flattened = flattenValidationErrors(formatted);
expect(flattened.formErrors).toEqual(["Form error"]);
expect(flattened.fieldErrors.email).toEqual(["Invalid email"]);
expect(flattened.fieldErrors.name).toEqual(["Too short", "Must start with uppercase"]);
});
it("formatValidationErrors is identity", () => {
expect(formatValidationErrors(formatted)).toBe(formatted);
});
});
import { vi } from "vitest";
// Mock Next.js navigation
vi.mock("next/navigation", () => ({
// Digest formats are Next.js internals — may change across versions
redirect: vi.fn((url: string) => {
throw Object.assign(new Error("NEXT_REDIRECT"), {
digest: `NEXT_REDIRECT;push;${url};303;`,
});
}),
notFound: vi.fn(() => {
throw Object.assign(new Error("NEXT_NOT_FOUND"), {
digest: "NEXT_HTTP_ERROR_FALLBACK;404",
});
}),
}));
Follow the project convention:
packages/next-safe-action/src/__tests__/
├── happy-path.test.ts # Core happy path tests
├── validation-errors.test.ts # Validation error utilities
├── middleware.test.ts # Middleware chain behavior
├── navigation-errors.test.ts # Framework error handling
├── navigation-immediate-throw.test.ts # Immediate navigation throws
├── server-error.test.ts # Server error handling
├── bind-args-validation-errors.test.ts # Bind args validation
├── returnvalidationerrors.test.ts # returnValidationErrors behavior
├── input-schema.test.ts # Input schema tests
├── metadata.test.ts # Metadata tests
├── action-callbacks.test.ts # Server-level callbacks
└── hooks-utils.test.ts # Hook utilities
Run tests:
# All tests
pnpm run test:lib
# Single file
cd packages/next-safe-action && npx vitest run ./src/__tests__/action-builder.test.ts
Weekly Installs
62
Repository
First Seen
Mar 6, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
cursor61
gemini-cli61
amp61
github-copilot61
codex61
kimi-cli61
Vue 3 调试指南:解决响应式、计算属性与监听器常见错误
12,000 周安装