jest-extended
Advanced tools
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.
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'));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.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 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.
ππͺ
Additional Jest matchers
Jest is an amazing test runner 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.
jest-extended aims to add additional matchers to Jest's default ones making it easy to test everything π
If you've come here to help contribute - Thanks! Take a look at the contributing docs as a way of getting started.
With npm:
npm install --save-dev jest-extended
With yarn:
yarn add -D jest-extended
Add jest-extended to your Jest setupTestFrameworkScriptFile configuration. See for help
"jest": {
"setupTestFrameworkScriptFile": "jest-extended"
}
If you are already using another test framework, like jest-chain, then you should create a test setup file and require each of the frameworks you are using.
For example:
// ./testSetup.js
require('jest-extended');
require('any other test framework libraries you are using');
Then in your Jest config:
"jest": {
"setupTestFrameworkScriptFile": "./testSetup.js"
}
Note: Currently unimplemented
Passing assertion.
expect().pass('should pass');
Note: Currently unimplemented
Failing assertion.
expect().fail('test should fail');
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();
});
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]);
});
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();
});
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);
});
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();
});
Use .toBeArrayOfSize when checking if a value is an Array of size x.
test('passes when value is an array', () => {
expect([]).toBeArrayOfSize(0);
expect([1]).toBeArrayOfSize(1);
expect(true).not.toBeArrayOfSize(1);
});
Use .toIncludeAllMembers 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]).toIncludeAllMembers([2, 1, 3]);
expect([1, 2, 2]).toIncludeAllMembers([2, 1]);
});
Use .toIncludeAnyMembers when checking if an Array contains any of the members of a given set.
test('passes when given array values match any of the members in the set', () => {
expect([1, 2, 3]).toIncludeAnyMembers([2, 1, 3]);
expect([1, 2, 2]).toIncludeAnyMembers([2]);
expect([1, 2, 2]).not.toIncludeAnyMembers([3]);
});
Use .toSatisfyAll when you want to use a custom matcher by supplying a predicate function that returns a Boolean for all values in an array.
test('passes when all values in array pass given predicate', () => {
const isOdd = el => el % 2 === 1;
expect([1,3,5,7]).toSatisfyAll(isOdd);
expect([1,3,4,5,7]).not.toSatisfyAll(isOdd);
});
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();
});
Use .toBeTrue when checking a value is equal (===) to true.
test('is jest cool', () => {
expect(isJestCool()).toBeTrue();
expect(false).not.toBeTrue();
});
Use .toBeFalse when checking a value is equal (===) to false.
test('returns false', () => {
expect(areWeThereYet()).toBeFalse();
expect(true).not.toBeFalse();
});
Proposal in #117 (under development)
Use .toBeDate when checking if a value is a Date.
test('passes when value is a date', () => {
expect(new Date()).toBeDate();
expect('01/01/2018').not.toBeDate();
expect(new Date('01/01/2018').toBeDate();
expect(undefined).not.toBeDate();
});
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();
});
Use .toHaveBeenCalledBefore when checking if a Mock was called before another Mock.
Note: Required Jest version >22
Note: Your mock functions will have to be asynchronous to cause the timestamps inside of Jest to occur in a different JS event loop, otherwise the mock timestamps will all be the same
const timeout = time => () => new Promise(res => setTimeout(() => res()), time);
it('calls mock1 before mock2', async () => {
const mock1 = jest.fn(timeout(1));
const mock2 = jest.fn(timeout(1));
await mock1();
await mock2();
await mock1();
expect(mock1).toHaveBeenCalledBefore(mock2);
});
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();
});
Use .toBeNaN when checking a value is NaN.
test('passes when value is NaN', () => {
expect(NaN).toBeNaN();
expect(1).not.toBeNaN();
});
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();
});
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();
});
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();
});
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();
});
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();
});
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);
});
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();
});
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');
});
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']);
});
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']);
});
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']);
});
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');
});
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']);
});
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']);
});
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']);
});
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']);
});
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']]);
});
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']]);
});
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']]);
});
Use .toBeExtensible when checking if an object is extensible.
test('passes when value is extensible', () => {
expect({a: 1}).toBeExtensible();
expect(1).not.toBeExtensible();
});
Use .toBeFrozen when checking if an object is frozen.
test('passes when value is frozen', () => {
expect(Object.frozen({})).toBeFrozen();
expect({}).not.toBeFrozen();
expect(1).not.toBeFrozen();
});
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();
});
No APIs proposed yet
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();
});
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');
});
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');
});
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');
});
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');
});
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);
});
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']);
});
FAQs
Additional Jest matchers
The npm package jest-extended receives a total of 753,208 weekly downloads. As such, jest-extended popularity was classified as popular.
We found that jest-extended demonstrated a not healthy version release cadence and project activity because the last version was released a year ago.Β It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
