Skip to main content

Expect

toBenode.jsbrowser​

Signature: expect(received).toBe(expected)

  • received <any>
  • expected <any>

Returns <void>

"toBe" is used to compare whether the primitive values are equal or whether objects belong to the same reference.

import { test, expect } from 'xbell';

const man = {
  name: 'Mike',
  bag: ['vodka'],
};

test('check primitives value', () => {
  expect(man.name).toBe('Mike');
});

test('check reference value', () => {
  const bagRef = man.bag;

  expect(man.bag).toBe(bagRef);
  expect(man.bag).not.toBe(['vodka']);
});

toEqual​

Signature: expect(received).toEqual(value)

  • received <any>
  • value <any>

Returns <void>

toEqual is used to assert that compare recursively all properties of object instances (also known as "deep" equality).

Example

import { test } from 'xbell';

test('toEqual', ({ expect }) => {
  const obj1 = {
    key: 'value',
  };

  const obj2 = {
    key: 'value',
  };

  expect(obj1).not.toBe(obj2);
  // to euqal
  expect(obj1).toEqual(obj2);
});

toContain​

Signature: expect(received).toContain(value)

  • received<Array | string | IterableIterator>
  • value <any>

Returns <void>

toContain is used to assert that an item is in an array. It uses ===, a strict equality check.

Example

import { test } from 'xbell';

test('toContain', ({ expect }) => {
  expect([1, 2, 3]).toContain(1);
  expect('abc').toContain('a');
});

toContainEqual​

Signature: expect(received).toContainEqual(value)

  • received<Array | string | IterableIterator>
  • value <any>

Returns <void>

toContainEqual is used to assert that an item is in an array. It uses toEqual to compare item.

Example

import { test } from 'xbell';

test('toContainEqual', ({ expect }) => {
  expect([{ key: 'value' }]).toContainEqual({ key: 'value' });
  expect('abc').toContainEqual('a');
});

toBeDefinednode.jsbrowser​

Signature: expect(received).toBeDefined()

  • received <any>

Returns <void>

toBeDefined() is used to assert that the value is not equal to undefined , same as .not.toBe(undefined) .

Usually used to check if a function has a return value.

Example

import { test, expect } from 'xbell';

function createSomething() {
  return Math.random();
}

test('it always creates something', () => {
  expect(createSomething()).toBeDefined();
});

toBeUndefined node.jsbrowser​

Signature: expect(received).toBeUndefined()

  • received <any>

Returns <void>

toBeUndefined() is used to assert that the value is undefined , same as toBe(undefined) .

Usually used to check if a function returns undefined.

Exmaple

import { test, expect } from 'xbell';

function getName(person) {
  return person?.name;
}

test('getName returns undefined when passed a empty value', () => {
  expect(getName()).toBeUndefined();
});

toBeNull node.jsbrowser​

Signature: expect(received).toBeNull()

  • received <any>

Returns <void>

toBeNull() asserts that the value is null , same as toBe(null) .

import { test, expect } from 'xbell';

function getSomething(make) {
  if (make) {
    return Math.random();
  }

  return null;
}

test('get something is null', () => {
  expect(getSomething()).toBeNull();
});

toBeTruthy​

Signature: expect(received).toBeTruthy()

  • received <any>

Returns <void>

import { test, expect } from 'xbell';

function createSomething() {
  return 1 + Math.random();
}

test('createSomething returns value to be truthy', () => {
  expect(createSomething()).toBeTruthy();
});

toBeFalsy​

Signature: expect(received).toBeFalsy()

  • received <any>

Returns <void>

import { test, expect } from 'xbell';

function createNothing() {
  return null;
}

test('createSomething returns value to be falsy', () => {
  expect(createNothing()).toBeFalsy();
});

toHaveLength​

Signature: expect(received).toHaveLength(length)

  • received <{ length: number }>
  • length <number>

toHaveLength is used to check that an object has a .length property and it is set to a certain numeric value.

Example

test('toHaveLength', ({ expect }) => {
  expect([1, 2, 3]).toHaveLength(3);
  expect('a').toHaveLength(1);
  expect('').not.toHaveLength(1);
});

toBeTypeOf​

Signature: expect(received).toBeTypeOf(type)

  • received <any>
  • type <{'function' | 'number' | 'string' | 'object' | 'boolean' | 'undefined' | 'symbol' | 'bigint'}>

Returns <void>

  import { test } from 'xbell';

  class Dog {
    eat() {}
  }

  test('the dog has a method of eating', ({ expect }) => {
    const dog = new Dog();

    expect(dog.eat).toBeTypeOf('function');
  });

toBeLessThan​

Signature: expect(received).toBeLessThan(num)

  • received <number>
  • num <number>

Returns <void>

toBeLessThanOrEqual​

Signature: expect(received).toBeLessThanOrEqual(num)

  • received <number>
  • num <number>

Returns <void>

toBeLessThanOrEqual is used to assert that the value is less than or equal to the target value.

Example

import { test } from 'xbell';

test('toBeLessThanOrEqual', ({ expect }) => {
  expect(6).toBeLessThanOrEqual(6);
  expect(6).toBeLessThanOrEqual(8);
});

toBeGreaterThan​

Signature: expect(received).toBeGreaterThan(num)

  • received <number>
  • num <number>

Returns <void>

toBeGreaterThan is used to assert that the value is greater than the target value.

Example

import { test } from 'xbell';

test('toBeLessThanOrEqual', ({ expect }) => {
  expect(6).toBeGreaterThan(5);
});

toBeGreaterThanOrEqual​

Signature: expect(received).toBeGreaterThanOrEqual(num)

  • received <number>
  • num <number>

Returns <void>

toBeGreaterThanOrEqual is used to assert that the value is greater than or equal to the target value.

Example

import { test } from 'xbell';

test('toBeGreaterThanOrEqual', ({ expect }) => {
  expect(6).toBeGreaterThanOrEqual(5);
  expect(6).toBeGreaterThanOrEqual(6);
});

toBeNaN​

Signature: expect(received).toBeNaN()

  • received <number>

Returns <void>

toBeNaN is used to assert that the value is NaN.

Example

test('toBeNaN', ({ expect }) => {
  expect(NaN).toBeNaN();
  expect(1).not.toBeNaN();
});

toBeCloseTo​

Signature: expect(received).toBeCloseTo(num, numDigits?)

  • received <number>
  • num <number>
  • numDigits <number>

Returns <void>

Use toBeCloseTo to compare floating point numbers for approximate equality.

The optional numDigits argument limits the number of digits to check after the decimal point. For the default value 2, the test criterion is Math.abs(expected - received) < 0.005 (that is, 10 ** -2 / 2).

Intuitive equality comparisons often fail, because arithmetic on decimal (base 10) values often have rounding errors in limited precision binary (base 2) representation. For example, this test fails:

test('adding works sanely with decimals', ({ expect }) => {
  expect(0.2 + 0.1).toBe(0.3); // Fails!
});

Example

test('adding works sanely with decimals', ({ expect }) => {
  expect(0.2 + 0.1).toBeCloseTo(0.3);
});

toHaveProperty​

Signature: expect(received).toHaveProperty(key, value?)

  • received <number>
  • key <string> object's key
  • value? <any>

Returns <void>

toHaveBeenCalled​

Signature: expect(received).toHaveBeenCalled()

  • received <Mock> The mock function

Returns <void>

Use toHaveBeenCalled to ensure that a mock function is called.

Exmaple

import { test } from 'xbell';

test('toHaveBeenCalled', ({ expect, fn, spyOn }) => {
  const object = {
    method() {}
  };

  const handleClick = fn();
  spyOn(object, 'method');

  handleClick();
  object.method();

  expect(handleClick).toHaveBeenCalled();
  expect(object.method).toHaveBeenCalled();
});

toHaveBeenCalledTimes​

Signature: expect(received).toHaveBeenCalledTimes(times)

  • received <Mock> The mock function
  • times <number>

Returns <void>

Use toHaveBeenCalledTimes to ensure that a mock function got called exact number of times.

import { test } from 'xbell';

test('toHaveBeenCalledTimes', ({ expect, fn, spyOn }) => {
  const object = {
    method() {}
  };

  const handleClick = fn();
  spyOn(object, 'method');

  handleClick();
  object.method();
  object.method();

  expect(handleClick).toHaveBeenCalledTimes(1);
  expect(object.method).toHaveBeenCalledTimes(2);
});

toHaveBeenCalledWith​

Signature: expect(received).toHaveBeenCalledWith(...args)

  • received <Mock> The mock function
  • args <any[]> Expect arguments

Returns <void>

Use toHaveBeenCalledWith to ensure that a mock function was called with specific arguments. The arguments are checked with the same algorithm that toEqual uses.

Example

import { test } from 'xbell';

test('toHaveBeenCalledWith', ({ expect, fn, spyOn }) => {
  const object = {
    method() {}
  };

  const handleClick = fn();
  spyOn(object, 'method');

  handleClick('str');
  object.method(1, 2);

  expect(handleClick).toHaveBeenCalledWith('str');
  expect(object.method).toHaveBeenCalledWith(1, 2);
});

toHaveBeenLastCalledWith​

Signature: expect(received).toHaveBeenLastCalledWith(...args)

  • received <Mock> The mock function
  • args <any[]> Expect arguments

Returns <void>

Use toHaveBeenLastCalledWith to ensure that the mock function is called the last time with the specified arguments.

Example

import { test } from 'xbell';

test('toHaveBeenLastCalledWith', ({ expect, fn, spyOn }) => {
  const handleClick = fn();

  handleClick('str');
  handleClick(1, 2);

  expect(handleClick).toHaveBeenCalledWith('str');
  expect(handleClick).toHaveBeenLastCalledWith(1, 2);
});

toHaveBeenNthCalledWith​

Signature: expect(received).toHaveBeenNthCalledWith(nthCall, ...args)

  • received <Mock> The mock function
  • nthCall <number> The NTH call
  • args <any[]> Expect arguments

Returns <void>

Use toHaveBeenNthCalledWith to ensure that the mock function was called the nth time with the specified arguments.

Example

import { test } from 'xbell';

test('toHaveBeenNthCalledWith', ({ expect, fn, spyOn }) => {
  const handleClick = fn();

  handleClick('one', 'one');
  handleClick('two', 'two');
  handleClick('three', 'three');

  expect(handleClick).toHaveBeenNthCalledWith(1, 'one', 'one');
  expect(handleClick).toHaveBeenNthCalledWith(3, 'three', 'three');
});

toHaveReturned​

Signature: expect(received).toHaveReturned()

  • received <Mock> The mock function

Returns <void>

Use toHaveReturned to ensure that a mock function successfully returned (i.e., did not throw an error) at least one time.

Example

import { test } from 'xbell';

test('toHaveReturned', ({ expect, fn, spyOn }) => {
  const add = (a: number, b: number) => a + b;
  const someOne = {
    makeSomething() {
      return 'something';
    },
  };

  const mockAdd = fn(add);
  spyOn(someOne, 'makeSomething');

  add(1, 1);
  someOne.makeSomething();

  expect(mockAdd).toHaveReturned();
  expect(someOne.makeSomething).toHaveReturned();
});

toHaveReturnedTimes​

Signature: expect(received).toHaveReturnedTimes(times)

  • received <Mock> The mock function
  • times <number> Number of calls

Returns <void>

Use toHaveReturnedTimes to ensure that a mock function returned successfully (i.e., did not throw an error) an exact number of times. Any calls to the mock function that throw an error are not counted toward the number of times the function returned.

Example

import { test } from 'xbell';

test('toHaveReturnedTimes', ({ expect, fn, spyOn }) => {
  const add = (a: number, b: number) => a + b;
  const someOne = {
    makeSomething() {
      return 'something';
    },
  };

  const mockAdd = fn(add);
  spyOn(someOne, 'makeSomething');

  add(1, 1);
  add(1, 1);
  someOne.makeSomething();
  someOne.makeSomething();
  someOne.makeSomething();

  expect(mockAdd).toHaveReturnedTimes(2);
  expect(someOne.makeSomething).toHaveReturnedTimes(3);
});

toHaveReturnedWith​

Signature: expect(received).toHaveReturnedWith(value)

  • received <Mock> The mock function
  • value <any> The return value

Returns <void>

Use toHaveReturnedWith to ensure that a mock function was called with specific return value. The return value are checked with the same algorithm that toEqual uses.

Example

import { test } from 'xbell';

test('toHaveReturnedWith', ({ expect, fn, spyOn }) => {
  const add = (a: number, b: number) => a + b;
  const someOne = {
    makeSomething() {
      return 'something';
    },
  };

  const mockAdd = fn(add);
  spyOn(someOne, 'makeSomething');

  add(1, 1);
  someOne.makeSomething();

  expect(mockAdd).toHaveReturnedWith(2);
  expect(someOne.makeSomething).toHaveReturnedWith('something');
});

toHaveLastReturnedWith​

Signature: expect(received).toHaveLastReturnedWith(value)

  • received <Mock> The mock function
  • value <any> The return value of the last called

Returns <void>

Use toHaveLastReturnedWith to ensure that a mock function was called the last time with specific return value. The return value are checked with the same algorithm that toEqual uses.

Example

import { test } from 'xbell';

test('toHaveLastReturnedWith', ({ expect, fn, spyOn }) => {
  const add = (a: number, b: number) => a + b;
  const someOne = {
    makeSomething() {
      return 'something';
    },
  };

  const mockAdd = fn(add);
  spyOn(someOne, 'makeSomething');

  add(1, 1);
  add(2, 2);
  someOne.makeSomething();

  expect(mockAdd).toHaveLastReturnedWith(4);
  expect(someOne.makeSomething).toHaveLastReturnedWith('something');
});

toHaveNthReturnedWith​

Signature: expect(received).toHaveNthReturnedWith(nthCall, value)

  • received <Mock> The mock function
  • nthCall <number> The NTH call
  • value <any> The return value of the last called

Returns <void>

Use toHaveNthReturnedWith to ensure that a mock function was called the nth time with specific return value. The return value are checked with the same algorithm that toEqual uses.

Example

import { test } from 'xbell';

test('toHaveNthReturnedWith', ({ expect, fn, spyOn }) => {
  const add = (a: number, b: number) => a + b;
  const someOne = {
    makeSomething() {
      return 'something';
    },
  };

  const mockAdd = fn(add);
  spyOn(someOne, 'makeSomething');

  add(1, 1);
  add(20, 20);
  add(3, 3);
  someOne.makeSomething();

  expect(mockAdd).toHaveNthReturnedWith(2, 40);
  expect(someOne.makeSomething).toHaveNthReturnedWith(1, 'something');
});

toBeVisible node.js​

Signature: expect(received).toBeVisible(options?)

  • received <Locator | ElementHandle> Locator or element handle
  • options? < object >
    • timeout? <number> Time to retry the assertion for.

Returns <void>

Use toBeVisible to ensure that a locator or element handle points to an attached and visible DOM node.

import { test } from 'xbell';

test('toBeVisible', ({ expect, page, spyOn }) => {
  await page.goto('https://github.com/x-bell/xbell')

  const slogan = page.getByText('Make Web testing easy.')

  await expect(slogan).toBeVisible();
});

toBeHidden​

Signature: expect(received).toBeHidden(options?)

  • received <Locator | ElementHandle> Locator or element handle
  • options? < object >
    • timeout? <number> Time to retry the assertion for.

Returns <void>

Use toBeHidden to ensure that a locator or element handle either does not resolve to any DOM node, or resolves to a non-visible one.

import { test } from 'xbell';

test('toBeHidden', ({ expect, page, spyOn }) => {
  await page.goto('https://github.com/x-bell/xbell')

  const slogan = page.getByText('Make Web testing hard.')

  await expect(slogan).toBeHidden();
});

toBeChecked​

toBeDisabled​

toBeEmpty​

toBeEnabled​

toBeFocused​

toHaveText​

toContainText​

toHaveAttribute​

toHaveClass​

toHaveId​

toHaveCount​

toMatchImageScreenshot​

toMatchSnapshot​