tessl/npm-jest-matchers

A comprehensive matcher library for Jest testing framework providing assertion utilities for test expectations

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Core Matchers

Name: tessl/npm-jest-matchers
Author: tessl

Essential assertion methods for equality, truthiness, and basic comparisons. These form the foundation of most test assertions in Jest.

Capabilities

Equality Matchers

toBe

Performs exact equality comparison using === (referential equality).

/**
 * Tests exact equality using === comparison
 * @param expected - Expected value for strict equality
 */
ExpectationObject.toBe(expected: any): void;

Usage Examples:

expect(1).toBe(1);
expect('hello').toBe('hello');
expect(true).toBe(true);

// Objects and arrays check reference equality
const obj = {name: 'John'};
expect(obj).toBe(obj);  // passes
expect({name: 'John'}).toBe({name: 'John'});  // fails - different references

toEqual

Performs deep equality comparison with recursive checking of object properties and array elements.

/**
 * Tests deep equality using custom equality logic
 * @param expected - Expected value for deep equality comparison
 */
ExpectationObject.toEqual(expected: any): void;

Usage Examples:

expect({name: 'John', age: 30}).toEqual({name: 'John', age: 30});
expect([1, 2, 3]).toEqual([1, 2, 3]);
expect(new Date('2023-01-01')).toEqual(new Date('2023-01-01'));

// Works with nested objects
expect({
  user: {name: 'John', preferences: {theme: 'dark'}}
}).toEqual({
  user: {name: 'John', preferences: {theme: 'dark'}}
});

toMatchObject

Checks if the received object contains the expected properties (subset matching).

/**
 * Matches if received object contains expected properties
 * @param expected - Object with properties that should be present
 */
ExpectationObject.toMatchObject(expected: Object): void;

Usage Examples:

const user = {
  id: 1,
  name: 'John',
  email: 'john@example.com',
  preferences: {theme: 'dark'}
};

expect(user).toMatchObject({name: 'John'});  // passes
expect(user).toMatchObject({name: 'John', id: 1});  // passes
expect(user).toMatchObject({preferences: {theme: 'dark'}});  // passes

// Received object can have additional properties
expect(user).toMatchObject({name: 'John'});  // passes even though user has more properties

Truthiness Matchers

toBeTruthy

Checks if a value is truthy (not false, 0, "", null, undefined, or NaN).

/**
 * Checks if value is truthy in JavaScript context
 */
ExpectationObject.toBeTruthy(): void;

Usage Examples:

expect(true).toBeTruthy();
expect(1).toBeTruthy();
expect('hello').toBeTruthy();
expect([]).toBeTruthy();  // empty array is truthy
expect({}).toBeTruthy();  // empty object is truthy

toBeFalsy

Checks if a value is falsy (false, 0, "", null, undefined, or NaN).

/**
 * Checks if value is falsy in JavaScript context
 */
ExpectationObject.toBeFalsy(): void;

Usage Examples:

expect(false).toBeFalsy();
expect(0).toBeFalsy();
expect('').toBeFalsy();
expect(null).toBeFalsy();
expect(undefined).toBeFalsy();
expect(NaN).toBeFalsy();

toBeDefined

Checks that a value is not undefined.

/**
 * Checks that value is not undefined
 */
ExpectationObject.toBeDefined(): void;

Usage Examples:

expect('hello').toBeDefined();
expect(0).toBeDefined();
expect(null).toBeDefined();  // null is defined, just not undefined
expect(false).toBeDefined();

let x;
expect(x).not.toBeDefined();  // x is undefined

toBeUndefined

Checks that a value is undefined.

/**
 * Checks that value is undefined
 */
ExpectationObject.toBeUndefined(): void;

Usage Examples:

let x;
expect(x).toBeUndefined();

const obj = {name: 'John'};
expect(obj.age).toBeUndefined();

expect(undefined).toBeUndefined();

toBeNull

Checks that a value is null.

/**
 * Checks that value is null
 */
ExpectationObject.toBeNull(): void;

Usage Examples:

expect(null).toBeNull();

function findUser(id) {
  return id > 0 ? {id, name: 'User'} : null;
}

expect(findUser(-1)).toBeNull();
expect(findUser(1)).not.toBeNull();

Negation Support

All core matchers support negation using .not:

expect(1).not.toBe(2);
expect({a: 1}).not.toEqual({a: 2});
expect('hello').not.toBeFalsy();
expect(null).not.toBeDefined();
expect('defined').not.toBeUndefined();
expect('not null').not.toBeNull();

Promise Support

All core matchers work with promises using .resolves and .rejects:

// Testing resolved values
await expect(Promise.resolve(42)).resolves.toBe(42);
await expect(Promise.resolve({name: 'John'})).resolves.toEqual({name: 'John'});
await expect(Promise.resolve('hello')).resolves.toBeTruthy();

// Testing rejected values
await expect(Promise.reject(new Error('fail'))).rejects.toBeDefined();