Assertion API

The following assertion methods are available.

Deep Equal

Asserts that actual is deeply equal to expected.

await t.expect( actual ).eql( expected, message, options );
Parameter Type Description
actual Any Type | Selector's Property | ClientFunction Promise A comparison value. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the comparison value is obtained.
expected Any type An expected value.
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Examples:

await t
    .expect({ a: 'bar' }).eql({ a: 'bar' }, 'this assertion will pass')
    .expect({ a: 'bar' }).eql({ a: 'foo' }, 'this assertion will fail');
import { Selector } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    await t.expect(Selector('.className').count).eql(3);
});

Not Deep Equal

Assert that actual is not deeply equal to unexpected.

await t.expect( actual ).notEql( unexpected, message, options );
Parameter Type Description
actual Any Type | Selector's Property | ClientFunction Promise A comparison value. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the comparison value is obtained.
expected Any type An unexpected value.
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Examples:

await t
    .expect({ a: 'bar' }).notEql({ a: 'bar' }, 'this assertion will fail')
    .expect({ a: 'bar' }).notEql({ a: 'foo' }, 'this assertion will pass');
import { Selector } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    await t.expect(Selector('.className').count).notEql(2);
});

Ok

Asserts that actual is truthy.

await t.expect( actual ).ok( message, options );
Parameter Type Description
actual Any Type | Selector's Property | ClientFunction Promise A value that should be truthy. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the actual value is obtained.
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Examples:

await t
    .expect('ok').ok('this assertion will pass')
    .expect(false).ok('this assertion will fail');
import { Selector } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    await t.expect(Selector('#element').exists).ok();
});

Not Ok

Asserts that actual is falsy.

await t.expect( actual ).notOk( message, options );
Parameter Type Description
actual Any Type | Selector's Property | ClientFunction Promise A value that should be falsy. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the actual value is obtained.
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Examples:

await t
    .expect('ok').notOk('this assertion will fail')
    .expect(false).notOk('this assertion will pass');
import { Selector } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    await t.expect(Selector('#element').exists).notOk();
});

Contains

Asserts that actual contains expected.

await t.expect( actual ).contains( expected, message, options );
Parameter Type Description
actual String | Array | Object | Selector's Property | ClientFunction Promise A string that contains the expected substring, an array that contains the expected value or an object that contains the expected property. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the actual value is obtained.
expected Any type The expected value.
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Examples:

await t
    .expect('foo bar').contains('bar', 'string contains the expected substring')
    .expect([1, 2, 3]).contains(2, 'array contains the expected value')
    .expect({ foo: 'bar', hello: 'universe' }).contains({ foo: 'bar' }, 'object contains the expected property');
import { ClientFunction } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    const getLocation = ClientFunction(() => document.location.href.toString());

    await t.expect(getLocation()).contains('example.com');
});

Not Contains

Asserts that actual does not contain expected.

await t.expect( actual ).notContains( expected, message, options );
Parameter Type Description
actual String | Array | Object | Selector's Property | ClientFunction Promise A string that should not contain the expected substring, an array that should not contain the expected value or an object that should not contain the expected property. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the actual value is obtained.
expected Any type The expected value.
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Examples:

await t
    .expect('foo bar').notContains('baz', 'string does not contain a substring')
    .expect([1, 2, 3]).notContains(4, 'array does not contain a value')
    .expect({ foo: 'bar', hello: 'universe' }).notContains({ buzz: 'abc' }, 'object does not contain a property');
import { ClientFunction } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    const getLocation = ClientFunction(() => document.location.href.toString());

    await t.expect(getLocation()).notContains('devexpress.com');
});

Type Of

Asserts that type of actual is typeName.

await t.expect( actual ).typeOf( typeName, message, options );
Parameter Type Description
actual Any Type | Selector's Property | ClientFunction Promise A comparison value. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the actual value is obtained.
typeName String The expected type of an actual value.
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Examples:

await t
    .expect({ a: 'bar' }).typeOf('object', 'it\'s an object')
    .expect(/bar/).typeOf('regexp', 'it\'s a regular expression')
    .expect(null).typeOf('null', 'it\'s a null');
import { Selector } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    await t.expect(Selector('#element').getAttribute('attr')).typeOf('string');
});

Not Type of

Asserts that type of actual is not typeName.

await t.expect( actual ).notTypeOf( typeName, message, options );
Parameter Type Description
actual Any Type | Selector's Property | ClientFunction Promise A comparison value. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the actual value is obtained.
typeName String An unexpected type of actual value.
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Example:

await t.expect('bar').notTypeOf('number', 'string is not a number');
import { Selector } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    await t.expect(Selector('#element').getAttribute('attr')).notTypeOf('null');
});

Greater than

Asserts that actual is strictly greater than expected.

await t.expect( actual ).gt( expected, message, options );
Parameter Type Description
actual Number | Selector's Property | ClientFunction Promise A value that should be greater than expected. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the actual value is obtained.
expected Any type A comparison value.
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Example:

await t.expect(5).gt(2, '5 is strictly greater than 2');
import { Selector } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    await t.expect(Selector('#element').clientWidth).gt(300);
});

Greater than or Equal to

Asserts that actual is greater than or equal to expected.

await t.expect( actual ).gte( expected, message, options );
Parameter Type Description
actual Number | Selector's Property | ClientFunction Promise A value that should be greater than or equal to expected. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the actual value is obtained.
expected Any type A comparison value.
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Examples:

await t
    .expect(5).gte(2, '5 is greater or equal than 2')
    .expect(2).gte(2, '2 is greater or equal than 2 ');
import { Selector } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    await t.expect(Selector('#element').clientWidth).gte(50);
});

Less than

Asserts that actual is strictly less than expected.

await t.expect( actual ).lt( expected, message, options );
Parameter Type Description
actual Number | Selector's Property | ClientFunction Promise A value that should be less than expected. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the actual value is obtained.
expected Any type A comparison value.
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Example:

await t.expect(2).lt(5, '2 is strictly less than 5');
import { Selector } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    await t.expect(Selector('#element').offsetHeight).lt(25);
});

Less than or Equal to

Asserts that actual is less than or equal to expected.

await t.expect( actual ).lte( expected, message, options );
Parameter Type Description
actual Number | Selector's Property | ClientFunction Promise A value that should be less than or equal to expected. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the actual value is obtained.
expected Any type A comparison value.
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Examples:

await t
    .expect(2).lte(5, '2 is less or equal than 5')
    .expect(2).lte(2, '2 is less or equal than 2 ');
import { Selector } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    await t.expect(Selector('#element').offsetHeight).lte(400);
});

Within

Asserts that actual is within a range from start to finish. Bounds are inclusive.

await t.expect( actual ).within( start, finish, message, options );
Parameter Type Description
actual Number | Selector's Property | ClientFunction Promise A comparison value. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the actual value is obtained.
start Number A lower bound of range (included).
finish Number An upper bound of range (included).
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Example:

await t.expect(5).within(3, 10, 'this assertion will pass');
import { Selector } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    await t.expect(Selector('#element').scrollTop).within(300, 400);
});

Not Within

Asserts that actual is not within a range from start to finish. Bounds are inclusive.

await t.expect( actual ).notWithin( start, finish, message, options );
Parameter Type Description
actual Number | Selector's Property | ClientFunction Promise A comparison value. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the actual value is obtained.
start Number A lower bound of range (included).
finish Number An upper bound of range (included).
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Example:

await t.expect(1).notWithin(3, 10, 'this assertion will pass');
import { Selector } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    await t.expect(Selector('#element').scrollTop).notWithin(100, 200);
});

Match

Asserts that actual matches the re regular expression.

await t.expect( actual ).match( re, message, options );
Parameter Type Description
actual String | Selector's Property | ClientFunction Promise A comparison value. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the actual value is obtained.
re RegExp A regular expression that is expected to match actual.
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Example:

await t.expect('foobar').match(/^f/, 'this assertion will be passed');
import { ClientFunction } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    const getLocation = ClientFunction(() => document.location.href.toString());

    await t.expect(getLocation()).match(/\.com/);
});

Not Match

Asserts that actual does not match the re regular expression.

await t.expect( actual ).notMatch( re, message, options );
Parameter Type Description
actual String | Selector's Property | ClientFunction Promise A comparison value. If you pass a selector's property or a client function promise, the Smart Assertion Query Mechanism is activated and the assertion automatically waits until the actual value is obtained.
re RegExp A regular expression that is expected not to match actual.
message (optional) String An assertion message that will be displayed in the report if the test fails.
options (optional) Object See Options.

Example:

await t.expect('foobar').notMatch(/^b/, 'this assertion will be passed');
import { ClientFunction } from 'testcafe';

fixture `My fixture`;

test('My test', async t => {
    const getLocation = ClientFunction(() => document.location.href.toString());

    await t.expect(getLocation()).notMatch(/\.co\.uk/);
});