# @cerios/playwright-expectly 中文文档

规范地址：https://npmcn.com/package/%40cerios/playwright-expectly/

版本：2\.1\.0
npm 元数据更新时间：2026-11-06T11:19:06.014Z
中文译文更新时间：2026-11-09T11:10:30.931Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cerios/playwright-expectly
原文对照：https://npmcn.com/package/%40cerios/playwright-expectly/?lang=original
项目主页：https://github.com/CeriosTesting/playwright-expectly#readme
源码仓库：https://github.com/CeriosTesting/playwright-expectly

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.7 MB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：@playwright/test \>=1\.40\.0
- 首次发布：2025-12-01T10:49:17.657Z
- 最新版本发布：2026-11-06T11:19:05.710Z
- 近 30 天下载量：2804（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

综合 Playwright 测试匹配器,用于字符串,数字,日期,阵列,对象,和定位器. 用直观的说法来简化你的E2E测试,比如BeAlphanumic, toHave Aliginal Order, toBe The Future,以及130+更多的匹配者.

## 安装

```sh
npm install @cerios/playwright-expectly
```

也可以使用：`pnpm add @cerios/playwright-expectly`、`yarn add @cerios/playwright-expectly`、`bun add @cerios/playwright-expectly`

## README

# 由Cerios主演

[![npm version](https://badge.fury.io/js/%40cerios%2Fplaywright-expectly.svg)](https://www.npmjs.com/package/@cerios/playwright-expectly) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

全面的 Playwright 测试匹配器,用于字符串,数字,日期,阵列,对象,定位器,和页面状态. 用直观的说法简化你的E2E测试 `toBeAlphanumeric`, (中文(简体) ), `toHaveAscendingOrder`, (中文(简体) ), `toBeInTheFuture`,和130+ 更多的匹配者.

## 特征

-   🎯 **130+ 自定义匹配器** ——对所有数据类型进行广泛验证
-   🔤 **字符串验证** 电子邮件、 URL、 UUID、 字母数、 六进制、 大小写不敏感 等
-   🔢 **数字矩阵** 分类、统计、范围和模式
-   📅 **日期和时间** —— 说 `Date`,ISO字符串和时间;时区,DST,纳秒精度,持续时间
-   🎨 **定位仪** —— DOM 元素验证,文本格式化,计数范围,排序文本,并计算样式
-   🍪 **页面状态** 重试饼干, `localStorage` 财务报告和审定财务报表 `sessionStorage` 主张
-   📦 **对象矩阵** ——分类,独特性,财产鉴定
-   🧺 **收藏和函数** 阵列成员、对象密钥和条目、承诺和抛出的错误
-   🤖 **模糊匹配** ——AI生成文本验证(分离) [`@cerios/playwright-expectly-fuzzy`](https://www.npmjs.com/package/@cerios/playwright-expectly-fuzzy) 软件包)
-   💪 **类型安全** ——完整类型脚本支持
-   ⚡ **轻巧** ——仅要求 Playwright

## 安装

```bash
npm install @cerios/playwright-expectly --save-dev
```

> **同伴依赖 :** 需求 `@playwright/test` 将安装.

## 快速启动

### 建议:单身 `tests/support` 本地模块 `expect`

在您自己的项目中创建扩展 Playwright 的共享模块 `expect` 并捕获返回值,然后再出口。 每个固定文件和 spec 文件导入 `test`编号 :`expect` 从本单元开始——从不直接从 `@playwright/test`。 。 。 .

```typescript
// 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;
```

```typescript
import { expect, test } from "./support/expect";

test("extended expect example", async ({ page }) => {
    expect("john@example.com").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`

```typescript
import { expectly } from "@cerios/playwright-expectly";

expectly("user@example.com").toBeValidEmail();
expectly([1, 2, 3, 4, 5]).toHaveAscendingOrder();
expectly(subscription.expiresAt).toBeInTheFuture();
await expectly(page.locator(".username")).toBeAlphanumeric();
```

与 `@cerios/playwright-expectly-fuzzy`,或自己的匹配者,通过 `mergeExpects()`数字 :

```typescript
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;
```

如果您只需要独立的软件包导出, 较短的表单也是有效的 :

```typescript
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()`见 [根读取](https://npmcn.com/package/README.md#upgrading-from-1x) 以移民为例.

## 可用匹配符

-   **字符串** —— 说 `toBeValidEmail()`, (中文(简体) ), `toBeValidUrl()`, (中文(简体) ), `toBeUUID()`, (中文(简体) ), `toBeAlphanumeric()`, (中文(简体) ), `toBeHexadecimal()`, (中文(简体) ), `toEqualCaseInsensitive()`, (中文(简体) ), `toEqualIgnoringWhitespace()`, (中文(简体) ), `toMatchPattern()`,还有更多.. [翻译:](https://npmcn.com/package/docs/STRING_MATCHERS.md)
-   **数字矩阵** —— 说 `toHaveAscendingOrder()`, (中文(简体) ), `toHaveAverage()`, (中文(简体) ), `toBeAllPositive()`, (中文(简体) ), `toBeMonotonic()`,还有更多.. [翻译:](https://npmcn.com/package/docs/NUMBER_ARRAY_MATCHERS.md)
-   **日期和时间** —— 说 `Date`,ISO字符串和时间值: `toBeWithinLast()`, (中文(简体) ), `toBeWithinDurationAfter()`, (中文(简体) ), `toBeSameInstant()`, (中文(简体) ), `toBeSameDay()`, (中文(简体) ), `toBeWithinTimeOfDay()`, (中文(简体) ), `toHaveOffset()`时间匹配器,加 `parseISO*()` 编号 : `isISO*()` 并键入 ISO 字符串 - [翻译:](https://npmcn.com/package/docs/DATE_MATCHERS.md)
-   **定位器** —— 说 `toBeAlphanumeric()`, (中文(简体) ), `toBeUpperCase()`, (中文(简体) ), `toHaveSrc()`, (中文(简体) ), `toHaveStyles()`, (中文(简体) ), `toHaveCountGreaterThan()`, (中文(简体) ), `toHaveCountBetween()`, (中文(简体) ), `toHaveTextsInAscendingOrder()`,还有更多.. [翻译:](https://npmcn.com/package/docs/LOCATOR_MATCHERS.md)
-   **页次** —— 说 `toHaveCookie()` 编号 `Page` 或者说 `BrowserContext`, (中文(简体) ), `toHaveLocalStorageItem()`, (中文(简体) ), `toHaveSessionStorageItem()` —— 说 [翻译:](https://npmcn.com/package/docs/PAGE_MATCHERS.md)
-   **对象阵列** —— 说 `toHaveObjectsInAscendingOrderBy()`, (中文(简体) ), `toHaveOnlyUniqueObjects()`,还有更多.. [翻译:](https://npmcn.com/package/docs/OBJECT_ARRAY_MATCHERS.md)
-   **字符串阵列** —— 说 `toHaveAscendingOrder()`, (中文(简体) ), `toHaveStrictlyAscendingOrder()`, (中文(简体) ), `toHaveUniqueValues()`,还有更多.. [翻译:](https://npmcn.com/package/docs/STRING_ARRAY_MATCHERS.md)
-   **常规** —— 说 `toBeInteger()`, (中文(简体) ), `toBeAnyOf()`, (中文(简体) ), `toSatisfy()`, (中文(简体) ), `toBeEven()`, (中文(简体) ), `toBeFinite()`, (中文(简体) ), `toEqualPartially()`, (中文(简体) ), `toBeNullish()`,还有更多.. [翻译:](https://npmcn.com/package/docs/GENERIC_MATCHERS.md)
-   **收藏函数( F)** —— 说 `toSatisfyAll()`, (中文(简体) ), `toIncludeSameMembers()`, (中文(简体) ), `toContainKeys()`, (中文(简体) ), `toContainEntry()`, (中文(简体) ), `toBeEmptyObject()`, (中文(简体) ), `toResolve()`, (中文(简体) ), `toReject()`, (中文(简体) ), `toThrowWithMessage()`,还有更多.. [翻译:](https://npmcn.com/package/docs/COLLECTION_MATCHERS.md)

## 链接

-   [完整项目 README](https://github.com/CeriosTesting/playwright-expectly#readme)
-   [更改日志](https://npmcn.com/package/%40cerios/playwright-expectly/CHANGELOG.md)
-   [问题](https://github.com/CeriosTesting/playwright-expectly/issues)

## 许可证

麻省理工学院

## 重试断言返回值

`expectly.pollAndReturn()` 返回满足匹配者的值. `expectly(callback).toPassAndReturn()` 返回第一个不丢弃的回调尝试的结果。 两者都支持同步和同步回调,成功后不再次调用.

```typescript
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()` 组合匹配源后 :

```typescript
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` 如果调用符从未返回一个值.

```typescript
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`; 见 [日期匹配者](https://npmcn.com/package/docs/DATE_MATCHERS.md) 用于公认格式.
-   A 类 `pollAndReturn()` profile 对象可以同时被重用或被引用;每个匹配者引用会捕捉自己的成功值.

CI对照最低支持的Playwright版本1.40,以及项目当前版本,测试被打包的库. 最小版本声明检查使用TypeScript 5.9,因为TypeScript 7拒绝Playwright 1.40自己声明的遗留语法.

## 常见问题

### @cerios/playwright-expectly 是什么？

综合 Playwright 测试匹配器,用于字符串,数字,日期,阵列,对象,和定位器\. 用直观的说法来简化你的E2E测试,比如BeAlphanumic, toHave Aliginal Order, toBe The Future,以及130\+更多的匹配者\.

### 如何安装 @cerios/playwright-expectly？

在项目目录运行 npm install @cerios/playwright-expectly，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@playwright/test（\>=1\.40\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cerios/playwright-expectly 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cerios/playwright-expectly 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cerios/playwright-expectly 可以商用吗？

@cerios/playwright-expectly 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cerios/playwright-expectly 的下载量有多少？

根据 npm 官方下载统计，@cerios/playwright-expectly 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,804 次，日均约 93 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cerios/playwright-expectly 还在维护吗？

最新版本 2\.1\.0 发布于 2026/11/06（3 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2025/12/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。