Getting Started

xJet-Expect is the assertion library for the xJet test runner. It provides a fluent, Jest-compatible matcher API - xExpect(value).toBe(...) - with deep equality, asymmetric matchers, mock introspection, and colorized failure diffs, all written in TypeScript.

Installation

npm

npm install --save-dev @remotex-labs/xjet-expect

pnpm

pnpm add -D @remotex-labs/xjet-expect

yarn

yarn add --dev @remotex-labs/xjet-expect

xJet-Expect requires Node.js 20 or later.

Your first assertion

test('two plus two', () => {
    xExpect(2 + 2).toBe(4);
});

When this runs under the xJet test runner, the assertion passes silently. If 2 + 2 were anything but 4, xJet would print a diff of the expected and received values and fail the test.

Globals provided by the runner

Inside the xJet runner, test, describe, expect, and the xJet mock namespace are available globally - no imports needed. The global expect is xExpect, so the two are interchangeable. Import xExpect explicitly only when you use it outside a test file:

import { xExpect } from '@remotex-labs/xjet-expect';

The assertion model

Every assertion follows the same shape: wrap the value under test in xExpect(...), then chain a matcher that states what you expect.

xExpect(received).toEqual(expected);
//      ^actual    ^matcher ^expected

A matcher is the check itself (toBe, toEqual, toContain, ...). A modifier sits in front of a matcher to adapt it - .not inverts it, and .resolves / .rejects unwrap a Promise first.

xExpect(value).not.toBeNull();
await xExpect(promise).resolves.toBe('ok');

Matchers by category

Matchers are grouped by the kind of value they operate on. Each category has its own page with a quick-reference table and worked examples.

Category	Covers
Equality	Identity, deep equality, presence, and truthiness
Numbers	Comparisons and floating-point tolerance
Strings	Length, substrings, and patterns
Objects & Arrays	Properties, type, and partial structure
Functions	Asserting that a call throws
Mocks & Spies	Calls, arguments, and return values

Two features cut across every category:

• Modifiers - .not, .resolves, and .rejects.
• Asymmetric matchers - match a shape (xExpect.any(), xExpect.objectContaining()) instead of an exact value.

Reading a failure

When an assertion fails, xJet prints a diff. Lines marked - are what was expected; lines marked + are what was received.

Expected: 42
Received: 41

  Object {
-   "count": 2,
+   "count": 3,
    "name": "test",
  }

Next steps

• Learn the modifiers that adapt any matcher.
• Match flexible shapes with asymmetric matchers.
• Browse the matcher reference, starting with Equality.