christopher-buss Based on Jest Roblox v3.x, generated 2026-02-07.
Jest Roblox is a Luau port of Jest for the Roblox platform. It closely follows the upstream Jest API but has critical deviations due to Luau language constraints.
Critical deviations from JS Jest:
.neverinstead of.not(reserved keyword)jest.fn()returns two values: mock object + forwarding function0,"",{}are truthy in Luau (onlyfalseandnilare falsy)- All globals (
describe,expect,jest, etc.) must be explicitly imported .eachuses table syntax, not tagged template literals- Custom matchers take
selfas first parameter
Read core-deviations first when working with this codebase.
Core References
| Topic | Description | Reference |
|---|---|---|
| Deviations | All Luau/Roblox differences from JS Jest | core-deviations |
| Test Structure | describe, test/it, hooks, .each, .only/.skip | core-test-structure |
| Matchers | toBe, toEqual, toContain, toThrow, mock matchers | core-matchers |
| Asymmetric Matchers | expect.anything/any/nothing/callable, .resolves/.rejects | core-asymmetric-matchers |
| Mocking | jest.fn(), spyOn, mock.calls, return values | core-mocking |
| Configuration | jest.config.lua, runCLI, reporters, options | core-configuration |
Features
Testing Patterns
| Topic | Description | Reference |
|---|---|---|
| Async Testing | Promises, done callbacks, .resolves/.rejects | feature-async-testing |
| Custom Matchers | expect.extend(), self parameter, isNever | feature-custom-matchers |
| Test Filtering | testMatch, testPathPattern, testNamePattern | feature-test-filtering |
Mocking
| Topic | Description | Reference |
|---|---|---|
| Timer Mocks | useFakeTimers, Roblox timers, engineFrameTime | feature-timer-mocks |
| Global Mocks | jest.globalEnv, spyOn globals, library mocks | feature-global-mocks |
| Module Mocking | jest.mock(), isolateModules, resetModules | feature-module-mocking |
Advanced
| Topic | Description | Reference |
|---|---|---|
| Benchmarking | benchmark(), Reporter, Profiler, CustomReporters | advanced-benchmarking |