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

Jest Matchers

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

Jest Matchers is a comprehensive matcher library for the Jest testing framework providing assertion utilities for test expectations. It offers a complete set of assertion methods including equality matchers, comparison operators, collection matchers, spy/mock verifications, and asynchronous testing support with detailed error messages and visual diffs.

Package Information

Package Name: jest-matchers
Package Type: npm
Language: JavaScript (with Flow types)
Installation: npm install jest-matchers

Core Imports

const expect = require('jest-matchers');

ES modules:

import expect from 'jest-matchers';

Basic Usage

const expect = require('jest-matchers');

// Basic equality assertions
expect(2 + 2).toBe(4);
expect({name: 'John'}).toEqual({name: 'John'});

// Truthiness checks
expect(true).toBeTruthy();
expect(null).toBeFalsy();

// Collection assertions
expect(['apple', 'banana']).toContain('apple');
expect([1, 2, 3]).toHaveLength(3);

// Numeric comparisons
expect(10).toBeGreaterThan(5);
expect(3.14).toBeCloseTo(3.1, 1);

// String matching
expect('Hello World').toMatch(/World/);

// Spy/mock verification
const mockFn = jest.fn();
mockFn('arg1', 'arg2');
expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2');

// Exception testing
expect(() => {
  throw new Error('Something went wrong');
}).toThrow('Something went wrong');

Architecture

Jest Matchers is built around several core components:

Expect Function: Main entry point that creates expectation objects with all available matchers
Matcher System: Extensible matcher framework supporting custom matchers via expect.extend()
Negation Support: All matchers support .not for inverted assertions
Promise Support: All matchers support .resolves and .rejects for asynchronous testing
Global State Management: Centralized state for assertion counting and configuration
Error Handling: Rich error messages with visual diffs using jest-diff, jest-matcher-utils

Capabilities

Core Matchers

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

// Main expect function
function expect(actual: any): ExpectationObject;

// Core equality matchers
ExpectationObject.toBe(expected: any): void;
ExpectationObject.toEqual(expected: any): void;
ExpectationObject.toMatchObject(expected: Object): void;

// Truthiness matchers
ExpectationObject.toBeTruthy(): void;
ExpectationObject.toBeFalsy(): void;
ExpectationObject.toBeDefined(): void;
ExpectationObject.toBeUndefined(): void;
ExpectationObject.toBeNull(): void;

Core Matchers

Numeric and Comparison Matchers

Specialized matchers for numeric comparisons and floating-point precision testing.

ExpectationObject.toBeGreaterThan(expected: number): void;
ExpectationObject.toBeGreaterThanOrEqual(expected: number): void;
ExpectationObject.toBeLessThan(expected: number): void;
ExpectationObject.toBeLessThanOrEqual(expected: number): void;
ExpectationObject.toBeCloseTo(expected: number, precision?: number): void;
ExpectationObject.toBeNaN(): void;

Numeric Matchers

Collection and String Matchers

Matchers for arrays, objects, strings, and other iterable collections.

ExpectationObject.toContain(item: any): void;
ExpectationObject.toContainEqual(item: any): void;
ExpectationObject.toHaveLength(length: number): void;
ExpectationObject.toHaveProperty(path: string, value?: any): void;
ExpectationObject.toMatch(pattern: string | RegExp): void;
ExpectationObject.toBeInstanceOf(constructor: Function): void;

Collection and String Matchers

Spy and Mock Matchers

Verification matchers for Jest mock functions and spies, essential for testing function calls and interactions.

ExpectationObject.toBeCalled(): void;
ExpectationObject.toHaveBeenCalled(): void;
ExpectationObject.toBeCalledWith(...args: any[]): void;
ExpectationObject.toHaveBeenCalledWith(...args: any[]): void;
ExpectationObject.toHaveBeenCalledTimes(number: number): void;
ExpectationObject.lastCalledWith(...args: any[]): void;
ExpectationObject.toHaveBeenLastCalledWith(...args: any[]): void;

Spy and Mock Matchers

Exception Matchers

Matchers for testing error conditions and exception handling.

ExpectationObject.toThrow(expected?: string | Error | RegExp): void;
ExpectationObject.toThrowError(expected?: string | Error | RegExp): void;

Exception Matchers

Asymmetric Matchers

Special matchers for flexible pattern matching and partial object comparison.

expect.anything(): Anything;
expect.any(constructor: Function): Any;
expect.objectContaining(object: Object): ObjectContaining;
expect.arrayContaining(array: Array): ArrayContaining;
expect.stringContaining(string: string): StringContaining;
expect.stringMatching(pattern: string | RegExp): StringMatching;

Asymmetric Matchers

Configuration and Extension

Methods for extending Jest Matchers with custom matchers and configuring test behavior.

expect.extend(matchers: MatchersObject): void;
expect.assertions(expected: number): void;
expect.hasAssertions(): void;
expect.setState(state: Object): void;
expect.getState(): Object;
expect.addSnapshotSerializer(): void;

Configuration and Extension

Types

interface ExpectationObject {
  // All matchers are available on the expectation object
  // Plus special properties for negation and promise handling
  not: ExpectationObject;
  resolves: ExpectationObject;
  rejects: ExpectationObject;
}

interface MatchersObject {
  [matcherName: string]: RawMatcherFn;
}

interface ExpectationResult {
  pass: boolean;
  message?: string | (() => string);
}

class JestAssertionError extends Error {
  matcherResult: any;
}