GenericAssertions
The GenericAssertions class provides assertion methods that can be used to make assertions about any values in the tests. A new instance of GenericAssertions is created by calling expect():
import { test, expect } from '@playwright/test';
test('assert a value', async ({ page }) => {
const value = 1;
expect(value).toBe(2);
});
方法 (Methods)
any
Added in: v1.9expect.any()
matches any object instance created from the constructor or a corresponding primitive type. Use it inside expect(value).toEqual() to perform pattern matching.
使用方式
// 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 of the expected object like
ExampleClass
, or a primitive boxed type likeNumber
.
anything
Added in: v1.9expect.anything()
matches everything except null
and undefined
. Use it inside expect(value).toEqual() to perform pattern matching.
使用方式
const value = { prop: 1 };
expect(value).toEqual({ prop: expect.anything() });
expect(value).not.toEqual({ otherProp: expect.anything() });
arrayContaining
Added in: v1.9expect.arrayContaining()
matches an array that contains all of the elements in the expected array, in any order. Note that received array may be a superset of the expected array and contain some extra elements.
Use this method inside expect(value).toEqual() to perform pattern matching.
使用方式
expect([1, 2, 3]).toEqual(expect.arrayContaining([3, 1]));
expect([1, 2, 3]).not.toEqual(expect.arrayContaining([1, 4]));
參數
closeTo
Added in: v1.9Compares floating point numbers for approximate equality. Use this method inside expect(value).toEqual() to perform pattern matching. When just comparing two numbers, prefer 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 value.
-
The number of decimal digits after the decimal point that must be equal.
objectContaining
Added in: v1.9expect.objectContaining()
matches an object that contains and matches all of the properties in the expected object. Note that received object may be a superset of the expected object and contain some extra properties.
Use this method inside expect(value).toEqual() to perform pattern matching. Object properties can be matchers to further relax the expectation. See examples.
使用方式
// 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') }),
}));
參數
stringContaining
Added in: v1.9expect.stringContaining()
matches a string that contains the expected substring. Use this method inside expect(value).toEqual() to perform pattern matching.
使用方式
expect('Hello world!').toEqual(expect.stringContaining('Hello'));
參數
stringMatching
Added in: v1.9expect.stringMatching()
matches a received string that in turn matches the expected pattern. Use this method inside expect(value).toEqual() to perform pattern matching.
使用方式
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.9Compares value with expected by calling Object.is
. This method compares objects by reference instead of their contents, similarly to the strict equality operator ===
.
使用方式
const value = { prop: 1 };
expect(value).toBe(value);
expect(value).not.toBe({});
expect(value.prop).toBe(1);
參數
toBeCloseTo
Added in: v1.9Compares floating point numbers for approximate equality. Use this method instead of expect(value).toBe() when comparing floating point numbers.
使用方式
expect(0.1 + 0.2).not.toBe(0.3);
expect(0.1 + 0.2).toBeCloseTo(0.3, 5);
參數
-
Expected value.
-
The number of decimal digits after the decimal point that must be equal.
toBeDefined
Added in: v1.9Ensures that value is not undefined
.
使用方式
const value = null;
expect(value).toBeDefined();
toBeFalsy
Added in: v1.9Ensures that value is false in a boolean context, one of false
, 0
, ''
, null
, undefined
or NaN
. Use this method when you don't care about the specific value.
使用方式
const value = null;
expect(value).toBeFalsy();
toBeGreaterThan
Added in: v1.9Ensures that value > expected
for number or big integer values.
使用方式
const value = 42;
expect(value).toBeGreaterThan(1);
參數
toBeGreaterThanOrEqual
Added in: v1.9Ensures that value >= expected
for number or big integer values.
使用方式
const value = 42;
expect(value).toBeGreaterThanOrEqual(42);
參數
toBeInstanceOf
Added in: v1.9Ensures that value is an instance of a class. Uses instanceof
operator.
使用方式
expect(page).toBeInstanceOf(Page);
class Example {}
expect(new Example()).toBeInstanceOf(Example);
參數
toBeLessThan
Added in: v1.9Ensures that value < expected
for number or big integer values.
使用方式
const value = 42;
expect(value).toBeLessThan(100);
參數
toBeLessThanOrEqual
Added in: v1.9Ensures that value <= expected
for number or big integer values.
使用方式
const value = 42;
expect(value).toBeLessThanOrEqual(42);
參數
toBeNaN
Added in: v1.9Ensures that value is NaN
.
使用方式
const value = NaN;
expect(value).toBeNaN();
toBeNull
Added in: v1.9Ensures that value is null
.
使用方式
const value = null;
expect(value).toBeNull();
toBeTruthy
Added in: v1.9Ensures that value is true in a boolean context, anything but false
, 0
, ''
, null
, undefined
or NaN
. Use this method when you don't care about the specific value.
使用方式
const value = { example: 'value' };
expect(value).toBeTruthy();
toBeUndefined
Added in: v1.9Ensures that value is undefined
.
使用方式
const value = undefined;
expect(value).toBeUndefined();
toContain(expected)
Added in: v1.9Ensures that string value contains an expected substring. Comparison is case-sensitive.
使用方式
const value = 'Hello, World';
expect(value).toContain('World');
expect(value).toContain(',');
參數
toContain(expected)
Added in: v1.9Ensures that value is an Array
or Set
and contains an expected item.
使用方式
const value = [1, 2, 3];
expect(value).toContain(2);
expect(new Set(value)).toContain(2);
參數
toContainEqual
Added in: v1.9Ensures that value is an Array
or Set
and contains an item equal to the expected.
For objects, this method recursively checks equality of all fields, rather than comparing objects by reference as performed by expect(value).toContain().
For primitive values, this method is equivalent to expect(value).toContain().
使用方式
const value = [
{ example: 1 },
{ another: 2 },
{ more: 3 },
];
expect(value).toContainEqual({ another: 2 });
expect(new Set(value)).toContainEqual({ another: 2 });
參數
toEqual
Added in: v1.9Compares contents of the value with contents of expected, performing "deep equality" check.
For objects, this method recursively checks equality of all fields, rather than comparing objects by reference as performed by expect(value).toBe().
For primitive values, this method is equivalent to expect(value).toBe().
使用方式
const value = { prop: 1 };
expect(value).toEqual({ prop: 1 });
Non-strict equality
expect(value).toEqual() performs deep equality check that compares contents of the received and expected values. To ensure two objects reference the same instance, use expect(value).toBe() instead.
expect(value).toEqual() ignores undefined
properties and array items, and does not insist on object types being equal. For stricter matching, use expect(value).toStrictEqual().
Pattern matching
expect(value).toEqual() can be also used to perform pattern matching on objects, arrays and primitive types, with the help of the following matchers:
- expect(value).any()
- expect(value).anything()
- expect(value).arrayContaining()
- expect(value).closeTo()
- expect(value).objectContaining()
- expect(value).stringContaining()
- expect(value).stringMatching()
Here is an example that asserts some of the values inside a complex object:
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.9Ensures that value has a .length
property equal to expected. Useful for arrays and strings.
使用方式
expect('Hello, World').toHaveLength(12);
expect([1, 2, 3]).toHaveLength(3);
參數
toHaveProperty
Added in: v1.9Ensures that property at provided keyPath
exists on the object and optionally checks that property is equal to the expected. Equality is checked recursively, similarly to 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);
參數
-
Path to the property. Use dot notation
a.b
to check nested properties and indexeda[2]
notation to check nested array items. -
Optional expected value to compare the property to.
toMatch
Added in: v1.9Ensures that string value matches a regular expression.
使用方式
const value = 'Is 42 enough?';
expect(value).toMatch(/Is \d+ enough/);
參數
toMatchObject
Added in: v1.9Compares contents of the value with contents of expected, performing "deep equality" check. Allows extra properties to be present in the value, unlike expect(value).toEqual(), so you can check just a subset of object properties.
When comparing arrays, the number of items must match, and each item is checked recursively.
使用方式
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 }]);
參數
toStrictEqual
Added in: v1.9Compares contents of the value with contents of expected and their types.
Differences from expect(value).toEqual():
- Keys with undefined properties are checked. For example,
{ a: undefined, b: 2 }
does not match{ b: 2 }
. - Array sparseness is checked. For example,
[, 1]
does not match[undefined, 1]
. - Object types are checked to be equal. For example, a class instance with fields
a
andb
will not equal a literal object with fieldsa
andb
.
使用方式
const value = { prop: 1 };
expect(value).toStrictEqual({ prop: 1 });
參數
toThrow
Added in: v1.9Calls the function and ensures it throws an error.
Optionally compares the error with expected. Allowed expected values:
- Regular expression - error message should match the pattern.
- String - error message should include the substring.
- Error object - error message should be equal to the message property of the object.
- Error class - error object should be an instance of the class.
使用方式
expect(() => {
throw new Error('Something bad');
}).toThrow();
expect(() => {
throw new Error('Something bad');
}).toThrow(/something/);
expect(() => {
throw new Error('Something bad');
}).toThrow(Error);
參數
toThrowError
Added in: v1.9An alias for expect(value).toThrow().
使用方式
expect(() => {
throw new Error('Something bad');
}).toThrowError();
參數
屬性 (Properties)
not
Added in: v1.9Makes the assertion check for the opposite condition. For example, the following code passes:
const value = 1;
expect(value).not.toBe(2);
使用方式
expect(value).not
型別 (Type)