GenericAssertions

GenericAssertions 类提供了可用于在测试中对任何值进行断言的断言方法。通过调用 expect() 可以创建一个新的 GenericAssertions 实例。

import { test, expect } from '@playwright/test';

test('assert a value', async ({ page }) => {
  const value = 1;
  expect(value).toBe(2);
});

方法

any

添加于: v1.9

genericAssertions.any

expect.any() 匹配由 constructor 创建的任何对象实例或对应的原始类型。在 expect(value).toEqual() 中使用它进行模式匹配。

用法

// Match instance of a class.
class Example {}
expect(new Example()).toEqual(expect.any(Example));

// Match any number.
expect({ prop: 1 }).toEqual({ prop: expect.any(Number) });

// Match any string.
expect('abc').toEqual(expect.any(String));

参数

constructor Function #

期望对象的构造函数，例如 ExampleClass，或原始包装类型，例如 Number。

anything

添加于: v1.9

genericAssertions.anything

expect.anything() 匹配除了 null 和 undefined 之外的所有内容。在 expect(value).toEqual() 中使用它进行模式匹配。

用法

const value = { prop: 1 };
expect(value).toEqual({ prop: expect.anything() });
expect(value).not.toEqual({ otherProp: expect.anything() });

arrayContaining

添加于: v1.9

genericAssertions.arrayContaining

expect.arrayContaining() 匹配包含期望数组中所有元素的数组，顺序不限。注意，接收到的数组可能是期望数组的超集，并包含一些额外的元素。

在 expect(value).toEqual() 中使用此方法进行模式匹配。

用法

expect([1, 2, 3]).toEqual(expect.arrayContaining([3, 1]));
expect([1, 2, 3]).not.toEqual(expect.arrayContaining([1, 4]));

参数

expected Array<Object>#

作为接收值子集的期望数组。

closeTo

添加于: v1.9

genericAssertions.closeTo

比较浮点数的近似相等性。在 expect(value).toEqual() 中使用此方法进行模式匹配。仅比较两个数字时，优先使用 expect(value).toBeCloseTo()。

用法

expect({ prop: 0.1 + 0.2 }).not.toEqual({ prop: 0.3 });
expect({ prop: 0.1 + 0.2 }).toEqual({ prop: expect.closeTo(0.3, 5) });

参数

expected number #

期望值。
numDigits number (可选)#

小数点后必须相等的十进制位数。

objectContaining

添加于: v1.9

genericAssertions.objectContaining

expect.objectContaining() 匹配包含并匹配期望对象中所有属性的对象。注意，接收到的对象可能是期望对象的超集，并包含一些额外的属性。

在 expect(value).toEqual() 中使用此方法进行模式匹配。对象属性可以是匹配器，以进一步放宽期望。请参见示例。

用法

// Assert some of the properties.
expect({ foo: 1, bar: 2 }).toEqual(expect.objectContaining({ foo: 1 }));

// Matchers can be used on the properties as well.
expect({ foo: 1, bar: 2 }).toEqual(expect.objectContaining({ bar: expect.any(Number) }));

// Complex matching of sub-properties.
expect({
  list: [1, 2, 3],
  obj: { prop: 'Hello world!', another: 'some other value' },
  extra: 'extra',
}).toEqual(expect.objectContaining({
  list: expect.arrayContaining([2, 3]),
  obj: expect.objectContaining({ prop: expect.stringContaining('Hello') }),
}));

参数

expected Object #

包含部分属性的期望对象模式。

stringContaining

添加于: v1.9

genericAssertions.stringContaining

expect.stringContaining() 匹配包含期望子字符串的字符串。在 expect(value).toEqual() 中使用此方法进行模式匹配。

用法

expect('Hello world!').toEqual(expect.stringContaining('Hello'));

参数

expected string #

期望的子字符串。

stringMatching

添加于: v1.9

genericAssertions.stringMatching

expect.stringMatching() 匹配一个与期望模式相匹配的接收到的字符串。在 expect(value).toEqual() 中使用此方法进行模式匹配。

用法

expect('123ms').toEqual(expect.stringMatching(/\d+m?s/));

// Inside another matcher.
expect({
  status: 'passed',
  time: '123ms',
}).toEqual({
  status: expect.stringMatching(/passed|failed/),
  time: expect.stringMatching(/\d+m?s/),
});

参数

expected string | RegExp #

期望字符串应匹配的模式。

toBe

添加于: v1.9

genericAssertions.toBe

通过调用 Object.is 将值与 expected 进行比较。此方法按引用而不是内容比较对象，类似于严格相等运算符 ===。

用法

const value = { prop: 1 };
expect(value).toBe(value);
expect(value).not.toBe({});
expect(value.prop).toBe(1);

参数

expected Object #

期望值。

toBeCloseTo

添加于: v1.9

genericAssertions.toBeCloseTo

比较浮点数的近似相等性。比较浮点数时，使用此方法代替 expect(value).toBe()。

用法

expect(0.1 + 0.2).not.toBe(0.3);
expect(0.1 + 0.2).toBeCloseTo(0.3, 5);

参数

expected number #

期望值。
numDigits number (可选)#

小数点后必须相等的十进制位数。

toBeDefined

添加于: v1.9

genericAssertions.toBeDefined

确保值不是 undefined。

用法

const value = null;
expect(value).toBeDefined();

toBeFalsy

添加于: v1.9

genericAssertions.toBeFalsy

确保值在布尔上下文中为 false，即 false、0、''、null、undefined 或 NaN 之一。当您不关心具体值时使用此方法。

用法

const value = null;
expect(value).toBeFalsy();

toBeGreaterThan

添加于: v1.9

genericAssertions.toBeGreaterThan

确保 number 或 bigint 值满足 value > expected。

用法

const value = 42;
expect(value).toBeGreaterThan(1);

参数

expected number | [bigint]#

要比较的值。

toBeGreaterThanOrEqual

添加于: v1.9

genericAssertions.toBeGreaterThanOrEqual

确保 number 或 bigint 值满足 value >= expected。

用法

const value = 42;
expect(value).toBeGreaterThanOrEqual(42);

参数

expected number | [bigint]#

要比较的值。

toBeInstanceOf

添加于: v1.9

genericAssertions.toBeInstanceOf

确保值是某个类的实例。使用 instanceof 运算符。

用法

expect(page).toBeInstanceOf(Page);

class Example {}
expect(new Example()).toBeInstanceOf(Example);

参数

expected Function #

类或构造函数。

toBeLessThan

添加于: v1.9

genericAssertions.toBeLessThan

确保 number 或 bigint 值满足 value < expected。

用法

const value = 42;
expect(value).toBeLessThan(100);

参数

expected number | [bigint]#

要比较的值。

toBeLessThanOrEqual

添加于: v1.9

genericAssertions.toBeLessThanOrEqual

确保 number 或 bigint 值满足 value <= expected。

用法

const value = 42;
expect(value).toBeLessThanOrEqual(42);

参数

expected number | [bigint]#

要比较的值。

toBeNaN

添加于: v1.9

genericAssertions.toBeNaN

确保值是 NaN。

用法

const value = NaN;
expect(value).toBeNaN();

toBeNull

添加于: v1.9

genericAssertions.toBeNull

确保值是 null。

用法

const value = null;
expect(value).toBeNull();

toBeTruthy

添加于: v1.9

genericAssertions.toBeTruthy

确保值在布尔上下文中为 true，即除了 false、0、''、null、undefined 或 NaN 之外的任何值。当您不关心具体值时使用此方法。

用法

const value = { example: 'value' };
expect(value).toBeTruthy();

toBeUndefined

添加于: v1.9

genericAssertions.toBeUndefined

确保值是 undefined。

用法

const value = undefined;
expect(value).toBeUndefined();

toContain(expected)

添加于: v1.9

genericAssertions.toContain(expected)

确保字符串值包含期望的子字符串。比较区分大小写。

用法

const value = 'Hello, World';
expect(value).toContain('World');
expect(value).toContain(',');

参数

expected string #

期望的子字符串。

toContain(expected)

添加于: v1.9

genericAssertions.toContain(expected)

确保值是 Array 或 Set 且包含期望的项。

用法

const value = [1, 2, 3];
expect(value).toContain(2);
expect(new Set(value)).toContain(2);

参数

expected Object #

集合中的期望值。

toContainEqual

添加于: v1.9

genericAssertions.toContainEqual

确保值是 Array 或 Set 且包含与期望值相等的项。

对于对象，此方法递归检查所有字段的相等性，而不是像 expect(value).toContain() 那样按引用比较对象。

对于原始值，此方法等同于 expect(value).toContain()。

用法

const value = [
  { example: 1 },
  { another: 2 },
  { more: 3 },
];
expect(value).toContainEqual({ another: 2 });
expect(new Set(value)).toContainEqual({ another: 2 });

参数

expected Object #

集合中的期望值。

toEqual

添加于: v1.9

genericAssertions.toEqual

将值的内容与 expected 的内容进行比较，执行“深度相等”检查。

对于对象，此方法递归检查所有字段的相等性，而不是像 expect(value).toBe() 那样按引用比较对象。

对于原始值，此方法等同于 expect(value).toBe()。

用法

const value = { prop: 1 };
expect(value).toEqual({ prop: 1 });

非严格相等

expect(value).toEqual() 执行深度相等检查，比较接收值和期望值的内容。为确保两个对象引用同一实例，请改用 expect(value).toBe()。

expect(value).toEqual() 忽略 undefined 属性和数组项，并且不强制要求对象类型相等。对于更严格的匹配，请使用 expect(value).toStrictEqual()。

模式匹配

expect(value).toEqual() 也可以用于对象、数组和原始类型的模式匹配，借助以下匹配器：

这是一个断言复杂对象内某些值的示例：

expect({
  list: [1, 2, 3],
  obj: { prop: 'Hello world!', another: 'some other value' },
  extra: 'extra',
}).toEqual(expect.objectContaining({
  list: expect.arrayContaining([2, 3]),
  obj: expect.objectContaining({ prop: expect.stringContaining('Hello') }),
}));

参数

expected Object #

期望值。

toHaveLength

添加于: v1.9

genericAssertions.toHaveLength

确保值的 .length 属性等于 expected。对数组和字符串很有用。

用法

expect('Hello, World').toHaveLength(12);
expect([1, 2, 3]).toHaveLength(3);

参数

expected number #

期望的长度。

toHaveProperty

添加于: v1.9

genericAssertions.toHaveProperty

确保给定 keyPath 处的属性存在于对象上，并可选地检查该属性是否等于 expected。相等性以递归方式检查，类似于 expect(value).toEqual()。

用法

const value = {
  a: {
    b: [42],
  },
  c: true,
};
expect(value).toHaveProperty('a.b');
expect(value).toHaveProperty('a.b', [42]);
expect(value).toHaveProperty('a.b[0]', 42);
expect(value).toHaveProperty('c');
expect(value).toHaveProperty('c', true);

参数

keyPath string #

属性的路径。使用点号表示法 a.b 检查嵌套属性，使用索引表示法 a[2] 检查嵌套数组项。
expected Object (可选)#

用于比较属性的可选期望值。

toMatch

添加于: v1.9

genericAssertions.toMatch

确保字符串值匹配正则表达式。

用法

const value = 'Is 42 enough?';
expect(value).toMatch(/Is \d+ enough/);

参数

expected RegExp | string #

用于匹配的正则表达式。

toMatchObject

添加于: v1.9

genericAssertions.toMatchObject

将值的内容与 expected 的内容进行比较，执行“深度相等”检查。与 expect(value).toEqual() 不同，允许值中存在额外的属性，因此您只检查对象属性的一个子集即可。

比较数组时，项的数量必须匹配，且每个项都会递归检查。

用法

const value = {
  a: 1,
  b: 2,
  c: true,
};
expect(value).toMatchObject({ a: 1, c: true });
expect(value).toMatchObject({ b: 2, c: true });

expect([{ a: 1, b: 2 }]).toMatchObject([{ a: 1 }]);

参数

expected Object | Array #

用于匹配的期望对象值。

toStrictEqual

添加于: v1.9

genericAssertions.toStrictEqual

比较值的内容与 expected 的内容及其类型。

与 expect(value).toEqual() 的区别

会检查带有 undefined 属性的键。例如，{ a: undefined, b: 2 } 与 { b: 2 } 不匹配。
会检查数组的稀疏性。例如，[, 1] 与 [undefined, 1] 不匹配。
会检查对象类型是否相等。例如，具有字段 a 和 b 的类实例不等于具有字段 a 和 b 的字面量对象。

用法

const value = { prop: 1 };
expect(value).toStrictEqual({ prop: 1 });

参数

expected Object #

期望值。

toThrow

添加于: v1.9

genericAssertions.toThrow

调用函数并确保它抛出错误。

可选地将错误与 expected 进行比较。允许的期望值：

正则表达式 - 错误消息应匹配模式。
字符串 - 错误消息应包含子字符串。
Error 对象 - 错误消息应等于该对象的 message 属性。
Error 类 - 错误对象应是该类的实例。

用法

expect(() => {
  throw new Error('Something bad');
}).toThrow();

expect(() => {
  throw new Error('Something bad');
}).toThrow(/something/);

expect(() => {
  throw new Error('Something bad');
}).toThrow(Error);

参数

expected Object (可选)#

期望的错误消息或错误对象。

toThrowError

添加于: v1.9

genericAssertions.toThrowError

expect(value).toThrow() 的别名。

用法

expect(() => {
  throw new Error('Something bad');
}).toThrowError();

参数

expected Object (可选)#

期望的错误消息或错误对象。

属性

not

添加于: v1.9

genericAssertions.not

使断言检查相反的条件。例如，以下代码通过：

const value = 1;
expect(value).not.toBe(2);

用法

expect(value).not

类型

GenericAssertions

方法​

any​

anything​

arrayContaining​

closeTo​

objectContaining​

stringContaining​

stringMatching​

toBe​

toBeCloseTo​

toBeDefined​

toBeFalsy​

toBeGreaterThan​

toBeGreaterThanOrEqual​

toBeInstanceOf​

toBeLessThan​

toBeLessThanOrEqual​

toBeNaN​

toBeNull​

toBeTruthy​

toBeUndefined​

toContain(expected)​

toContain(expected)​

toContainEqual​

toEqual​

toHaveLength​

toHaveProperty​

toMatch​

toMatchObject​

toStrictEqual​

toThrow​

toThrowError​

属性​

not​

方法

any

anything

arrayContaining

closeTo

objectContaining

stringContaining

stringMatching

toBe

toBeCloseTo

toBeDefined

toBeFalsy

toBeGreaterThan

toBeGreaterThanOrEqual

toBeInstanceOf

toBeLessThan

toBeLessThanOrEqual

toBeNaN

toBeNull

toBeTruthy

toBeUndefined

toContain(expected)

toContain(expected)

toContainEqual

toEqual

toHaveLength

toHaveProperty

toMatch

toMatchObject

toStrictEqual

toThrow

toThrowError

属性

not