Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Octopodo/kt-testing-suite-core/llms.txt

Use this file to discover all available pages before exploring further.

Type and existence matchers let you assert what kind of value you are dealing with before making deeper assertions. They are especially important in ExtendScript environments where Adobe host APIs can return null, undefined, or custom object types in ways that differ from standard JavaScript. All of the matchers documented here return this, so they are fully chainable.

​
Existence matchers

​
toBeDefined()

Asserts that the actual value is not undefined. Any other value — including null, 0, false, or an empty string — is considered defined. 
// ✅ Passes
expect('test').toBeDefined();
expect(0).toBeDefined();
expect(null).toBeDefined();
expect(false).toBeDefined();

// ❌ Throws
expect(() => expect(undefined).toBeDefined()).toThrow();
Signature: 
toBeDefined(): this

​
toBeUndefined()

Asserts that the actual value is strictly undefined. 
// ✅ Passes
let value;
expect(value).toBeUndefined();

// ❌ Throws — null is not undefined
expect(() => expect(null).toBeUndefined()).toThrow();
Signature: 
toBeUndefined(): this

​
toBeNull()

Asserts that the actual value is strictly null. 
// ✅ Passes
expect(null).toBeNull();

// ❌ Throws — 0 and undefined are not null
expect(() => expect(0).toBeNull()).toThrow();
expect(() => expect(undefined).toBeNull()).toThrow();
Signature: 
toBeNull(): this

​
Numeric type matchers

​
toBeNumber()

Asserts that the actual value is a number and is not NaN. This intentionally excludes NaN because NaN is not a valid numeric value for most arithmetic purposes. 
// ✅ Passes
expect(42).toBeNumber();
expect(0).toBeNumber();
expect(-5.5).toBeNumber();

// ❌ Throws — NaN is excluded
expect(() => expect(NaN).toBeNumber()).toThrow();

// ❌ Throws — string '42' is not a number type
expect(() => expect('42').toBeNumber()).toThrow();
expect(() => expect(null).toBeNumber()).toThrow();
NaN has the JavaScript type "number" but toBeNumber() explicitly rejects it. Use toBeNaN() to assert that a value is NaN.
Signature: 
toBeNumber(): this

​
toBeNaN()

Asserts that the actual value is NaN. This is useful when testing the output of operations that produce NaN on invalid input, such as parseInt on a non-numeric string. 
// ✅ Passes
expect(NaN).toBeNaN();
expect(parseInt('invalid')).toBeNaN();

// ❌ Throws — 42 is a valid number, not NaN
expect(() => expect(42).toBeNaN()).toThrow();
Signature: 
toBeNaN(): this

​
String, boolean, and function matchers

​
toBeString()

Asserts that the actual value has the JavaScript type "string". Both empty and non-empty strings pass. 
// ✅ Passes
expect('hello').toBeString();
expect('').toBeString();

// ❌ Throws — numbers are not strings
expect(() => expect(123).toBeString()).toThrow();
Signature: 
toBeString(): this

​
toBeBoolean()

Asserts that the actual value has the JavaScript type "boolean". Only the literals true and false pass; truthy or falsy values of other types do not. 
// ✅ Passes
expect(true).toBeBoolean();
expect(false).toBeBoolean();

// ❌ Throws — 1 and 0 are numbers, not booleans
expect(() => expect(1).toBeBoolean()).toThrow();
expect(() => expect(0).toBeBoolean()).toThrow();
Signature: 
toBeBoolean(): this

​
toBeFunction()

Asserts that the actual value has the JavaScript type "function". Both function declarations and arrow functions pass. 
// ✅ Passes
expect(function () {}).toBeFunction();
expect(() => {}).toBeFunction();

// ❌ Throws — objects are not functions
expect(() => expect({}).toBeFunction()).toThrow();
Signature: 
toBeFunction(): this

​
toBeArray()

Asserts that the actual value is an Array by checking value.constructor === Array. This approach works correctly in ExtendScript, where instanceof behaviour can differ across execution contexts. 
// ✅ Passes
expect([]).toBeArray();
expect([1, 2, 3]).toBeArray();

// ❌ Throws — plain objects are not arrays
expect(() => expect({}).toBeArray()).toThrow();
expect(() => expect('abc').toBeArray()).toThrow();
Signature: 
toBeArray(): this

​
Truthiness matchers

Truthiness matchers check whether a value is truthy or falsy according to JavaScript’s standard coercion rules, or whether a value is strictly the boolean literal true or false.

​
toBeTrue()

Asserts that the actual value is strictly true — not merely truthy. The check uses ===, so 1, "yes", and non-empty arrays all fail. 
// ✅ Passes
expect(true).toBeTrue();
expect(1 === 1).toBeTrue();

// ❌ Throws — 1 is truthy but not strictly true
expect(() => expect(1).toBeTrue()).toThrow();
expect(() => expect('yes').toBeTrue()).toThrow();
Signature: 
toBeTrue(): this

​
toBeFalse()

Asserts that the actual value is strictly false — not merely falsy. The check uses ===, so 0, "", null, and undefined all fail. 
// ✅ Passes
expect(false).toBeFalse();
expect(1 !== 1).toBeFalse();

// ❌ Throws — 0 is falsy but not strictly false
expect(() => expect(0).toBeFalse()).toThrow();
expect(() => expect(null).toBeFalse()).toThrow();
Signature: 
toBeFalse(): this

​
toBeTruthy()

Asserts that the actual value is truthy — any value for which !!value === true. This includes non-zero numbers, non-empty strings, objects, arrays (even empty ones), and true itself. 
// ✅ Passes
expect(true).toBeTruthy();
expect(1).toBeTruthy();
expect('test').toBeTruthy();
expect({}).toBeTruthy();
expect([1]).toBeTruthy();
expect([0]).toBeTruthy(); // Array is truthy despite containing a falsy value

// ❌ Throws — falsy values
expect(() => expect(0).toBeTruthy()).toThrow();
expect(() => expect('').toBeTruthy()).toThrow();
Signature: 
toBeTruthy(): this

​
toBeFalsy()

Asserts that the actual value is falsy — any value for which !value === true. The falsy values in JavaScript are false, 0, "", null, undefined, and NaN. 
// ✅ Passes
expect(false).toBeFalsy();
expect(0).toBeFalsy();
expect('').toBeFalsy();
expect(null).toBeFalsy();
expect(undefined).toBeFalsy();

// ❌ Throws — truthy values
expect(() => expect('non-empty').toBeFalsy()).toThrow();
expect(() => expect(1).toBeFalsy()).toThrow();
Signature: 
toBeFalsy(): this

​
toBeInstanceOf(constructor)

Asserts that the actual value is an instance of the given constructor. The check first compares value.constructor === expected, then falls back to value instanceof expected. This two-step approach ensures correct behaviour with both standard JavaScript classes and Adobe host application classes (such as CompItem, Layer, File, etc.) where instanceof may not behave as expected across execution contexts. 
class TestClass {}
const instance = new TestClass();

// ✅ Passes
expect(instance).toBeInstanceOf(TestClass);

// ✅ Also works with Adobe built-in classes inside a host application
const comp = app.project.items.addComp('Test', 1920, 1080, 1, 10, 30);
expect(comp).toBeInstanceOf(CompItem);
comp.remove();

// ❌ Throws — plain object is not a TestClass instance
expect(() => expect({}).toBeInstanceOf(TestClass)).toThrow();

// ❌ Throws — null is not an instance of anything
expect(() => expect(null).toBeInstanceOf(TestClass)).toThrow();
null and undefined are handled explicitly: passing either as the actual value always fails with a descriptive message naming the expected constructor, even before instanceof is evaluated.
When testing Adobe host objects such as CompItem, AVLayer, ShapeLayer, or File, prefer toBeInstanceOf over toBeFile/toBeFolder for custom Adobe types. The IO matchers (toBeFile, toBeFolder) specifically target ExtendScript’s built-in File and Folder classes.
Signature: 
toBeInstanceOf(expected: Function): this
ParameterTypeDescription
expectedFunctionThe constructor function to check against.

​
toThrow()

Asserts that the actual value is a function and that it throws an error when called. The matcher calls the function with no arguments and catches any exception. If the function does not throw, or if the actual value is not a function at all, the assertion fails. 
// ✅ Passes — function throws
expect(() => {
    throw new Error('Test error');
}).toThrow();

// ✅ Passes — function with a failing inner assertion also throws
expect(() => {
    expect(5).toBeString();
}).toThrow();

// ❌ Throws — function does not throw
expect(() => expect(() => 42).toThrow()).toThrow();
toThrow only works on functions. Passing a non-function value (such as 42, null, or undefined) always fails the assertion — the matcher cannot execute a non-function, so it cannot determine whether it would throw.
// ❌ All fail — non-function values cannot be tested with toThrow
expect(() => expect(42).toThrow()).toThrow();
expect(() => expect(null).toThrow()).toThrow();
expect(() => expect(undefined).toThrow()).toThrow();
Use not().toThrow() to assert that a function completes without throwing. See the Negation page for detailed examples. Signature: 
toThrow(): this

​
Full examples from the test suite

it('toBeDefined passes with defined values', () => {
    expect('test').toBeDefined();
    expect(0).toBeDefined();
});

it('toBeUndefined passes with undefined', () => {
    let value;
    expect(value).toBeUndefined();
});

it('toBeNull passes with null', () => {
    expect(null).toBeNull();
});

Build docs developers (and LLMs) love

Get started for freeTalk to us