clean-typescript-tests

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clean Tests

整洁的测试

T1: Insufficient Tests

T1：测试覆盖不足

Test everything that could possibly break. Use coverage tools as a guide, not a goal.

// Bad - only tests happy path
test("divide", () => {
  expect(divide(10, 2)).toBe(5);
});

// Good - tests edge cases too
test("divide normal", () => {
  expect(divide(10, 2)).toBe(5);
});

test("divide by zero", () => {
  expect(() => divide(10, 0)).toThrow(RangeError);
});

test("divide negative", () => {
  expect(divide(-10, 2)).toBe(-5);
});

测试所有可能出问题的点。将覆盖率工具作为指引，而非目标。

// Bad - only tests happy path
test("divide", () => {
  expect(divide(10, 2)).toBe(5);
});

// Good - tests edge cases too
test("divide normal", () => {
  expect(divide(10, 2)).toBe(5);
});

test("divide by zero", () => {
  expect(() => divide(10, 0)).toThrow(RangeError);
});

test("divide negative", () => {
  expect(divide(-10, 2)).toBe(-5);
});

T2: Use a Coverage Tool

T2：使用覆盖率工具

Coverage tools report gaps in your testing strategy. Don't ignore them.

bash

undefined

覆盖率工具会报告测试策略中的缺口，不要忽视它们。

bash

undefined

Run with coverage

vitest run --coverage

Aim for meaningful coverage, not 100%

undefined

undefined

T3: Don't Skip Trivial Tests

T3：不要跳过简单测试

Trivial tests document behavior and catch regressions. They're worth more than their cost.

// Worth having - documents expected behavior
test("user default role", () => {
  const user = new User("Alice");
  expect(user.role).toBe("member");
});

简单测试可以记录行为并捕获回归问题，它们的价值远超成本。

// Worth having - documents expected behavior
test("user default role", () => {
  const user = new User("Alice");
  expect(user.role).toBe("member");
});

T4: An Ignored Test Is a Question About an Ambiguity

T4：被忽略的测试是对模糊点的疑问

Don't use

test.skip

to hide problems. Either fix the test or delete it.

// Bad - hiding a problem
test.skip("async operation", () => {
  // flaky, fix later
});

// Good - either fix it or document why it's skipped
test.skip("cache invalidation - requires Redis (see CONTRIBUTING.md)", () => {
});

不要用

test.skip

来掩盖问题。要么修复测试，要么删除它。

// Bad - hiding a problem
test.skip("async operation", () => {
  // flaky, fix later
});

// Good - either fix it or document why it's skipped
test.skip("cache invalidation - requires Redis (see CONTRIBUTING.md)", () => {
});

T5: Test Boundary Conditions

T5：测试边界条件

Bugs congregate at boundaries. Test them explicitly.

test("pagination boundaries", () => {
  const items = Array.from({ length: 100 }, (_, i) => i);

  // First page
  expect(paginate(items, 1, 10)).toEqual(items.slice(0, 10));

  // Last page
  expect(paginate(items, 10, 10)).toEqual(items.slice(90, 100));

  // Beyond last page
  expect(paginate(items, 11, 10)).toEqual([]);

  // Page zero (invalid)
  expect(() => paginate(items, 0, 10)).toThrow(RangeError);

  // Empty list
  expect(paginate([], 1, 10)).toEqual([]);
});

漏洞往往集中在边界处，要明确测试这些场景。

test("pagination boundaries", () => {
  const items = Array.from({ length: 100 }, (_, i) => i);

  // First page
  expect(paginate(items, 1, 10)).toEqual(items.slice(0, 10));

  // Last page
  expect(paginate(items, 10, 10)).toEqual(items.slice(90, 100));

  // Beyond last page
  expect(paginate(items, 11, 10)).toEqual([]);

  // Page zero (invalid)
  expect(() => paginate(items, 0, 10)).toThrow(RangeError);

  // Empty list
  expect(paginate([], 1, 10)).toEqual([]);
});

T6: Exhaustively Test Near Bugs

T6：全面测试漏洞相关场景

When you find a bug, write tests for all similar cases. Bugs cluster.

// Found bug: off-by-one in date calculation
// Now test ALL date boundaries
test("month boundaries", () => {
  expect(lastDayOfMonth(2024, 1)).toBe(31); // January
  expect(lastDayOfMonth(2024, 2)).toBe(29); // Leap year February
  expect(lastDayOfMonth(2023, 2)).toBe(28); // Non-leap February
  expect(lastDayOfMonth(2024, 4)).toBe(30); // 30-day month
  expect(lastDayOfMonth(2024, 12)).toBe(31); // December
});

当发现一个漏洞时，为所有类似场景编写测试。漏洞往往会集中出现。

// Found bug: off-by-one in date calculation
// Now test ALL date boundaries
test("month boundaries", () => {
  expect(lastDayOfMonth(2024, 1)).toBe(31); // January
  expect(lastDayOfMonth(2024, 2)).toBe(29); // Leap year February
  expect(lastDayOfMonth(2023, 2)).toBe(28); // Non-leap February
  expect(lastDayOfMonth(2024, 4)).toBe(30); // 30-day month
  expect(lastDayOfMonth(2024, 12)).toBe(31); // December
});

T7: Patterns of Failure Are Revealing

T7：失败模式具有启示性

When tests fail, look for patterns. They often point to deeper issues.

// If all async tests fail intermittently,
// the problem isn't the tests - it's the async handling

当测试失败时，寻找模式。它们通常指向更深层次的问题。

// If all async tests fail intermittently,
// the problem isn't the tests - it's the async handling

T8: Test Coverage Patterns Can Be Revealing

T8：测试覆盖模式具有启示性

Look at which code paths are untested. Often they reveal design problems.

// If you can't easily test a function, it probably does too much
// Refactor for testability

查看哪些代码路径未被测试。它们往往会暴露设计问题。

// If you can't easily test a function, it probably does too much
// Refactor for testability

T9: Tests Should Be Fast Enough To Run

T9：测试应足够快以支持频繁运行

Slow tests don't get run. Keep unit tests fast and isolate slower integration tests so developers can run the right feedback loop intentionally.

// Bad - hits real database
test("user creation", async () => {
  const db = await connectToDatabase(); // Slow!
  const user = await db.createUser("Alice");
  expect(user.name).toBe("Alice");
});

// Good - uses mock or in-memory
test("user creation", async () => {
  const db = new InMemoryDatabase();
  const user = await db.createUser("Alice");
  expect(user.name).toBe("Alice");
});

缓慢的测试不会被频繁执行。保持单元测试快速，将较慢的集成测试隔离出来，以便开发者可以有针对性地运行合适的反馈循环。

// Bad - hits real database
test("user creation", async () => {
  const db = await connectToDatabase(); // Slow!
  const user = await db.createUser("Alice");
  expect(user.name).toBe("Alice");
});

// Good - uses mock or in-memory
test("user creation", async () => {
  const db = new InMemoryDatabase();
  const user = await db.createUser("Alice");
  expect(user.name).toBe("Alice");
});

T10: Prefer Test Data Builders

T10：优先使用测试数据构建器

Use test data builders or small factory helpers when setup objects are large, repeated, or full of irrelevant fields. Builders keep tests focused on the one fact that matters and reduce

as

assertions around incomplete fixtures.

// Bad - noisy fixture hides the behavior under test
const order: Order = {
  id: "order-1",
  status: "paid",
  customerId: "customer-1",
  lineItems: [],
  discounts: [],
  createdAt: new Date("2026-01-01"),
};

// Good - default valid object, test overrides the relevant fact
const order = buildOrder({ status: "paid" });

Inline literals are fine when the shape is tiny and every field matters to the assertion. Avoid broad builders that hide important setup or create invalid domain objects by default.

当测试对象的设置过程繁琐、重复或包含大量无关字段时，使用测试数据构建器或小型工厂工具。构建器可以让测试聚焦于关键事实，并减少针对不完整夹具的

as

断言。

// Bad - noisy fixture hides the behavior under test
const order: Order = {
  id: "order-1",
  status: "paid",
  customerId: "customer-1",
  lineItems: [],
  discounts: [],
  createdAt: new Date("2026-01-01"),
};

// Good - default valid object, test overrides the relevant fact
const order = buildOrder({ status: "paid" });

当对象结构简单且每个字段都与断言相关时，使用内联字面量是没问题的。避免使用会隐藏重要设置或默认创建无效领域对象的通用构建器。

T11: Test Behavior Contracts, Not Incidental Implementation

T11：测试行为契约，而非偶然实现细节

Tests should fail when behavior breaks, not when harmless implementation choices change. Assert public outputs, state transitions, side effects at boundaries, interactions, and other observable outcomes. Avoid tests that only lock in private helper calls, intermediate data shape, algorithm steps, ordering of internal operations, or other details that can change without changing the contract.

Implementation-detail assertions are appropriate only when the detail is the contract, protects against a real bug, or covers a boundary where there is no better observable signal.

测试应在行为被破坏时失败，而非在无害的实现选择变更时失败。断言公共输出、状态转换、边界处的副作用、交互以及其他可观察结果。避免仅锁定私有辅助函数调用、中间数据结构、算法步骤、内部操作顺序或其他无需改变契约即可变更的细节。

只有当细节本身就是契约、能防范真实漏洞，或在没有更好可观察信号的边界场景下，针对实现细节的断言才是合适的。

Test Organization

测试组织

F.I.R.S.T. Principles

F.I.R.S.T. 原则

Fast: Tests should run quickly
Independent: Tests shouldn't depend on each other
Repeatable: Same result every time, any environment
Self-Validating: Pass or fail, no manual inspection
Timely: Written before or with the code, not after

Fast：测试应快速运行
Independent：测试之间不应相互依赖
Repeatable：在任何环境下每次运行都得到相同结果
Self-Validating：通过或失败，无需人工检查
Timely：在代码编写前或同时编写，而非事后

One Concept Per Test

每个测试对应一个概念

Multiple assertions are acceptable when they verify one behavior. Split the test when assertions describe different concepts, state transitions, or responsibilities.

// Bad - testing multiple things
test("user", () => {
  const user = new User("Alice", "alice@example.com");
  expect(user.name).toBe("Alice");
  expect(user.email).toBe("alice@example.com");
  expect(user.isValid()).toBe(true);
  user.activate();
  expect(user.isActive).toBe(true);
});

// Good - one concept each
test("user stores name", () => {
  const user = new User("Alice", "alice@example.com");
  expect(user.name).toBe("Alice");
});

test("user stores email", () => {
  const user = new User("Alice", "alice@example.com");
  expect(user.email).toBe("alice@example.com");
});

test("new user is valid", () => {
  const user = new User("Alice", "alice@example.com");
  expect(user.isValid()).toBe(true);
});

test("user can be activated", () => {
  const user = new User("Alice", "alice@example.com");
  user.activate();
  expect(user.isActive).toBe(true);
});

当多个断言验证同一行为时是可接受的。当断言描述不同概念、状态转换或职责时，应拆分测试。

// Bad - testing multiple things
test("user", () => {
  const user = new User("Alice", "alice@example.com");
  expect(user.name).toBe("Alice");
  expect(user.email).toBe("alice@example.com");
  expect(user.isValid()).toBe(true);
  user.activate();
  expect(user.isActive).toBe(true);
});

// Good - one concept each
test("user stores name", () => {
  const user = new User("Alice", "alice@example.com");
  expect(user.name).toBe("Alice");
});

test("user stores email", () => {
  const user = new User("Alice", "alice@example.com");
  expect(user.email).toBe("alice@example.com");
});

test("new user is valid", () => {
  const user = new User("Alice", "alice@example.com");
  expect(user.isValid()).toBe(true);
});

test("user can be activated", () => {
  const user = new User("Alice", "alice@example.com");
  user.activate();
  expect(user.isActive).toBe(true);
});