Japa 单元测试入门指南（Node.js）

本文依据官方文档整理，未执行运行验证或性能基准。代码片段展示局部用法，业务函数、数据和环境需按项目补齐；版本与配置以所引文档为准。

直接回答：Japa 是一个快速、简洁的 Node.js 测试框架：核心极简、断言直观，功能通过插件按需添加（ AdonisJS 官方测试方案就是它）。 想要比 Jest 更轻、比内置 runner 功能更全的中间选项，Japa 值得一看。

Japa 的特点

• 干净的核心：没有历史包袱，API 设计现代；
• 插件化：断言、覆盖率、API 测试等都按插件装配，要多少装多少；
• TypeScript 友好：一等公民支持。

搭建项目

mkdir japa-demo && cd japa-demo
npm init -y
npm init japa@latest .

在官方脚手架中选择 assert 插件，并确认生成的 bin/test.js 配置了 @japa/assert 的 assert()、测试文件glob和ESM。单装 @japa/runner 不会自动注入 assert。把测试放到匹配的 tests/**/*.spec.js。

第一个测试

import { test } from "@japa/runner";

const add = (a, b) => a + b;

test("两数相加", ({ assert }) => {
  assert.equal(add(1, 2), 3);
});

注册 @japa/assert 插件后 assert 才会由上下文注入，常用方法：equal、deepEqual、isTrue、rejects 等。

运行测试

node bin/test.js     # 脚手架生成的入口

输出简洁，失败时给出清晰的 diff。配置 TypeScript 后直接跑 .ts 测试文件，无需预编译。

Setup 与 Cleanup

test.group("用户服务", (group) => {
  let db;

  group.setup(async () => {
    db = await connectTestDb();
    return () => db.close();   // 返回值即 cleanup 函数
  });

  test("创建用户", async ({ assert }) => {
    const user = await db.createUser({ name: "Ada" });
    assert.equal(user.name, "Ada");
  });
});

group.setup 返回的函数会在该组结束时执行——把清理逻辑写在准备逻辑旁边，是 Japa 很讨喜的一个设计。每条用例可在返回的Test实例链式 .setup(...)，组内统一准备用 group.each.setup(...)。

异步测试

Japa 原生拥抱 Promise：

test("异步获取用户", async ({ assert }) => {
  const user = await fetchUser(1);
  assert.equal(user.id, 1);
});

默认有超时保护，慢测试用 test('name', callback).timeout(5000) 单独放宽，避免整条套件被拖死。

过滤与组织

• test('name', callback).pin()：只跑标记用例；
• test('name', callback).skip(true)：跳过；
• 命令行按文件名/标签过滤；
• test.group 把相关用例组织成组，报告按组缩进展示。

常见问题（FAQ）

Q：Japa 和 Jest 怎么选？
A：Jest 全家桶生态庞大；Japa 采用插件装配方式，性能需按项目验证。AdonisJS 项目默认 Japa 无需纠结；其他 Node 项目看你对"极简"和"生态"的权重。

Q：插件生态够用吗？
A：官方插件覆盖了断言、API 测试（@japa/api-client）、浏览器测试、覆盖率等主流需求；小众场景可自己写插件，成本不高。

Q：能和 Node 内置 runner 混用吗？
A：没必要。两者定位重叠，选一个即可；Japa 的增值在于插件体系与更友好的断言 API。

官方参考

• 官方文档 1
• 官方文档 2
• 官方文档 3
• 官方文档 4
• 官方文档 5
• 官方文档 6
• 官方文档 7

资料核对日期：2026-09-29。

延伸阅读

• Go 单元测试入门指南
• Python unittest 模块入门指南