TypeHero 默认测试用例模板解读:Extends 类型断言、向导校验与挑战测试编写实践
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)展示了完整的实时诊断链路:
- 设置编译器选项:
strict: true、target: ESNext、strictNullChecks: true,与挑战求解时的严格模式保持一致; - 注册 Prettier 格式化:通过
PrettierFormatProvider提供文档格式化能力; - 获取 TS Worker:
monaco.languages.typescript.getTypeScriptWorker()取得 TypeScript 语言服务; - 三路诊断:每次内容变化都并行执行
getSemanticDiagnostics(语义诊断)、getSyntacticDiagnostics(语法诊断)、getCompilerOptionsDiagnostics(编译选项诊断),结果写入tsErrors; - Twoslash 内联提示:注册
createTwoslashInlayProvider,在编辑器内渲染// ^?这类 twoslash 类型查询结果; - 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 类型挑战的三个设计要点:
- 断言即测试:
Extends<HelloWorld, ...>把期望约束写进类型层,让编译器成为裁判; - 失败即门槛:向导要求测试先失败,做题者通过让测试转绿完成解题,而 "TEST CASE START" 标记与
isTestsReadonly保证测试对做题者只读; - 模板即骨架:
user.ts/tests.ts的双文件结构、Expect/Equal/Extends断言器家族与官方编写规范(见 challenges/challenge-guidelines.md),都能从这份最小模板出发逐步补齐。
上手编写自己的挑战时,只需复制这套骨架,把 HelloWorld 换成你的目标类型,按主题补充断言数量,再依照官方指南完善 @ts-expect-error 说明与参数顺序即可。