jest-extended

What is jest-extended?

jest-extended is a set of additional matchers for Jest, a popular JavaScript testing framework. It extends Jest's built-in matchers with a variety of new ones, making it easier to write more expressive and comprehensive tests.

What are jest-extended's main functionalities?

Array Matchers

Checks if the value is an array.

expect([1, 2, 3]).toBeArray();

Object Matchers

Checks if the object contains the specified key.

expect({ a: 1 }).toContainKey('a');

String Matchers

Checks if the string starts with the given substring.

expect('hello world').toStartWith('hello');

Number Matchers

Checks if the number is within the specified range.

expect(10).toBeWithin(5, 15);

Date Matchers

Checks if the date is after the specified date.

expect(new Date('2023-01-01')).toBeAfter(new Date('2022-12-31'));

Other packages similar to jest-extended

chai

Chai is an assertion library for Node.js and the browser that can be delightfully paired with any JavaScript testing framework. It provides a variety of assertion styles (should, expect, assert) and is highly extensible.

should

Should.js is an expressive, readable, and powerful assertion library for Node.js and the browser. It extends Object.prototype to provide a more natural way to write assertions.

expect

Expect is a minimalistic assertion library for JavaScript. It is often used with Jest but can be used standalone. It provides a set of simple and intuitive matchers.

README

jest-extended

🃏💪

Additional Jest matchers

---

Problem

Jest is an amazing test running and has some awesome assertion APIs built in by default. However there are times when having more specific matchers (assertions) would be far more convenient.

Solution

jest-extended aims to add additional matchers to Jest's default ones making it easy to test everything 🙌

Contributing

If you've come here to help contribute - Thanks! Take a look at the contributing docs as a way of getting started.

---

• Installation
• Setup
• API
  • .toBeTrue()
  • .toBeFalse()
  • .pass(message)
  • .fail(message)
  • .toBeNil()
  • .toBeNaN()
  • .toBeEmpty()
  • .toBeWithin(start, end)
  • .toContainKey(key)
  • .toContainKeys([keys])
  • .toContainAllKeys([keys])
  • .toContainAnyKeys([keys])
  • .toContainValue(value)
  • .toContainValues([values])
  • .toContainAllValues([values])
  • .toContainAnyValues([values])
  • .toContainEntry([key, value])
  • .toContainEntries([[key, value]])
  • .toContainAllEntries([[key, value]])
  • .toContainAnyEntries([[key, value]])
  • .toSatisfy(predicate)
  • .toHaveAllMembers([members])
  • .toHaveSomeMembers([members])
  • .toBeOneOf([members])
  • .toBeExtensible()
  • .toBeSealed()
  • .toBeFrozen()
  • .toBeFinite()
  • .toBePositive()
  • .toBeNegative()
  • .toBeEven()
  • .toBeOdd()
  • .toBeFunction()
  • .toBeObject()
  • .toBeArray()
  • .toBeString()
  • .toBeNumber()
  • .toBeBoolean()
  • .toStartWith(prefix)
  • .toEndWith(suffix)
  • .toInclude(substring)
  • .toIncludeRepeated(substring, times)
  • .toIncludeMultiple([substring])
  • .toEqualCaseInsensitive(string)
• Contributors
• LICENSE

Installation

With npm:

npm install --save-dev jest-extended

With yarn:

yarn add -D jest-extended

Setup

Add jest-extended to your Jest setupTestFrameworkScriptFile configuration. See for help

"jest": {
  "setupTestFrameworkScriptFile": "jest-extended"
}

API

.toBeTrue()

Use .toBeTrue when checking a value is equal (===) to true.

test('is jest cool', () => {
  expect(isJestCool()).toBeTrue();
  expect(false).not.toBeTrue();
});

.toBeFalse()

Note: Currently unimplemented

Use .toBeFalse when checking a value is equal (===) to false.

test('returns false', () => {
  expect(areWeThereYet()).toBeFalse();
  expect(true).not.toBeFalse();
});

.pass(message)

Note: Currently unimplemented

Passing assertion.

expect().pass('should pass');

.fail(message)

Note: Currently unimplemented

Failing assertion.

expect().fail('test should fail');

.toBeNil()

Note: Currently unimplemented

Use .toBeNil when checking a value is null or undefined.

test('passes when value is null or undefined', () => {
  expect(null).toBeNil();
  expect(undefined).toBeNil();
  expect(true).not.toBeNil();
});

.toBeNaN()

Note: Currently unimplemented

Use .toBeNaN when checking a value is NaN.

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

.toBeEmpty()

Note: Currently unimplemented

Use .toBeEmpty when checking if a String '', Array [] or Object {} is empty.

test('passes when given an empty string', () => {
  expect('').toBeEmpty();
  expect('hello').not.toBeEmpty();
});

test('passes when given an empty array', () => {
  expect([]).toBeEmpty();
  expect(['hello']).not.toBeEmpty();
});

test('passes when given an empty object', () => {
  expect({}).toBeEmpty();
  expect({ hello: 'world' }).not.toBeEmpty();
});

.toBeWithin(start, end)

Use .toBeWithin when checking if a number is in between the given bounds of: start (inclusive) and end (exclusive).

test('passes when number is within given bounds', () => {
  expect(1).toBeWithin(1, 3);
  expect(2).toBeWithin(1, 3);
  expect(3).not.toBeWithin(1, 3);
});

.toContainKey(key)

Use .toContainKey when checking if an object contains the provided key.

test('passes when object contains the given key', () => {
  const o = { a: 'foo', b: 'bar', c: 'baz' };
  expect(o).toContainKey('a');
  expect(o).toContainKey('b');
  expect(o).toContainKey('c');
  expect(o).not.toContainKey('d');
});

.toContainKeys([keys])

Use .toContainKeys when checking if an object has all of the provided keys.

test('passes when object contains all keys', () => {
  const o = { a: 'foo', b: 'bar', c: 'baz' };
  expect(o).toContainKeys(['a', 'b']);
  expect(o).toContainKeys(['b', 'c']);
  expect(o).not.toContainKeys(['d']);
});

.toContainAllKeys([keys])

Use .toContainAllKeys when checking if an object only contains all of the provided keys.

test('passes when object only contains all keys', () => {
  const o = { a: 'hello', b: 'world' };
  expect(o).toContainAllKeys(['a', 'b']);
  expect(o).toContainAllKeys(['b', 'a']);
  expect(o).not.toContainAllKeys(['b']);
});

.toContainAnyKeys([keys])

Use .toContainAnyKeys when checking if an object contains at least one of the provided keys.

test('passes when object contains at least one matching key', () => {
  const o = { a: 'hello', b: 'world' };
  expect(o).toContainAnyKeys(['a']);
  expect(o).toContainAnyKeys(['b']);
  expect(o).toContainAnyKeys(['b', 'c']);
  expect(o).not.toContainAnyKeys(['c']);
});

.toContainValue(value)

Use .toContainValue when checking if an object contains the provided value.

test('passes when object contains given value', () => {
  const o = { a: 'foo', b: 'bar', c: 'baz' };
  expect(o).toContainValue('foo');
  expect(o).toContainValue('bar');
  expect(o).not.toContainValue('qux');
});

.toContainValues([values])

Use .toContainValues when checking if an object contains all of the provided values.

test('passes when object contains all of the given values', () => {
  const o = { a: 'foo', b: 'bar', c: 'baz' };
  expect(o).toContainValues(['foo']);
  expect(o).toContainValues(['baz', 'bar']);
  expect(o).not.toContainValues(['qux', 'foo']);
});

.toContainAllValues([values])

Note: Currently unimplemented

Use .toContainAllValues when checking if an object only contains all of the provided values.

test('passes when object only contains all of the given values', () => {
  const o = { a: 'foo', b: 'bar', c: 'baz' };
  expect(o).toContainAllValues(['foo', 'bar', 'baz']);
  expect(o).toContainAllValues(['baz', 'bar', 'foo']);
  expect(o).not.toContainAllValues(['bar', 'foo']);
});

.toContainAnyValues([values])

Note: Currently unimplemented

Use .toContainAnyValues when checking if an object contains at least one of the provided values.

test('passes when object contains at least one of the given values', () => {
  const o = { a: 'foo', b: 'bar', c: 'baz' };
  expect(o).toContainAnyValues(['qux', 'foo']);
  expect(o).toContainAnyValues(['qux', 'bar']);
  expect(o).toContainAnyValues(['qux', 'baz']);
  expect(o).not.toContainAnyValues(['qux']);
});

.toContainEntry([key, value])

Note: Currently unimplemented

Use .toContainEntry when checking if an object contains the provided entry.

test('passes when object contains given entry', () => {
  const o = { a: 'foo', b: 'bar', c: 'baz' };
  expect(o).toContainEntry(['a', 'foo']);
  expect(o).toContainEntry(['b', 'bar']);
  expect(o).toContainEntry(['c', 'baz']);
  expect(o).not.toContainEntry(['a', 'qux']);
});

.toContainEntries([[key, value]])

Note: Currently unimplemented

Use .toContainEntries when checking if an object contains all of the provided entries.

test('passes when object contains all of the given entries', () => {
  const o = { a: 'foo', b: 'bar', c: 'baz' };
  expect(o).toContainEntries([['a', 'foo']]);
  expect(o).toContainEntries([['c', 'baz'], ['a', 'foo']]);
  expect(o).not.toContainEntries([['b', 'qux'], ['a', 'foo']]);
});

.toContainAllEntries([[key, value]])

Note: Currently unimplemented

Use .toContainAllEntries when checking if an object only contains all of the provided entries.

test('passes when object only contains all of the given entries', () => {
  const o = { a: 'foo', b: 'bar', c: 'baz' };
  expect(o).toContainAllEntries([['a', 'foo'], ['b', 'bar'], ['c', 'baz']]);
  expect(o).not.toContainAllEntries([['a', 'foo'], ['b', 'bar']]);
});

.toContainAnyEntries([[key, value]])

Note: Currently unimplemented

Use .toContainAnyEntries when checking if an object contains at least one of the provided entries.

test('passes when object contains at least one of the given entries', () => {
  const o = { a: 'foo', b: 'bar', c: 'baz' };
  expect(o).toContainAnyEntries([['a', 'qux'], ['a', 'foo']]);
  expect(o).toContainAnyEntries([['a', 'qux'], ['b', 'bar']]);
  expect(o).toContainAnyEntries([['a', 'qux'], ['c', 'baz']]);
  expect(o).not.toContainAnyEntries([['d', 'qux']]);
});

.toSatisfy(predicate)

Note: Currently unimplemented

Use .toSatisfy when you want to use a custom matcher by supplying a predicate function that returns a Boolean.

test('passes when value passes given predicate', () => {
  const greaterThanOneButNotThree = n => n > 1 && n !== 3;
  expect(100).toSatisfy(greaterThanOneButNotThree);
  expect(0).not.toSatisfy(greaterThanOneButNotThree);
  expect(3).not.toSatisfy(greaterThanOneButNotThree);
});

.toHaveAllMembers([members])

Note: Currently unimplemented

Use .toHaveAllMembers when checking if an Array contains all of the same members of a given set.

test('passes when given array values match the members of the set', () => {
  expect([1, 2, 3]).toHaveAllMembers([2, 1, 3]);
  expect([1, 2, 2]).toHaveAllMembers([2, 1]);
});

.toHaveSomeMembers([members])

Note: Currently unimplemented

Use .toHaveSomeMembers when checking if an Array contains some of the members of a given set.

test('passes when given array values match the members of the set', () => {
  expect([1, 2, 3]).toHaveSomeMembers([2, 1, 3]);
  expect([1, 2, 2]).toHaveSomeMembers([2]);
  expect([1, 2, 2]).not.toHaveSomeMembers([3]);
});

.toBeOneOf([members])

Use .toBeOneOf when checking if a value is a member of a given Array.

test('passes when value is in given array', () => {
  expect(1).toBeOneOf([1, 2, 3]);
  expect(4).not.toBeOneOf([1, 2, 3]);
});

.toBeExtensible()

Use .toBeExtensible when checking if an object is extensible.

test('passes when value is extensible', () => {
  expect({a: 1}).toBeExtensible();
  expect(1).not.toBeExtensible();
});

.toBeSealed()

Note: Currently unimplemented

Use .toBeSealed when checking if an object is sealed.

test('passes when value is sealed', () => {
  expect(Object.seal({})).toBeSealed();
  expect({}).not.toBeSealed();
  expect(1).not.toBeSealed();
});

.toBeFrozen()

Use .toBeFrozen when checking if an object is frozon.

test('passes when value is frozen', () => {
  expect(Object.frozen({})).toBeFrozen();
  expect({}).not.toBeFrozen();
  expect(1).not.toBeFrozen();
});

.toBeFinite()

Use .toBeFinite when checking if a value is a Number, not NaN or Infinity.

test('passes when value is a finite number', () => {
  expect(1).toBeFinite();
  expect(Infinity).not.toBeFinite();
  expect(NaN).not.toBeFinite();
});

.toBePositive()

Note: Currently unimplemented

Use .toBePositive when checking if a value is a positive Number.

test('passes when value is a positive number', () => {
  expect(1).toBePositive();
  expect(Infinity).not.toBePositive();
  expect(-1).not.toBePositive();
  expect(NaN).not.toBePositive();
});

.toBeNegative()

Use .toBeNegative when checking if a value is a negative Number.

test('passes when value is a negative number', () => {
  expect(-1).toBeNegative();
  expect(-Infinity).not.toBeNegative();
  expect(1).not.toBeNegative();
  expect(NaN).not.toBeNegative();
});

.toBeEven()

Use .toBeEven when checking if a value is an even Number.

test('passes when value is an even number', () => {
  expect(2).toBeEven();
  expect(1).not.toBeEven();
  expect(NaN).not.toBeEven();
});

.toBeOdd()

Note: Currently unimplemented

Use .toBeOdd when checking if a value is an odd Number.

test('passes when value is an odd number', () => {
  expect(1).toBeOdd();
  expect(2).not.toBeOdd();
  expect(NaN).not.toBeOdd();
});

.toBeFunction()

Note: Currently unimplemented

Use .toBeFunction when checking if a value is a Function.

test('passes when value is a function', () => {
  function noop = () {};
  expect(() => {}).toBeFunction();
  expect(function() {}).not.toBeFunction();
  expect(noop).toBeFunction();
  expect(true).not.toBeFunction();
});

.toBeObject()

Use .toBeObject when checking if a value is an Object.

test('passes when value is an object', () => {
  expect({}).toBeObject();
  expect({ a: 'hello' }).toBeObject();
  expect(true).not.toBeObject();
});

.toBeArray()

Note: Currently unimplemented

Use .toBeArray when checking if a value is an Array.

test('passes when value is an array', () => {
  expect([]).toBeArray();
  expect([1]).toBeArray();
  expect(true).not.toBeArray();
});

.toBeString()

Use .toBeString when checking if a value is a String.

test('passes when value is a string', () => {
  expect('').toBeString();
  expect('hello').toBeString();
  expect(new String('hello')).toBeString();
  expect(true).not.toBeString();
});

.toBeNumber()

Note: Currently unimplemented

Use .toBeNumber when checking if a value is a Number.

test('passes when value is a number', () => {
  expect(1).toBeNumber();
  expect(NaN).toBeNumber();
  expect(Infinity).toBeNumber();
  expect(true).not.toBeNumber();
});

.toBeBoolean()

Note: Currently unimplemented

Use .toBeBoolean when checking if a value is a Boolean.

test('passes when value is a boolean', () => {
  expect(false).toBeBoolean();
  expect(true).toBeBoolean();
  expect(1 === 1).toBeBoolean();
  expect(1).not.toBeBoolean();
});

.toStartWith(prefix)

Use .toStartWith when checking if a String starts with a given String prefix.

test('passes when value is starts with given string', () => {
  expect('hello world').toStartWith('hello');
  expect('hello world').not.toStartWith('world');
});

.toEndWith(suffix)

Use .toEndWith when checking if a String ends with a given String suffix.

test('passes when value is ends with given string', () => {
  expect('hello world').toEndWith('world');
  expect('hello world').not.toEndWith('hello');
});

.toInclude(substring)

Note: Currently unimplemented

Use .toInclude when checking if a String includes the given String substring.

test('passes when value includes substring', () => {
  expect('hello world').toInclude('ell');
  expect('hello world').not.toInclude('bob');
});

.toIncludeRepeated(substring, times)

Note: Currently unimplemented

Use .toIncludeRepeated when checking if a String includes the given String substring the correct number of times.

test('passes when value includes substring n times', () => {
  expect('hello hello world').toIncludeRepeated('hello', 2);
  expect('hello hello world').not.toIncludeRepeated('hello', 1);
});

.toIncludeMultiple([substring])

Use .toIncludeMultiple when checking if a String includes all of the given substrings.

test('passes when value includes all substrings', () => {
  expect('hello world').toInclude(['world', 'hello']);
  expect('hello world').not.toInclude(['world', 'hello', 'bob']);
});

.toEqualCaseInsensitive(string)

Use .toEqualCaseInsensitive when checking if a string is equal (===) to another ignoring the casing of both strings.

test('passes when strings are equal ignoring case', () => {
  expect('hello world').toEqualCaseInsensitive('hello world');
  expect('hello WORLD').toEqualCaseInsensitive('HELLO world');
  expect('HELLO WORLD').toEqualCaseInsensitive('hello world');
  expect('hello world').toEqualCaseInsensitive('HELLO WORLD');
  expect('hello world').not.toEqualCaseInsensitive('hello');
});

Contributors

Matt Phillips 📝 💻 📖 💡 🚇 ⚠️	Brandon Newton 💻 📖 ⚠️	Gary Leutheuser 💻	Johan Lindgren 💻 📖 ⚠️	Andrew Hayward 💻 ⚠️	Oliver Schneider 💻 ⚠️	Tyle Whalen 💻 📖
Martius 💻 ⚠️	Eli Collis 💻	Marcin Lichwała 💻 ⚠️	Massimo Prencipe 💻 ⚠️	Gary Meehan 💻 📖 ⚠️	Fredrik Mäkilä 💻 ⚠️	Daniel Reinoso 💻 ⚠️
Chris Hut 💻 ⚠️

LICENSE

MIT