christopher-buss 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.