需求怎么写，测试就怎么写。

semantic-assert（意为“语义化的断言”）让你直接断言需求本身。照着产品文档的说法写下陈述，交给一个充当裁判的模型，让你的测试不再依赖 HTML 标签和其中的文字。靠着最新的 Jev 模型，这个过程飞快、可靠，而且便宜得像是免费的。

const alert = page.getByRole("alert");
await alert.waitFor({ state: "visible" });
await judge.expectPageTo("The alert explains how to recover from the error", {
  region: alert,
});

这是 Playwright fixture 的写法。对于 API 响应和其他 JSON，使用与框架无关的核心裁判。

从你多半遇到过的问题开始

产品经理改了个文案……然后 CI 就挂了。 →文案怎么改，都要确认提示框说明了失败原因和恢复步骤。机器人刚承诺了退款？CI 怎么还通过了…… →即使回复里从没出现“退款”二字，也能抓住不该做的承诺。路由变了，标签页标题却没变……测试还全是绿的。 →确认标题、面包屑和页面标题彼此一致，即使页面名称来自用户随手输入的内容。

或者看看这些：

• 零条结果……还是其实还没加载完？ 零行数据可能意味着没有结果、请求还在路上，或者出错了。
• 高亮是加上了……可位置不对。 样式是有了，却挂在了错误的文字上。
• 回答里确实写了“30 天”……可建议还是错的。 关键词对了，结论错了。

工作原理

每条语义断言都遵循同样的三步：

1. 捕获状态。 从你的应用返回 JSON，或者让 Playwright 适配器给页面拍个快照。
2. 写下陈述。 描述用户应该能从这个状态中看出什么。相关的陈述放在同一个请求里发送。
3. 断言结果。 裁判把返回的概率和你的阈值比较，某条陈述没过线，测试就失败。

谁来当裁判？

默认是 Jev，TypeSafe 的第一个System One 模型。Jev 不生成文本。你给它状态和一个是非题或选择题，它返回一个带类型的答案，并且提供可靠的信心值（我们用这个值和阈值比较，来判断测试是否通过）。任何 Provider 实现都可以替代它，参见 provider。

语义断言适合用在哪里

用语义断言检查	用普通断言检查
错误信息是否给出了具体恢复步骤	提示框是否可见
回复是否承诺了退款	精确的订单 ID 和状态码
回复是否回答了客户的问题	数量、总额和算术
高亮段落是否支持某个陈述	精确的 CSS 值和 class 名称

模型的判断是概率性的

你可以在自己的应用里测试一遍，再决定具体针对不同场景用什么样的阈值。

开始使用

跟着快速开始跑通一个检查，然后为 HTML 和浏览器测试加上Playwright 适配器。