Class: Matcher¶

Provides assertion methods for testing values.

Created by Expect.expect(value) and chains to matchers like toBe(), toContain(), etc.

Since¶

0.22.0

Example¶

JavaScript

const expect = new gaslamp.JestLite.Expect().expect;
expect(5).toBeGreaterThan(3);
expect([1, 2, 3]).toContain(2);
expect(() => { throw new Error("fail"); }).toThrow();

Constructors¶

Constructor¶

new Matcher(value, isNot?): Matcher

Creates a matcher instance for the given value.

Parameters¶

value¶

unknown

Value to test.

isNot?¶

boolean = false

Whether negated (.not). Default is false.

Returns¶

Matcher

Accessors¶

not¶

Get Signature¶

get not(): Matcher

Invert the next assertion.

Example¶

JavaScript

expect(true).not.toBe(false);
expect(1).not.toBe(2);
expect([1, 2]).not.toContain(3);

Returns¶

Matcher

Negated matcher.

Methods¶

toBe()¶

toBe(expected): void

Assert strict equality (===).

Parameters¶

expected¶

unknown

Expected value.

Returns¶

void

Throws¶

If assertion fails.

Example¶

JavaScript

expect(1 + 2).toBe(3);
expect("hello").toBe("hello");

toEqual()¶

toEqual(expected): void

Assert deep equality using JSON.stringify comparison.

Parameters¶

expected¶

unknown

Expected value to match.

Returns¶

void

Throws¶

If assertion fails.

Remarks¶

Compares JSON representations. Circular references and special types (Date, Map, Set) may not compare as expected.

Example¶

JavaScript

expect({ a: 1 }).toEqual({ a: 1 });
expect([1, 2, 3]).toEqual([1, 2, 3]);

toBeTruthy()¶

toBeTruthy(): void

Assert value is truthy.

Returns¶

void

Throws¶

If value is falsy.

Example¶

JavaScript

expect("hello").toBeTruthy();
expect(1).toBeTruthy();
expect(true).toBeTruthy();

toBeFalsy()¶

toBeFalsy(): void

Assert value is falsy.

Returns¶

void

Throws¶

If value is truthy.

Example¶

JavaScript

expect(0).toBeFalsy();
expect("").toBeFalsy();
expect(false).toBeFalsy();
expect(null).toBeFalsy();
expect(undefined).toBeFalsy();

toBeNull()¶

toBeNull(): void

Assert value is exactly null.

Returns¶

void

Throws¶

If value is not null.

Example¶

JavaScript

expect(null).toBeNull();

toBeUndefined()¶

toBeUndefined(): void

Assert value is exactly undefined.

Returns¶

void

Throws¶

If value is not undefined.

Example¶

JavaScript

expect(undefined).toBeUndefined();

toBeInstanceOf()¶

toBeInstanceOf(type): void

Assert value is an instance of a constructor.

Parameters¶

type¶

(...args) => unknown

Constructor function to check.

Returns¶

void

Throws¶

If assertion fails or type is not a function.

Remarks¶

Uses constructor name comparison instead of instanceof for robustness across GAS script boundaries, where instanceof can fail due to context switching.

Example¶

JavaScript

expect(new Date()).toBeInstanceOf(Date);
expect([1, 2]).toBeInstanceOf(Array);
expect(new MyClass()).toBeInstanceOf(MyClass);

toContain()¶

toContain(expected): void

Assert value contains the expected value.

Supports strings and arrays.

Parameters¶

expected¶

unknown

Value to search for.

Returns¶

void

Throws¶

If value is not contained or type is unsupported.

Example¶

JavaScript

expect("hello world").toContain("world");
expect([1, 2, 3]).toContain(2);

toThrow()¶

toThrow(expectedErrorType?): void

Assert function throws an error.

Optionally match a specific error type.

Parameters¶

expectedErrorType?¶

ErrorConstructor | ((...args) => Error)

Optional error constructor to match.

Returns¶

void

Throws¶

If function doesn't throw or throws unexpected error type.

Remarks¶

Error type checking uses constructor name comparison instead of instanceof for compatibility with GAS script boundaries, where instanceof can fail due to context switching.

Example¶

JavaScript

expect(() => { throw new Error("fail"); }).toThrow();
expect(() => { throw new TypeError("bad"); }).toThrow(TypeError);
expect(() => { throw new SyntaxError(); }).toThrow(SyntaxError);

toBeGreaterThan()¶

toBeGreaterThan(expected): void

Assert number is greater than expected value.

Parameters¶

expected¶

number

Number to compare against.

Returns¶

void

Throws¶

If assertion fails.

Example¶

JavaScript

expect(5).toBeGreaterThan(3);
expect(10).toBeGreaterThan(5);

toBeLessThan()¶

toBeLessThan(expected): void

Assert number is less than expected value.

Parameters¶

expected¶

number

Number to compare against.

Returns¶

void

Throws¶

If assertion fails.

Example¶

JavaScript

expect(2).toBeLessThan(10);
expect(1).toBeLessThan(5);

toBeCloseTo()¶

toBeCloseTo(expected, precision?): void

Assert number is approximately equal to expected value.

Parameters¶

expected¶

number

Expected number.

precision?¶

number = 2

Decimal places for comparison. Default is 2.

Returns¶

void

Throws¶

If values differ beyond precision.

Example¶

JavaScript

expect(0.1 + 0.2).toBeCloseTo(0.3);
expect(3.1416).toBeCloseTo(3.14, 2);
expect(1.234).toBeCloseTo(1.23, 2);