四个测试逐条读，以及它们的盲区The four tests read line by line, and what they fail to catch
判卷器长什么样，它查什么，它查不到什么。What the grader looks like, what it checks, and what it cannot check.
这一页有什么On this page7
- 01 测试环境是怎么搭起来的How the test setup is put together
- 02 Testing Library 三件套The three main pieces of Testing Library
- 03 getByTestId 和 getByRole：为什么两种都用getByTestId and getByRole: why both are used
- 04 为什么每个 userEvent 都要 awaitWhy every userEvent call needs await
- 05 三个盲区，以及怎么自己补Three blind spots, and how to cover them yourself
- 练习 · 动手做Practice
- 迁移模式Transfer
- 读懂 Testing Library 的三件套：render / screen / userEventRead the three main pieces of Testing Library: render, screen, and userEvent
- 说清 getByTestId 和 getByRole 各在什么时候用Say when to use getByTestId and when to use getByRole
- 知道为什么每个 userEvent 前面都有 awaitKnow why every userEvent call has await in front of it
- 列出这四个测试的三个盲区，以及怎么自己补上List the three blind spots of these four tests, and how to cover them yourself
测试就是判卷器。看懂它 = 知道及格线在哪。而看懂它的盲区 = 知道题目要求里哪些是测试之外还得自己保证的。The tests are the grader. Reading them tells you where the pass line is. Reading their blind spots tells you which requirements you still have to guarantee yourself.
react-notes-app/src/NoteManager.test.tsx四个判卷测试The four tests that decide the marks
react-notes-app/src/NoteManager.test.tsxreact-notes-app/vite.config.tsvitest 配置内联在这里The vitest config is inline here
react-notes-app/vite.config.tsreact-notes-app/vitest.setup.ts引入 jest-dom 断言Brings in the jest-dom assertions
react-notes-app/vitest.setup.ts测试环境是怎么搭起来的How the test setup is put together
三个文件，各管一段。Three files, each responsible for one part.
vite.config.ts —— vitest 的配置内联在 vite 配置里（不是单独的 vitest.config.ts）。 两个关键项：environment: "jsdom"（在 Node 里模拟一个浏览器 DOM，这样 React 才有东西可渲染）、globals: true（让 test /expect 变成全局变量，不用 import）。
vitest.setup.ts —— 只有一行 import "@testing-library/jest-dom"。 它给 expect 加了一批 DOM 专用断言：toBeDisabled()、toHaveTextContent()。没有它，那两个断言方法就不存在。
顺带回答上一门课那个问题：globals: true 让 test 在运行时存在，但 TypeScript 编译时并不知道 —— 这正是 npm run build 报 10 个Cannot find name 'test' 的原因。 要修需要在 tsconfig 里加"types": ["vitest/globals"]， 但题目没让你改配置。
vite.config.ts — the vitest config is inlined into the vite config (there is no separate vitest.config.ts). Two entries matter: environment: "jsdom" (simulate a browser DOM inside Node, so React has something to render into) and globals: true (make test / expect global, no import needed).
vitest.setup.ts — a single line, import "@testing-library/jest-dom". It adds a batch of DOM-specific assertions to expect: toBeDisabled(), toHaveTextContent(). Without it, those two methods do not exist.
While we are here, the answer to that question from the previous module: globals: true makes test exist at runtime, but TypeScript does not know it at compile time — which is exactly why npm run build reports 10 counts of Cannot find name 'test'. Fixing it would mean adding "types": ["vitest/globals"] to tsconfig, and the brief never told you to touch the config.
react-notes-app/vite.config.tsTesting Library 三件套The three main pieces of Testing Library
| 工具 | 作用 | 这个项目里怎么用 |
|---|---|---|
render | 把组件挂载到 jsdom 里 | render(<NoteManager />) —— 每个测试都从顶层组件开始 |
screen | 在渲染结果里查找元素 | getByTestId / getByRole |
userEvent | 模拟真人操作 | type / click / clear |
注意每个测试都 render 的是 NoteManager， 不是单独测 NoteForm。这意味着任何一环断掉都会让测试挂 —— 受控输入没接好、props 名字对不上、handler 写错， 全都表现为「同一个测试失败」。 所以失败时要顺着整条链查，不能只盯一个文件。
| Tool | What it does | How this project uses it |
|---|---|---|
render | Mounts the component into jsdom | render(<NoteManager />) — every test starts from the top-level component |
screen | Finds elements in the rendered output | getByTestId / getByRole |
userEvent | Acts like a real person | type / click / clear |
Notice that every test renders NoteManager, not NoteForm on its own. Which means a break anywhere along the chain fails the test — a controlled input wired wrong, a mismatched prop name, a broken handler all show up as “the same test failed”. So when one fails, trace the whole chain instead of staring at one file.
getByTestId 和 getByRole：为什么两种都用getByTestId and getByRole: why both are used
getByTestId("form-input") —— 按 data-testid 属性找。 最稳，因为 testid 是专门为测试加的，不会因为文案改动而变。代价是它跟实现绑死了 —— 这也是 README 要求「不得修改任何 data-testid」的原因。
getByRole("button", { name: "Delete" }) —— 按「无障碍角色 + 可见名称」找，也就是 「一个按钮，上面写着 Delete」。 这更接近真人的找法（用户是靠看文字找按钮的）。代价是文案变了就找不到。
这个项目里，表单元素用 testid（它们没有可见文字）， 行内的 Edit / Delete 按钮用 role + name（它们没有 testid）。两种方式各自绑定了不同的东西， 所以 testid 和按钮文字都不能改。
另外记一个特性：getBy* 系列找不到就抛错，找到多个也抛错。 后半条解释了为什么测试里每次只放一条数据 —— 两条数据就有两个 Delete 按钮，getByRole 会因为「找到多个」而失败。
getByTestId("form-input") — looks up the data-testid attribute. The steadiest option, because a testid exists purely for the tests and never changes when the wording does. The price is that it is welded to the implementation — which is why the README demands “do not modify any data-testid”.
getByRole("button", { name: "Delete" }) — looks up an accessibility role plus a visible name, i.e. “a button with Delete written on it”. Closer to how a real person searches (users find buttons by reading them). The price is that changed wording breaks it.
In this project the form elements use testids (they have no visible text), and the inline Edit / Delete buttons use role plus name (they have no testid). Each approach binds a different thing, which is why neither the testids nor the button text can change.
One more trait to keep in mind: the getBy* family throws when it finds nothing, and throws when it finds several. The second half explains why the tests only ever add one note — two notes mean two Delete buttons, and getByRole fails with “found multiple”.
为什么每个 userEvent 都要 awaitWhy every userEvent call needs await
userEvent 的每个方法都返回 Promise。 因为它模拟的是真人操作：type("My Title") 会一个字符一个字符地触发keydown / keypress /input / keyup， 每个字符之间还有微小的间隔。
更重要的是：React 的 state 更新和重新渲染是异步批处理的。await 保证「等这次操作引发的所有渲染都结束了」 再往下走。
漏了 await 会怎样？断言会在渲染完成之前执行，看到的是旧界面， 于是报「找不到 My Title」—— 但你的代码其实是对的。这是最容易误导人的一类测试失败。
Every userEvent method returns a Promise, because what it simulates is a real person: type("My Title") fires keydown / keypress / input / keyup one character at a time, with a tiny gap between characters.
More importantly: React batches state updates and re-renders asynchronously. await guarantees that every render this action triggered is finished before you move on.
What happens if you drop the await?The assertion runs before the render lands, sees the old screen, and reports “cannot find My Title” — even though your code is fine. This is the most misleading kind of test failure there is.
三个盲区，以及怎么自己补Three blind spots, and how to cover them yourself
这一段是本节的重点。This section is the most important part of the lesson.
四个测试合起来覆盖了「能不能跑通」， 但漏掉了三条题目明确要求的东西：
| 题目要求 | 为什么测不出 | 自己怎么验 |
|---|---|---|
| Task 2「按 id 移除」 | 只有一条数据，按 title 甚至清空列表都能过 | 加三条同名笔记，删中间那条 |
| Task 3「原位置更新」 | 只有一条数据，谈不上顺序 | 加三条，编辑中间那条，看它还在不在第二行 |
| Task 3「退出编辑模式」 | 提交后没检查表单和按钮状态 | 更新完看按钮是否回到 Add、表单是否清空 |
所以正确的自测流程是两步：
npx vitest run—— 确认没有低级错误（及格线）。npm run dev+ 上面三个手动场景 —— 确认真的满足题面（真正的正确性）。
考场上时间紧，很多人只做第 1 步。而这三条恰好都是 README 明确写了的 —— 出题人是故意的：他想区分「跑通了」和「读懂了」。
Together the four tests cover “does it run”, but they skip three things the brief explicitly asks for:
| What the brief asks | Why the tests miss it | How to check it yourself |
|---|---|---|
| Task 2, “removed by id” | One note only, so filtering by title or even wiping the list passes | Add three same-named notes, delete the middle one |
| Task 3, “update in place” | One note only, so there is no order to speak of | Add three, edit the middle one, see whether it is still on row two |
| Task 3, “leave edit mode” | Nothing checks the form or the button after the submit | After an update, see whether the button is Add again and the form is empty |
So a proper self-check is two steps:
npx vitest run— confirm there are no basic mistakes (the pass mark).npm run devplus the three manual scenarios above — confirm it really satisfies the brief (actual correctness).
Time is tight in the exam, so plenty of people stop after step 1. And all three of these are spelled out in the README — the author did it on purpose: he wants to separate “it runs” from “you read it”.
动手做Get your hands on it
填空只是过渡。真正掌握的标准，是在没有答案的时候从头写出来 —— 所以做完 L2 之后一定要往 L3、L4 走。Filling blanks is a stepping stone. The real bar is writing it from nothing, so once L2 is comfortable, push on to L3 and L4.
下面哪个 handleDelete 能让四个测试全部通过， 但明显违反题目要求？
Which handleDelete below makes all four tests pass while clearly breaking what the task asks for?
你写的 handleSubmitNote 是 setNotes((prev) => [...prev, submittedNote])， 但自己加的测试报「找不到 My Title」。 测试代码是 userEvent.click(btn); expect(list).toHaveTextContent("My Title")。 最可能的原因？
Your handleSubmitNote is setNotes((prev) => [...prev, submittedNote]), but the test you added reports that My Title cannot be found. The test code is userEvent.click(btn); expect(list).toHaveTextContent("My Title"). What is the most likely reason?
现有测试测不出「按 id 删除」。写一个新测试： 添加两条同名笔记，删掉其中一条， 断言另一条还在。
提示：两条数据时页面上有两个 Delete 按钮，getByRole 会因为「找到多个」而抛错 —— 得用 getAllByRole。
The existing tests cannot check the delete by id. Write a new test: add two notes with the same title, delete one of them, and assert that the other is still there.
A note: with two notes there are two Delete buttons on the page, and getByRole throws because it found more than one. Use getAllByRole.
- 添加两条 title 完全相同、content 不同的笔记Add two notes with exactly the same title and different content
- 用 getAllByRole 拿到 Delete 按钮数组，点第一个Use getAllByRole to get the array of Delete buttons, then click the first one
- 断言 notes-list 不再含「内容A」Assert that notes-list no longer holds 内容A
- 断言 notes-list 仍然含「内容B」Assert that notes-list still holds 内容B
- 所有 userEvent 调用都要 awaitPut an await on every userEvent call
看答案之前，先确认你已经自己动手写过一遍。看懂别人的答案和自己写出来，是两种能力。Before you open this, make sure you have written it yourself once. Following someone else's answer and producing your own are two different skills.
换一道题也能用Works on other problems too
考试不会原题重考。真正能带走的是「看到这种信号 → 伸手去拿这个解法」。The exam will not reuse the same question. What you take away is the reflex: see this signal, reach for that solution.
- vitest 配置内联在 vite.config.ts 里；jest-dom 的断言靠 vitest.setup.ts 引入。The Vitest config sits inside vite.config.ts, and the jest-dom assertions are loaded by vitest.setup.ts.
- 四个测试都 render 顶层 NoteManager，所以任何一环断掉都表现为同一个失败。All four tests render the top-level NoteManager, so a break anywhere in the chain shows up as the same failure.
- testid 用于无文字的表单元素，role + name 用于行内按钮 —— 两者都是契约。data-testid is for form elements with no text, and role plus name is for the row buttons. Both are a contract.
- userEvent 都要 await，否则断言跑在重新渲染之前。Every userEvent call needs await, or the assertion runs before the re-render.
- 三个盲区：按 id 删、原位置更新、退出编辑模式。都得手动验证。Three blind spots: deleting by id, updating in place, and leaving edit mode. Check all three by hand.