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.

node.js

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']);
});

browser

man.js

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

man.test.js

import { test } from 'xbell';

test.browser('check primitives value', ({ expect }) => {
  const { man } = await import('./man');

  expect(man.name).toBe('Mike');
});

test.browser('check reference value', ({ expect }) => {
  const { man } = await import('./man');

  const bagRef = man.bag;

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

mixed

man.js

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

man.test.js

import { test, expect } from 'xbell';

test('check primitives value', async ({ page }) => {
  const nameHandle = await page.evaluate(async () => {
    const { man } = await import('./man');
    return man.name;
  });
  expect(nameHandle.toValue()).toBe('Mike');
});

test('check reference value', async ({ page }) => {
  const bagHanlde = await page.evaluate(async () => {
    const { man } = await import('./man');
    return man.bag;
  });
  
  expect(bagHanlde.toValue()).not.toBe(['vodka']);
  // NOTE: should use equal
  expect(bagHanlde.toValue()).toEqual(['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) .

node.js

import { test, expect } from 'xbell';

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

  return null;
}

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

browser

something.js

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

  return null;
}

something.test.js

import { test } from 'xbell';

test.browser('get something is null', ({ expect }) => {
  const { getSomething } = await import('./something');

  expect(getSomething()).toBeNull();
});

toBeTruthy

Signature: expect(received).toBeTruthy()

• received <any>

Returns <void>

node.js

import { test, expect } from 'xbell';

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

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

browser

something.js

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

something.test.js

import { test } from 'xbell';

test.browser('createSomething returns value to be truthy', ({ expect }) => {
  const { createSomething } = await import('./something');

  expect(createSomething()).toBeTruthy();
});

toBeFalsy

Signature: expect(received).toBeFalsy()

• received <any>

Returns <void>

node.js

import { test, expect } from 'xbell';

function createNothing() {
  return null;
}

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

browser

something.js

export function createNothing() {
  return null;
}

something.test.js

import { test } from 'xbell';

test.browser('createSomething returns value to be truthy', ({ expect }) => {
  const { createNothing } = await import('./something');

  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>

nodejs

  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');
  });

browser

uploader.js

export class Uploader {
  upload(file) {
    return Promise.resolve(URL.createObjectURL(file));
  }
}

uploader.test.js

import { test } from 'xbell';

test.browser('upload property is a function', ({ expect }) => {
  const { Uploader } = await import('./uploader');
  const uploader = new Uploader();

  expect(uploader.upload).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