or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

asymmetric-matchers.mdcollection-string-matchers.mdconfiguration-extension.mdcore-matchers.mdexception-matchers.mdindex.mdnumeric-matchers.mdspy-mock-matchers.md
tile.json

tessl/npm-jest-matchers

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/jest-matchers@20.0.x

To install, run

npx @tessl/cli install tessl/npm-jest-matchers@20.0.0

index.mddocs/

Jest Matchers

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