mirror of
https://github.com/microsoft/playwright.git
synced 2025-06-26 21:40:17 +00:00
731 lines
17 KiB
Markdown
731 lines
17 KiB
Markdown
# class: GenericAssertions
|
|
* since: v1.9
|
|
* langs: js
|
|
|
|
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 [`method: PlaywrightAssertions.expectGeneric`]:
|
|
|
|
```js
|
|
import { test, expect } from '@playwright/test';
|
|
|
|
test('assert a value', async ({ page }) => {
|
|
const value = 1;
|
|
expect(value).toBe(2);
|
|
});
|
|
```
|
|
|
|
## property: GenericAssertions.not
|
|
* since: v1.9
|
|
- returns: <[GenericAssertions]>
|
|
|
|
Makes the assertion check for the opposite condition. For example, the following code passes:
|
|
|
|
```js
|
|
const value = 1;
|
|
expect(value).not.toBe(2);
|
|
```
|
|
|
|
|
|
## method: GenericAssertions.toBe
|
|
* since: v1.9
|
|
|
|
Compares value with [`param: expected`] by calling `Object.is`. This method compares objects by reference instead of their contents, similarly to the strict equality operator `===`.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = { prop: 1 };
|
|
expect(value).toBe(value);
|
|
expect(value).not.toBe({});
|
|
expect(value.prop).toBe(1);
|
|
```
|
|
|
|
### param: GenericAssertions.toBe.expected
|
|
* since: v1.9
|
|
- `expected` <[any]>
|
|
|
|
Expected value.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toBeCloseTo
|
|
* since: v1.9
|
|
|
|
Compares floating point numbers for approximate equality. Use this method instead of [`method: GenericAssertions.toBe`] when comparing floating point numbers.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
expect(0.1 + 0.2).not.toBe(0.3);
|
|
expect(0.1 + 0.2).toBeCloseTo(0.3, 5);
|
|
```
|
|
|
|
### param: GenericAssertions.toBeCloseTo.expected
|
|
* since: v1.9
|
|
- `expected` <[float]>
|
|
|
|
Expected value.
|
|
|
|
### param: GenericAssertions.toBeCloseTo.numDigits
|
|
* since: v1.9
|
|
- `numDigits` ?<[int]>
|
|
|
|
The number of decimal digits after the decimal point that must be equal.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toBeDefined
|
|
* since: v1.9
|
|
|
|
Ensures that value is not `undefined`.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = null;
|
|
expect(value).toBeDefined();
|
|
```
|
|
|
|
|
|
## method: GenericAssertions.toBeFalsy
|
|
* since: v1.9
|
|
|
|
Ensures 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.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = null;
|
|
expect(value).toBeFalsy();
|
|
```
|
|
|
|
|
|
## method: GenericAssertions.toBeGreaterThan
|
|
* since: v1.9
|
|
|
|
Ensures that `value > expected` for number or big integer values.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = 42;
|
|
expect(value).toBeGreaterThan(1);
|
|
```
|
|
|
|
### param: GenericAssertions.toBeGreaterThan.expected
|
|
* since: v1.9
|
|
- `expected` <[float]|[bigint]>
|
|
|
|
The value to compare to.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toBeGreaterThanOrEqual
|
|
* since: v1.9
|
|
|
|
Ensures that `value >= expected` for number or big integer values.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = 42;
|
|
expect(value).toBeGreaterThanOrEqual(42);
|
|
```
|
|
|
|
### param: GenericAssertions.toBeGreaterThanOrEqual.expected
|
|
* since: v1.9
|
|
- `expected` <[float]|[bigint]>
|
|
|
|
The value to compare to.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toBeInstanceOf
|
|
* since: v1.9
|
|
|
|
Ensures that value is an instance of a class. Uses `instanceof` operator.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
expect(page).toBeInstanceOf(Page);
|
|
|
|
class Example {}
|
|
expect(new Example()).toBeInstanceOf(Example);
|
|
```
|
|
|
|
### param: GenericAssertions.toBeInstanceOf.expected
|
|
* since: v1.9
|
|
- `expected` <[Function]>
|
|
|
|
The class or constructor function.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toBeLessThan
|
|
* since: v1.9
|
|
|
|
Ensures that `value < expected` for number or big integer values.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = 42;
|
|
expect(value).toBeLessThan(100);
|
|
```
|
|
|
|
### param: GenericAssertions.toBeLessThan.expected
|
|
* since: v1.9
|
|
- `expected` <[float]|[bigint]>
|
|
|
|
The value to compare to.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toBeLessThanOrEqual
|
|
* since: v1.9
|
|
|
|
Ensures that `value <= expected` for number or big integer values.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = 42;
|
|
expect(value).toBeLessThanOrEqual(42);
|
|
```
|
|
|
|
### param: GenericAssertions.toBeLessThanOrEqual.expected
|
|
* since: v1.9
|
|
- `expected` <[float]|[bigint]>
|
|
|
|
The value to compare to.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toBeNaN
|
|
* since: v1.9
|
|
|
|
Ensures that value is `NaN`.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = NaN;
|
|
expect(value).toBeNaN();
|
|
```
|
|
|
|
|
|
## method: GenericAssertions.toBeNull
|
|
* since: v1.9
|
|
|
|
Ensures that value is `null`.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = null;
|
|
expect(value).toBeNull();
|
|
```
|
|
|
|
|
|
|
|
## method: GenericAssertions.toBeTruthy
|
|
* since: v1.9
|
|
|
|
Ensures 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.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = { example: 'value' };
|
|
expect(value).toBeTruthy();
|
|
```
|
|
|
|
|
|
## method: GenericAssertions.toBeUndefined
|
|
* since: v1.9
|
|
|
|
Ensures that value is `undefined`.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = undefined;
|
|
expect(value).toBeUndefined();
|
|
```
|
|
|
|
|
|
## method: GenericAssertions.toContain#1
|
|
* since: v1.9
|
|
|
|
Ensures that string value contains an expected substring. Comparison is case-sensitive.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = 'Hello, World';
|
|
expect(value).toContain('World');
|
|
expect(value).toContain(',');
|
|
```
|
|
|
|
### param: GenericAssertions.toContain#1.expected
|
|
* since: v1.9
|
|
- `expected` <[string]>
|
|
|
|
Expected substring.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toContain#2
|
|
* since: v1.9
|
|
|
|
Ensures that value is an `Array` or `Set` and contains an expected item.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = [1, 2, 3];
|
|
expect(value).toContain(2);
|
|
expect(new Set(value)).toContain(2);
|
|
```
|
|
|
|
### param: GenericAssertions.toContain#2.expected
|
|
* since: v1.9
|
|
- `expected` <[any]>
|
|
|
|
Expected value in the collection.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toContainEqual
|
|
* since: v1.9
|
|
|
|
Ensures 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 [`method: GenericAssertions.toContain#2`].
|
|
|
|
For primitive values, this method is equivalent to [`method: GenericAssertions.toContain#2`].
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = [
|
|
{ example: 1 },
|
|
{ another: 2 },
|
|
{ more: 3 },
|
|
];
|
|
expect(value).toContainEqual({ another: 2 });
|
|
expect(new Set(value)).toContainEqual({ another: 2 });
|
|
```
|
|
|
|
### param: GenericAssertions.toContainEqual.expected
|
|
* since: v1.9
|
|
- `expected` <[any]>
|
|
|
|
Expected value in the collection.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toEqual
|
|
* since: v1.9
|
|
|
|
Compares contents of the value with contents of [`param: expected`], performing "deep equality" check.
|
|
|
|
For objects, this method recursively checks equality of all fields, rather than comparing objects by reference as performed by [`method: GenericAssertions.toBe`].
|
|
|
|
For primitive values, this method is equivalent to [`method: GenericAssertions.toBe`].
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = { prop: 1 };
|
|
expect(value).toEqual({ prop: 1 });
|
|
```
|
|
|
|
**Non-strict equality**
|
|
|
|
[`method: GenericAssertions.toEqual`] performs deep equality check that compares contents of the received and expected values. To ensure two objects reference the same instance, use [`method: GenericAssertions.toBe`] instead.
|
|
|
|
[`method: GenericAssertions.toEqual`] ignores `undefined` properties and array items, and does not insist on object types being equal. For stricter matching, use [`method: GenericAssertions.toStrictEqual`].
|
|
|
|
**Pattern matching**
|
|
|
|
[`method: GenericAssertions.toEqual`] can be also used to perform pattern matching on objects, arrays and primitive types, with the help of the following matchers:
|
|
|
|
* [`method: GenericAssertions.any`]
|
|
* [`method: GenericAssertions.anything`]
|
|
* [`method: GenericAssertions.arrayContaining`]
|
|
* [`method: GenericAssertions.closeTo`]
|
|
* [`method: GenericAssertions.objectContaining`]
|
|
* [`method: GenericAssertions.stringContaining`]
|
|
* [`method: GenericAssertions.stringMatching`]
|
|
|
|
Here is an example that asserts some of the values inside a complex object:
|
|
```js
|
|
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') }),
|
|
}));
|
|
```
|
|
|
|
### param: GenericAssertions.toEqual.expected
|
|
* since: v1.9
|
|
- `expected` <[any]>
|
|
|
|
Expected value.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toHaveLength
|
|
* since: v1.9
|
|
|
|
Ensures that value has a `.length` property equal to [`param: expected`]. Useful for arrays and strings.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
expect('Hello, World').toHaveLength(12);
|
|
expect([1, 2, 3]).toHaveLength(3);
|
|
```
|
|
|
|
### param: GenericAssertions.toHaveLength.expected
|
|
* since: v1.9
|
|
- `expected` <[int]>
|
|
|
|
Expected length.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toHaveProperty
|
|
* since: v1.9
|
|
|
|
Ensures that property at provided `keyPath` exists on the object and optionally checks that property is equal to the [`param: expected`]. Equality is checked recursively, similarly to [`method: GenericAssertions.toEqual`].
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
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);
|
|
```
|
|
|
|
### param: GenericAssertions.toHaveProperty.keyPath
|
|
* since: v1.9
|
|
- `keyPath` <[string]>
|
|
|
|
Path to the property. Use dot notation `a.b` to check nested properties and indexed `a[2]` notation to check nested array items.
|
|
|
|
### param: GenericAssertions.toHaveProperty.expected
|
|
* since: v1.9
|
|
- `expected` ?<[any]>
|
|
|
|
Optional expected value to compare the property to.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toMatch
|
|
* since: v1.9
|
|
|
|
Ensures that string value matches a regular expression.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = 'Is 42 enough?';
|
|
expect(value).toMatch(/Is \d+ enough/);
|
|
```
|
|
|
|
### param: GenericAssertions.toMatch.expected
|
|
* since: v1.9
|
|
- `expected` <[RegExp]|[string]>
|
|
|
|
Regular expression to match against.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toMatchObject
|
|
* since: v1.9
|
|
|
|
Compares contents of the value with contents of [`param: expected`], performing "deep equality" check. Allows extra properties to be present in the value, unlike [`method: GenericAssertions.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.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
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 }]);
|
|
```
|
|
|
|
### param: GenericAssertions.toMatchObject.expected
|
|
* since: v1.9
|
|
- `expected` <[Object]|[Array]>
|
|
|
|
The expected object value to match against.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toStrictEqual
|
|
* since: v1.9
|
|
|
|
Compares contents of the value with contents of [`param: expected`] **and** their types.
|
|
|
|
Differences from [`method: GenericAssertions.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` and `b` will not equal a literal object with fields `a` and `b`.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = { prop: 1 };
|
|
expect(value).toStrictEqual({ prop: 1 });
|
|
```
|
|
|
|
### param: GenericAssertions.toStrictEqual.expected
|
|
* since: v1.9
|
|
- `expected` <[any]>
|
|
|
|
Expected value.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toThrow
|
|
* since: v1.9
|
|
|
|
Calls the function and ensures it throws an error.
|
|
|
|
Optionally compares the error with [`param: 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.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
expect(() => {
|
|
throw new Error('Something bad');
|
|
}).toThrow();
|
|
|
|
expect(() => {
|
|
throw new Error('Something bad');
|
|
}).toThrow(/something/);
|
|
|
|
expect(() => {
|
|
throw new Error('Something bad');
|
|
}).toThrow(Error);
|
|
```
|
|
|
|
### param: GenericAssertions.toThrow.expected
|
|
* since: v1.9
|
|
- `expected` ?<[any]>
|
|
|
|
Expected error message or error object.
|
|
|
|
|
|
|
|
## method: GenericAssertions.toThrowError
|
|
* since: v1.9
|
|
|
|
An alias for [`method: GenericAssertions.toThrow`].
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
expect(() => {
|
|
throw new Error('Something bad');
|
|
}).toThrowError();
|
|
```
|
|
|
|
### param: GenericAssertions.toThrowError.expected
|
|
* since: v1.9
|
|
- `expected` ?<[any]>
|
|
|
|
Expected error message or error object.
|
|
|
|
|
|
## method: GenericAssertions.any
|
|
* since: v1.9
|
|
|
|
`expect.any()` matches any object instance created from the [`param: constructor`] or a corresponding primitive type. Use it inside [`method: GenericAssertions.toEqual`] to perform pattern matching.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
// 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));
|
|
```
|
|
|
|
### param: GenericAssertions.any.constructor
|
|
* since: v1.9
|
|
- `constructor` <[Function]>
|
|
|
|
Constructor of the expected object like `ExampleClass`, or a primitive boxed type like `Number`.
|
|
|
|
|
|
## method: GenericAssertions.anything
|
|
* since: v1.9
|
|
|
|
`expect.anything()` matches everything except `null` and `undefined`. Use it inside [`method: GenericAssertions.toEqual`] to perform pattern matching.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const value = { prop: 1 };
|
|
expect(value).toEqual({ prop: expect.anything() });
|
|
expect(value).not.toEqual({ otherProp: expect.anything() });
|
|
```
|
|
|
|
|
|
## method: GenericAssertions.arrayContaining
|
|
* since: v1.9
|
|
|
|
`expect.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 [`method: GenericAssertions.toEqual`] to perform pattern matching.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
expect([1, 2, 3]).toEqual(expect.arrayContaining([3, 1]));
|
|
expect([1, 2, 3]).not.toEqual(expect.arrayContaining([1, 4]));
|
|
```
|
|
|
|
### param: GenericAssertions.arrayContaining.expected
|
|
* since: v1.9
|
|
- `expected` <[Array]<[any]>>
|
|
|
|
Expected array that is a subset of the received value.
|
|
|
|
|
|
|
|
## method: GenericAssertions.closeTo
|
|
* since: v1.9
|
|
|
|
Compares floating point numbers for approximate equality. Use this method inside [`method: GenericAssertions.toEqual`] to perform pattern matching. When just comparing two numbers, prefer [`method: GenericAssertions.toBeCloseTo`].
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
expect({ prop: 0.1 + 0.2 }).not.toEqual({ prop: 0.3 });
|
|
expect({ prop: 0.1 + 0.2 }).toEqual({ prop: expect.closeTo(0.3, 5) });
|
|
```
|
|
|
|
### param: GenericAssertions.closeTo.expected
|
|
* since: v1.9
|
|
- `expected` <[float]>
|
|
|
|
Expected value.
|
|
|
|
### param: GenericAssertions.closeTo.numDigits
|
|
* since: v1.9
|
|
- `numDigits` ?<[int]>
|
|
|
|
The number of decimal digits after the decimal point that must be equal.
|
|
|
|
|
|
## method: GenericAssertions.objectContaining
|
|
* since: v1.9
|
|
|
|
`expect.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 [`method: GenericAssertions.toEqual`] to perform pattern matching. Object properties can be matchers to further relax the expectation. See examples.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
// 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') }),
|
|
}));
|
|
```
|
|
|
|
### param: GenericAssertions.objectContaining.expected
|
|
* since: v1.9
|
|
- `expected` <[Object]>
|
|
|
|
Expected object pattern that contains a subset of the properties.
|
|
|
|
|
|
## method: GenericAssertions.stringContaining
|
|
* since: v1.9
|
|
|
|
`expect.stringContaining()` matches a string that contains the expected substring. Use this method inside [`method: GenericAssertions.toEqual`] to perform pattern matching.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
expect('Hello world!').toEqual(expect.stringContaining('Hello'));
|
|
```
|
|
|
|
### param: GenericAssertions.stringContaining.expected
|
|
* since: v1.9
|
|
- `expected` <[string]>
|
|
|
|
Expected substring.
|
|
|
|
|
|
## method: GenericAssertions.stringMatching
|
|
* since: v1.9
|
|
|
|
`expect.stringMatching()` matches a received string that in turn matches the expected pattern. Use this method inside [`method: GenericAssertions.toEqual`] to perform pattern matching.
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
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/),
|
|
});
|
|
```
|
|
|
|
### param: GenericAssertions.stringMatching.expected
|
|
* since: v1.9
|
|
- `expected` <[string]|[RegExp]>
|
|
|
|
Pattern that expected string should match.
|