TypeHero 默认测试用例模板解读:Extends 类型断言、向导校验与挑战测试编写实践

原创2026-10-10 23:31:481,712 阅读
文章标签:教育前端后端

TypeHero 默认测试用例模板解读:Extends 类型断言、向导校验与挑战测试编写实践

本文围绕 TypeHero 仓库中挑战创建向导(Wizard)的默认测试用例模板 apps/web/src/app/wizard/_components/default-tests.md 展开:先逐行解析其中 Extends<...>() 类型断言与模板字面量类型的用法,再结合向导的表单校验、Monaco 编辑器的实时类型诊断以及仓库内真实挑战的测试文件,完整呈现"编写 → 校验 → 诊断 → 落库"的挑战测试用例实践链路。读完本文,你将能够理解 TypeHero 类型测试的最小骨架,并写出符合官方规范的挑战测试文件。

模板在挑战创建流程中的位置

TypeHero 的挑战创建向导挂在 apps/web/src/app/wizard/page.tsx 路由下,其 UI 主体在 apps/web/src/app/wizard/_components/index.tsx。向导把创建过程拆成 4 个步骤(对应源码中的 STEPS 枚举):

步骤 名称 对应组件 校验 Schema
0 Challenge Card ChallengeCardEditor createExploreCardSchema
1 Description DescriptionEditor createDescriptionSchema
2 Test Cases TestCasesEditor createTestCasesSchema
3 Summary Summary 无

第 2 步"Test Cases"编辑器的初始内容正是来自 default-tests.md。向导在初始化 react-hook-form 表单时,把三个默认模板一次性注入 defaultValues(index.tsx):

defaultValues: {
  name: '',
  difficulty: 'BEGINNER',
  description: DEFAULT_DESCRIPTION,
  tests: DEFAULT_TEST_CASES,
  code: DEFAULT_CHALLENGE_TEMPLATE,
},

其中:

  • DEFAULT_TEST_CASES 来自 ./default-tests.md(即本文主体);
  • DEFAULT_CHALLENGE_TEMPLATE 来自同目录的 default-challenge.md,内容为 type HelloWorld = "",这是留给做题者实现的目标类型起点;
  • DEFAULT_DESCRIPTION 来自 default-description.md,是一段 Markdown 描述模板,提示作者在描述中附上代码片段。

也就是说,default-tests.md 与 default-challenge.md 是一对配套模板:前者描述"HelloWorld 应该长什么样"(期望),后者是"HelloWorld 现在是什么"(起点)。做题者要做的是把 type HelloWorld = "" 改造成能满足测试用例的类型。

逐行解读默认测试用例模板

default-tests.md 全文只有 4 行,却浓缩了 TypeHero 类型测试的两条核心约定:

// TEST CASE START (code in test cases is not editable)
Extends<HelloWorld, `Hello, ${string}`>()

Extends<HelloWorld, `${string}!`>()

第一行:测试区标记注释

// TEST CASE START (code in test cases is not editable) 是测试区域的起始标记,向编辑器与做题者声明:从这里开始的内容属于测试用例,玩家侧不可修改。这与 packages/monaco/src/split-editor.tsx 中 SplitEditor 的 isTestsReadonly 属性(默认 true)相互印证——在正式挑战页面里,测试面板对做题者只读。

第二、四行:Extends 类型断言

Extends<A, B>() 是 TypeHero 测试体系中的核心断言器之一:它在编译期断言类型 A 可以赋值给类型 B(即 A extends B 约束成立),断言不成立时产生类型错误,从而让该条测试"失败"。模板用两条断言从两个维度约束 HelloWorld:

Extends<HelloWorld, `Hello, ${string}`>()   // HelloWorld 必须是 "Hello, xxx" 形式
Extends<HelloWorld, `${string}!`>()         // HelloWorld 必须是 "xxx!" 形式

这里用到的是 TypeScript 模板字面量类型(Template Literal Types)。${string} 在模板字面量类型中代表任意字符串插槽,因此:

  • `Hello, ${string}` 匹配所有以 Hello, 开头的字符串类型;
  • `${string}!` 匹配所有以 ! 结尾的字符串类型。

两条断言合起来,等价于要求 HelloWorld 形如 `Hello, ${string}!`——以 Hello, 开头、以 ! 结尾。而默认起点 type HelloWorld = "" 既不满足前一条(不以 Hello, 开头)也不满足后一条(不以 ! 结尾)。这正是向导设计的核心:默认测试用例在未实现时是"失败"的,迫使作者先写出有判定力的测试,再等待做题者让它变绿。

从源码结构看,Extends 在模板中是直接调用的顶层断言,没有显式 import;而在仓库真实挑战的测试文件中(如 challenges/aot/2023/1/tests.ts),统一从 type-testing 库导入 Expect、Equal 等断言器。两者表达的是同一套"类型级断言"思想:把用户实现的类型放进断言器,交给 TypeScript 编译器在编译期判定对错。

向导如何强制测试用例"先失败"

TypeHero 向导刻意要求:进入 Summary 之前,测试用例必须处于"有类型错误"(失败)状态。这样可以保证作者提交的题目具有真实判定力。这一约束分两层实现。

第一层:Zod 表单校验

createTestCasesSchema(index.tsx)对测试文本做了严格约束:

const testCaseRegex = new RegExp('(?:\n|^)s*(?:Equal|Extends|NotEqual|Expect)<');

const createTestCasesSchema = z.object({
  tests: createNoProfanitySchemaWithValidate((zodString) =>
    zodString
      .min(20, 'The test cases must be longer than 20 characters')
      .max(65536)
      .regex(testCaseRegex, 'You need to have test cases in your challenge'),
  ),
  code: createNoProfanitySchema(),
});

约束要点:

  • 长度:测试内容必须为 20~65536 字符;
  • 断言器存在性:内容必须匹配 testCaseRegex——即每一行需要以 Equal<、Extends<、NotEqual< 或 Expect< 开头。从代码字面看,s* 原样匹配字符 s,正则的真实意图是识别"行首出现断言器调用"这一模式,从而保证测试里确实有类型断言而非随意文本;
  • 内容合规:tests 与 code 都要通过 apps/web/src/utils/antiProfanityZod.ts 提供的反脏话校验;
  • 同一步骤还校验了 challenge 卡片字段(createExploreCardSchema):难度必须是 BEGINNER | EASY | MEDIUM | HARD | EXTREME | EVENT 之一,标题 3~30 字符,简介 10~191 字符,描述 20~65536 字符。

第二层:步骤推进门禁

handleNextClick(index.tsx)在点击 Next 时对当前步骤的 Schema 做 safeParse;当处于 Test Cases 步骤时,额外要求存在类型错误:

if (step === STEPS.TestCases) {
  if (!hasTsErrors) return; // 没有类型错误就不放行
}

其中 hasTsErrors = tsErrors.some((e) => e.length),而 tsErrors 由 TestCasesEditor 在编辑器挂载与内容变化时实时更新。与之对应,TestCasesEditor.tsx 在无类型错误时显示红字提示:

You must have failing test cases

这条"必须失败"的门禁保证了向导产出的是可判定的挑战:做题者修改 user.ts 后,测试用例从红转绿的过程就是解题过程。

编辑器实时类型诊断的原理

TestCasesEditor 基于 @repo/monaco 的 CodeEditor 构建,其 onMount 回调(TestCasesEditor.tsx)展示了完整的实时诊断链路:

  1. 设置编译器选项:strict: true、target: ESNext、strictNullChecks: true,与挑战求解时的严格模式保持一致;
  2. 注册 Prettier 格式化:通过 PrettierFormatProvider 提供文档格式化能力;
  3. 获取 TS Worker:monaco.languages.typescript.getTypeScriptWorker() 取得 TypeScript 语言服务;
  4. 三路诊断:每次内容变化都并行执行 getSemanticDiagnostics(语义诊断)、getSyntacticDiagnostics(语法诊断)、getCompilerOptionsDiagnostics(编译选项诊断),结果写入 tsErrors;
  5. Twoslash 内联提示:注册 createTwoslashInlayProvider,在编辑器内渲染 // ^? 这类 twoslash 类型查询结果;
  6. Vim 状态栏:底部挂载 VimStatusBar(来自 @repo/monaco/vim-mode)。

TsErrors 的类型定义在 packages/monaco/src/index.tsx:

export type TsErrors = [
  SemanticDiagnostics: monaco.languages.typescript.Diagnostic[],
  SyntacticDiagnostics: monaco.languages.typescript.Diagnostic[],
  CompilerOptionsDiagnostics: monaco.languages.typescript.Diagnostic[],
];

这套"三路诊断"机制同样用于做题侧的提交判定:在 packages/monaco/src/index.tsx 的 handleSubmit 中,系统分别对测试文件与用户代码做诊断,只要任一文件存在错误,提交即判定失败;零错误则提示 "Good job!"。两个虚拟文件的路径常量定义在 packages/monaco/src/split-editor.tsx:

export const TESTS_PATH = 'file:///tests.ts';
export const USER_CODE_PATH = 'file:///user.ts';

这与向导里的模板组合完全同构:作者在向导中写的 code(起点类型)对应 user.ts,写的 tests(断言)对应 tests.ts。

从模板走向正式挑战:仓库里的真实测试写法

理解了模板中的 Extends<...>(),再对照仓库内真实挑战的测试文件,就能掌握完整的类型测试写法。

type-testing 断言器家族

真实挑战测试通常从 type-testing 导入断言器,例如 challenges/blank/tests.ts:

import { Expect, Equal } from 'type-testing';

challenges/keyof/tests.ts 则展示了"错误测试"的写法——用 @ts-expect-error 断言某次调用必须报错:

// should error for artists that are not part of the original
// @ts-expect-error
getCasetteCount('Red Hot Chili Peppers')

不同断言器的分工:

  • Equal<A, B>:要求两个类型完全相等(双向 extends 都成立);
  • Extends<A, B>:只要求 A 可赋值给 B(单向约束),适合模板字面量、泛型约束这类"范围型"断言;
  • Expect<Equal<A, B>>、Expect<Extends<A, B>>:把断言包进 Expect,语义更显式;
  • NotEqual:要求两个类型不相等。

默认模板选择 Extends 而非 Equal,正是因为 HelloWorld 的期望形态是一个"范围"(Hello, 开头 + ! 结尾),而不是某个确定的字面量——用 Equal 写死反而会锁死解题空间。

官方指南中的测试编写规范

仓库根目录的 challenges/challenge-guidelines.md 是提交挑战的官方规范,与测试用例直接相关的条款包括:

  • Expect<Equal< 的参数顺序:第一个参数必须是"用户写的类型",第二个才是期望值:
// ✅ Do
type test_TheCoolestCarEverMade = Expect<Equal<TheCoolestCarEverMade, 'Toyota Corolla'>>;

// ❌ Don't
type test_TheCoolestCarEverMade = Expect<Equal<'Toyota Corolla', TheCoolestCarEverMade>>;
  • 避免类型元组:不要把多条断言塞进一个 tuple(如 type tests = [Expect<...>, ...]),应写成平铺的 type test_xxx = Expect<...>,否则当某一条失败时用户很难单独调试;
  • 说明错误原因:使用 @ts-expect-error 时补一句注释,说明该调用为什么应当报错。

user.ts 与 tests.ts 的配套

每个挑战目录都同时包含 user.ts 与 tests.ts。例如 challenges/blank/user.ts 的起点是 type XYZ = unknown;,对应地 challenges/blank/tests.ts 用断言器校验 XYZ;challenges/blank 目录下还有 metadata.json、prompt.md、tsconfig.json 等配套文件。这种"起点未知、测试期望"的结构,与向导里 type HelloWorld = "" + Extends<HelloWorld, ...> 的模板组合完全同构——向导生成的正是这份规范布局的最小骨架,照着这个骨架填充即可产出符合仓库规范的新挑战。

提交链路:模板表单如何落库

完成全部步骤后,onSubmit(index.tsx)调用 Server Action create.action.ts 的 uploadChallenge 落库:

export async function uploadChallenge(data: CreateChallengeSchema, isUserACreator: boolean) {
  const session = await auth();
  if (!session?.user) {
    throw new Error('Unauthorized');
  }
  return prisma.challenge.create({
    data: {
      ...data,
      slug: data.name.toLowerCase().replace(/ /g, '-'),
      userId: session.user.id,
      ...(isUserACreator ? { status: 'ACTIVE' } : {}),
    },
    select: { id: true },
  });
}

要点:

  • 必须登录,否则抛出 Unauthorized;
  • slug 由挑战标题小写化并把空格替换为 - 生成;
  • 若当前用户已拥有 CREATOR 角色(isUserACreator),挑战直接以 ACTIVE 状态上线;普通用户提交则不带状态字段,进入社区审核流程。这与 Summary.tsx 的文案一致——创作者看到 "Submit it to share with the community",普通用户看到 "Submit it to the community for review";
  • 提交成功后,创作者跳转到 /challenge/${id} 预览新挑战,普通用户回到 /explore。

小结:从 4 行模板到完整类型测试体系

回到 default-tests.md 的 4 行内容,它实际上浓缩了 TypeHero 类型挑战的三个设计要点:

  1. 断言即测试:Extends<HelloWorld, ...> 把期望约束写进类型层,让编译器成为裁判;
  2. 失败即门槛:向导要求测试先失败,做题者通过让测试转绿完成解题,而 "TEST CASE START" 标记与 isTestsReadonly 保证测试对做题者只读;
  3. 模板即骨架:user.ts/tests.ts 的双文件结构、Expect/Equal/Extends 断言器家族与官方编写规范(见 challenges/challenge-guidelines.md),都能从这份最小模板出发逐步补齐。

上手编写自己的挑战时,只需复制这套骨架,把 HelloWorld 换成你的目标类型,按主题补充断言数量,再依照官方指南完善 @ts-expect-error 说明与参数顺序即可。

登录后查看全文
typehero