| name | jest-roblox-cli |
| description | Run Jest tests inside Roblox, configure test execution, collect code
coverage, and debug test runner failures for Roblox and roblox-ts
projects. Use when setting up or running tests for a Roblox project,
executing the jest-roblox command, editing jest.config.ts, adding test
coverage, or debugging errors like "no backend available" or "failed to
find Jest instance".
|
jest-roblox CLI
CLI that executes Jest Roblox tests from Node.js. Uploads a Roblox place file,
runs Luau tests inside Roblox, parses JSON results, and maps stack traces back
to source. Two backends: Open Cloud (remote via Roblox API) and Studio
(local via WebSocket plugin).
Do not assume a specific package manager or TypeScript toolchain when giving
advice — jest-roblox is usable by both roblox-ts and Luau-only projects.
Running Tests
| Task | Command |
|---|
| Run all tests | jest-roblox |
| Run specific files | jest-roblox src/player.spec.ts src/combat.spec.ts |
| Filter by test name | jest-roblox -t "should spawn" |
| Filter by file path | jest-roblox --testPathPattern player |
| Verbose output | jest-roblox --verbose |
| Update snapshots | jest-roblox -u |
| AI-friendly output | jest-roblox --formatters agent |
| Limit agent failures | jest-roblox --formatters agent (configure maxFailures in config) |
| Type tests only | jest-roblox --typecheckOnly |
| Enable type tests | jest-roblox --typecheck |
| Custom tsconfig for types | jest-roblox --typecheckTsconfig tsconfig.test.json |
| JSON output to file | jest-roblox --formatters json --outputFile results.json |
Filtering options — three ways to narrow what runs:
- Positional file args — pass specific files directly:
jest-roblox src/combat/damage.spec.ts
--testPathPattern <regex> — filter by file path (only matching tests
execute; the full place is still uploaded)-t <regex> / --testNamePattern — filter by test name within
describe/it blocks
Combine them: jest-roblox --testPathPattern combat -t "should deal damage"
Run jest-roblox --help for the full flag list. CLI flags override config file
values.
References
| Topic | Description | Reference |
|---|
| Backends | Open Cloud vs Studio, auto-detection, env vars, fallback behavior | backends |
| Configuration | jest.config.ts fields, defaults, CLI override behavior | configuration |
| Coverage | Instrumentation pipeline, thresholds, reporters, lute setup | coverage |
| Debugging | Common errors, hints, diagnostic flags | debugging |
See Also
For writing tests (describe/it/expect API, matchers, mocking, Luau deviations
from JS Jest), refer to the
Jest Roblox documentation.
