跳至主要内容

GenericAssertions

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

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

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

方法​

任意​

Added in: 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。

任何内容​

Added in: 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​

Added in: 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​

Added in: 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​

Added in: 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​

Added in: v1.9 genericAssertions.stringContaining

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

用法

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

参数

  • expected string#

    预期的子字符串。

字符串匹配​

Added in: 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/),
});

参数

toBe​

Added in: v1.9 genericAssertions.toBe

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

用法

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

参数

toBeCloseTo​

Added in: 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​

Added in: v1.9 genericAssertions.toBeDefined

确保值不是undefined。

用法

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

toBeFalsy​

Added in: v1.9 genericAssertions.toBeFalsy

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

用法

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

toBeGreaterThan​

Added in: v1.9 genericAssertions.toBeGreaterThan

确保数值或大整数满足value > expected条件。

用法

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

参数

  • expected number | [bigint]#

    用于比较的值。

toBeGreaterThanOrEqual​

Added in: v1.9 genericAssertions.toBeGreaterThanOrEqual

确保数值或大整数满足value >= expected的条件。

用法

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

参数

  • expected number | [bigint]#

    要比较的值。

toBeInstanceOf​

Added in: v1.9 genericAssertions.toBeInstanceOf

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

用法

expect(page).toBeInstanceOf(Page);

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

参数

toBeLessThan​

Added in: v1.9 genericAssertions.toBeLessThan

确保数值或大整数满足 value < expected 条件。

用法

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

参数

  • expected number | [bigint]#

    要比较的值。

toBeLessThanOrEqual​

Added in: v1.9 genericAssertions.toBeLessThanOrEqual

确保数值或大整数满足value <= expected条件。

用法

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

参数

  • expected number | [bigint]#

    要比较的值。

toBeNaN​

Added in: v1.9 genericAssertions.toBeNaN

确保值为 NaN。

用法

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

toBeNull​

Added in: v1.9 genericAssertions.toBeNull

确保值为null。

用法

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

toBeTruthy​

Added in: v1.9 genericAssertions.toBeTruthy

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

用法

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

toBeUndefined​

Added in: v1.9 genericAssertions.toBeUndefined

确保值为undefined。

用法

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

toContain(预期值)​

Added in: v1.9 genericAssertions.toContain(expected)

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

用法

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

参数

  • expected string#

    预期的子字符串。

toContain(预期值)​

Added in: 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​

Added in: 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​

Added in: 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') }),
}));

参数

toHaveLength​

Added in: v1.9 genericAssertions.toHaveLength

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

用法

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

参数

toHaveProperty​

Added in: 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​

Added in: v1.9 genericAssertions.toMatch

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

用法

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

参数

toMatchObject​

Added in: 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​

Added in: v1.9 genericAssertions.toStrictEqual

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

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

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

用法

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

参数

toThrow​

Added in: v1.9 genericAssertions.toThrow

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

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

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

用法

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​

Added in: v1.9 genericAssertions.toThrowError

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

用法

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

参数

  • expected Object (可选)#

    预期的错误信息或错误对象。

属性​

不​

Added in: v1.9 genericAssertions.not

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

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

用法

expect(value).not

类型