由Cerios主演
全面的 Playwright 测试匹配器,用于字符串,数字,日期,阵列,对象,定位器,和页面状态. 用直观的说法简化你的E2E测试 toBeAlphanumeric, (中文(简体) ), toHaveAscendingOrder, (中文(简体) ), toBeInTheFuture,和130+ 更多的匹配者.
特征
- 🎯 130+ 自定义匹配器 ——对所有数据类型进行广泛验证
- 🔤 字符串验证 电子邮件、 URL、 UUID、 字母数、 六进制、 大小写不敏感 等
- 🔢 数字矩阵 分类、统计、范围和模式
- 📅 日期和时间 —— 说
Date,ISO字符串和时间;时区,DST,纳秒精度,持续时间 - 🎨 定位仪 —— DOM 元素验证,文本格式化,计数范围,排序文本,并计算样式
- 🍪 页面状态 重试饼干,
localStorage财务报告和审定财务报表sessionStorage主张 - 📦 对象矩阵 ——分类,独特性,财产鉴定
- 🧺 收藏和函数 阵列成员、对象密钥和条目、承诺和抛出的错误
- 🤖 模糊匹配 ——AI生成文本验证(分离)
@cerios/playwright-expectly-fuzzy软件包) - 💪 类型安全 ——完整类型脚本支持
- ⚡ 轻巧 ——仅要求 Playwright
安装
npm install @cerios/playwright-expectly --save-dev
同伴依赖 : 需求
@playwright/test将安装.
快速启动
建议:单身 tests/support 本地模块 expect
在您自己的项目中创建扩展 Playwright 的共享模块 expect 并捕获返回值,然后再出口。 每个固定文件和 spec 文件导入 test编号 :expect 从本单元开始——从不直接从 @playwright/test。 。 。 .
// tests/support/expect.ts
import "@cerios/playwright-expectly";
import { expectlyMatchers } from "@cerios/playwright-expectly";
import { expect as baseExpect, test as base } from "@playwright/test";
// MUST capture the return value — never call `.extend()` and discard it.
export const expect = baseExpect.extend(expectlyMatchers);
export const test = base;
import { expect, test } from "./support/expect";
test("extended expect example", async ({ page }) => {
expect("[email protected]").toBeValidEmail();
expect([1, 2, 3, 4]).toHaveAscendingOrder();
expect(new Date("2025-01-02")).toBeDateCloseTo(new Date("2025-01-01"), { days: 1 });
await expect(page.locator(".username")).toBeAlphanumeric();
});
抓取返回值是关键细节: 返回值由 .extend(...) 已全部输入 expect 带着期待中的配对者。 期待永远不会超过 Playwright 内置匹配器, 因此 Playwright 自己的匹配器( 包括数字) toBeCloseTo保持工作不变.
独立 expectly
import { expectly } from "@cerios/playwright-expectly";
expectly("[email protected]").toBeValidEmail();
expectly([1, 2, 3, 4, 5]).toHaveAscendingOrder();
expectly(subscription.expiresAt).toBeInTheFuture();
await expectly(page.locator(".username")).toBeAlphanumeric();
与 @cerios/playwright-expectly-fuzzy,或自己的匹配者,通过 mergeExpects()数字 :
import { expectlyMatchers } from "@cerios/playwright-expectly";
import { expectlyFuzzyMatchers } from "@cerios/playwright-expectly-fuzzy";
// tests/support/expect.ts
import { expect as baseExpect, mergeExpects, test as base } from "@playwright/test";
const expectlyExpect = baseExpect.extend(expectlyMatchers);
const fuzzyExpect = baseExpect.extend(expectlyFuzzyMatchers);
export const expect = mergeExpects(baseExpect, expectlyExpect, fuzzyExpect);
export const test = base;
如果您只需要独立的软件包导出, 较短的表单也是有效的 :
import { expectly } from "@cerios/playwright-expectly";
import { expectlyFuzzy } from "@cerios/playwright-expectly-fuzzy";
import { expect as baseExpect, mergeExpects, test as base } from "@playwright/test";
export const expect = mergeExpects(baseExpect, expectly, expectlyFuzzy);
export const test = base;
从 1. x 升级 : 日期匹配符
toBeCloseTo改为toBeDateCloseTo,堕落者setupExpectly()删除(使用tests/support而日期匹配者则在Temperal上重建 精确的日历语义:toBeValidISODate()现在验证YYYY-MM-DD财务报告和审定财务报表toMatchTimeZone()改为:toHaveOffset()编号 :toHaveTimeZone()见 根读取 以移民为例.
可用匹配符
- 字符串 —— 说
toBeValidEmail(), (中文(简体) ),toBeValidUrl(), (中文(简体) ),toBeUUID(), (中文(简体) ),toBeAlphanumeric(), (中文(简体) ),toBeHexadecimal(), (中文(简体) ),toEqualCaseInsensitive(), (中文(简体) ),toEqualIgnoringWhitespace(), (中文(简体) ),toMatchPattern(),还有更多.. 翻译: - 数字矩阵 —— 说
toHaveAscendingOrder(), (中文(简体) ),toHaveAverage(), (中文(简体) ),toBeAllPositive(), (中文(简体) ),toBeMonotonic(),还有更多.. 翻译: - 日期和时间 —— 说
Date,ISO字符串和时间值:toBeWithinLast(), (中文(简体) ),toBeWithinDurationAfter(), (中文(简体) ),toBeSameInstant(), (中文(简体) ),toBeSameDay(), (中文(简体) ),toBeWithinTimeOfDay(), (中文(简体) ),toHaveOffset()时间匹配器,加parseISO*()编号 :isISO*()并键入 ISO 字符串 - 翻译: - 定位器 —— 说
toBeAlphanumeric(), (中文(简体) ),toBeUpperCase(), (中文(简体) ),toHaveSrc(), (中文(简体) ),toHaveStyles(), (中文(简体) ),toHaveCountGreaterThan(), (中文(简体) ),toHaveCountBetween(), (中文(简体) ),toHaveTextsInAscendingOrder(),还有更多.. 翻译: - 页次 —— 说
toHaveCookie()编号Page或者说BrowserContext, (中文(简体) ),toHaveLocalStorageItem(), (中文(简体) ),toHaveSessionStorageItem()—— 说 翻译: - 对象阵列 —— 说
toHaveObjectsInAscendingOrderBy(), (中文(简体) ),toHaveOnlyUniqueObjects(),还有更多.. 翻译: - 字符串阵列 —— 说
toHaveAscendingOrder(), (中文(简体) ),toHaveStrictlyAscendingOrder(), (中文(简体) ),toHaveUniqueValues(),还有更多.. 翻译: - 常规 —— 说
toBeInteger(), (中文(简体) ),toBeAnyOf(), (中文(简体) ),toSatisfy(), (中文(简体) ),toBeEven(), (中文(简体) ),toBeFinite(), (中文(简体) ),toEqualPartially(), (中文(简体) ),toBeNullish(),还有更多.. 翻译: - 收藏函数( F) —— 说
toSatisfyAll(), (中文(简体) ),toIncludeSameMembers(), (中文(简体) ),toContainKeys(), (中文(简体) ),toContainEntry(), (中文(简体) ),toBeEmptyObject(), (中文(简体) ),toResolve(), (中文(简体) ),toReject(), (中文(简体) ),toThrowWithMessage(),还有更多.. 翻译:
链接
许可证
麻省理工学院
重试断言返回值
expectly.pollAndReturn() 返回满足匹配者的值. expectly(callback).toPassAndReturn() 返回第一个不丢弃的回调尝试的结果。 两者都支持同步和同步回调,成功后不再次调用.
import { expectly } from "@cerios/playwright-expectly";
const order = await expectly
.pollAndReturn(() => fetchOrder(), { timeout: 5_000, intervals: [100, 250] })
.toMatchObject({ status: "COMPLETED" });
const readyOrder = await expectly(async () => {
const current = await fetchOrder();
expectly(current.status).toBe("COMPLETED");
return current;
}).toPassAndReturn({ timeout: 5_000, intervals: [100, 250] });
这里, fetchOrder() 您的应用程序助手 。 投票支持 .not 和注册的自定义匹配者。 重试选项和自定义消息遵循相应的 Playwright API; toPassAndReturn() 使用本地语言 toPass() 超时行为,在需要约束时提供明确的超时.
对于您自己配置或扩展的预期实例,请应用 withReturn() 组合匹配源后 :
import { expectlyMatchers, withReturn } from "@cerios/playwright-expectly";
import { expect as baseExpect } from "@playwright/test";
export const expect = withReturn(baseExpect.extend(expectlyMatchers));
const uuid = await expect.pollAndReturn(() => fetchUuid()).toBeUUID(4);
后续 .soft, (中文(简体) ), .configure() 财务报告和审定财务报表 .extend() 调用保留返回意识方法和自定义匹配器类型。 使用时 mergeExpects(),将其结果以 withReturn()。 。 。 .
失败行为 : 与其它Playwright的说法一样.
软性断言 : 使用情况 .soft 或者说 .configure({ soft: true })然后记录失败,测试继续进行,就像本地的软断言一样。 由于断言没有通过,结果可能不是一个传递价值:
toPassAndReturn()解决undefined,因为没有尝试成功.pollAndReturn()以最后一个未满足匹配者的民意值解决。 它决定undefined如果调用符从未返回一个值.
const order = await expectly.soft.pollAndReturn(() => fetchOrder()).toMatchObject({ status: "COMPLETED" });
const readyOrder = await expectly.soft(() => fetchReadyOrder()).toPassAndReturn({ timeout: 5_000 });
// Both are typed `Order | undefined`; the test is already marked as failed when a check did not pass.
软返回类型 T | undefined。TypeScript只有在软旗被设置在被包的实例上时才能追踪到这一点(expectly.soft, (中文(简体) ), withReturn(expect).configure({ soft: true })) (中文(简体) ). withReturn(expect.configure({ soft: true })) 运行时表现相同 但其类型仍然说 T。 。 。 .
常规断言保留其配置的行为. 内部 toPassAndReturn() 调回,对必须触发重试的条件使用抛出断言;软断言不会抛出.
失败地点 : 返回意识的断言作为盒式的 Playwright 步骤出现. 断言步骤和报告失败 指向线 你的测试 引用匹配者, 包括解开匹配者的呼叫。 原生再试验步骤仍被嵌入到下方进行诊断,扩大后可能显示内部实施地点。 发现的错误还指代了引用,同时保留了它们的原始消息,匹配者细节,以及原因. 经常性的断言保持他们的本土报道.
普通的期待匹配者也会在您的断言调用站点上报告抛出验证和定位API错误 。 其原始错误类型,消息,原因和元数据被保存. 扩大的本土平等,投票,浏览器API步骤仍然可以显示执行地点.
边框行为
- 对象独有性利用节点的深度严格等值来比较当前值,包括 Dates, Maps, Sets, bigint, 和周期. 这种说法没有隐藏之处。 财产命令无关紧要;原型和明确
undefined属性是。 这种比较对于大型阵列来说可以花上四相时间. - Regex 断言测试从索引零进行,而不修改所提供的表达式
lastIndex,包括全局和粘性表达式. - 部分匹配支持共享的引用,但在输入中拒绝循环平原对象和数组,并有明显的错误,包括下
.not。 。 。 . - 数字比较拒绝
NaN和无限的。 整数、平均数、中数和范围容忍整个计算中的四舍五入错误,这个错误随着数值数量和数值的大小而增加,所以[0.01, 2.03, 1.2]金额3.24; 通过{ tolerance }对明确的绝对约束。 空阵列没有平均值或中位数,而且从未匹配. - 连续月份比较历月,独立于月日. ISO 验证拒绝不可能的日历日期, 如
2026-02-30; 见 日期匹配者 用于公认格式. - A 类
pollAndReturn()profile 对象可以同时被重用或被引用;每个匹配者引用会捕捉自己的成功值.
CI对照最低支持的Playwright版本1.40,以及项目当前版本,测试被打包的库. 最小版本声明检查使用TypeScript 5.9,因为TypeScript 7拒绝Playwright 1.40自己声明的遗留语法.