@rbxts/jest-utils

A collection of utilities for testing roblox-ts code with Jest.

Installation

npm i @rbxts/jest-utils

Peer dependency: @rbxts/jest-globals

API

afterThis

Queues a cleanup callback that runs after the current test. Callbacks run in reverse order (LIFO), so factory functions can own both setup and teardown without let variables or beforeEach/afterEach hooks.

it("connects to an event", () => {
    expect.assertions(1);

    const connection = signal.Connect(() => {
        /* ... */
    });
    afterThis(() => connection.Disconnect());

    signal.Fire();

    expect(received).toBe(true);
});

fromPartial

Pass a deep partial to a slot expecting a full type. Useful when you only care about a subset of properties but the function signature demands the complete type.

it("should get the user", () => {
    getUser(
        fromPartial({
            body: {
                id: "123",
            },
        }),
    );
});

fromAny

Pass anything to a typed slot while retaining autocomplete for the original type. Unlike fromPartial, this won't error if the value doesn't match the expected type at all — handy for testing error paths with intentionally wrong data.

it("should handle bad input", () => {
    getUser(
        fromAny({
            body: {
                id: 124123,
            },
        }),
    );
});

fromExact

Forces you to pass the exact type the slot requires. A convenience wrapper for swapping between fromPartial/fromAny and a strict check — the compiler will error if any required properties are missing.

it("should reject incomplete data", () => {
    // Will fail — not all properties of Request are provided.
    getUser(
        fromExact({
            body: {
                id: "123",
            },
        }),
    );
});

expectTypeOf / assertType

Compile-time type assertions — runtime no-ops. expectTypeOf is powered by expect-type and works like Jest's expect but for types. assertType is a simpler alternative when you just need to check assignability.

expectTypeOf<string>().toBeString();
expectTypeOf<string>().not.toBeNumber();
expectTypeOf<{ a: 1 }>().toEqualTypeOf<{ a: number }>();

const value = getValue();
assertType<string>(value);

See the full expect-type docs for all available matchers.

Note: expect-type is a standard TypeScript package, not an rbxts module — rbxtsc can't compile it. Type-test files must be checked by a separate tsconfig that is not consumed by rbxtsc. For example:

// tsconfig.typetest.json
{
    "extends": "./tsconfig.json",
    "compilerOptions": {
        "rootDir": "src/type-testing",
        "emitDeclarationOnly": true,
    },
    "include": ["src/type-testing"],
}

Run tsc -p tsconfig.typetest.json to verify your type tests.

Why fromPartial / fromAny / fromExact?

In roblox-ts tests you often need to pass mock objects to functions that expect full types. The typical escape hatch is as casts, but those are noisy, hide intent, and lose autocomplete. These utilities make the cast explicit and semantic — your test reads as "I'm deliberately passing a partial" rather than "I'm forcing the compiler to shut up."

Inspired by @total-typescript/shoehorn.

License

MIT