@isentinel/jest-roblox 0.0.8 → 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christopher Buss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,23 +1,27 @@
 # jest-roblox-cli
 
+[![npm version](https://img.shields.io/npm/v/@isentinel/jest-roblox)](https://www.npmx.dev/package/@isentinel/jest-roblox)
+[![CI](https://github.com/christopher-buss/jest-roblox-cli/actions/workflows/ci.yaml/badge.svg)](https://github.com/christopher-buss/jest-roblox-cli/actions/workflows/ci.yaml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/christopher-buss/jest-roblox-cli/blob/main/LICENSE)
+
+
 Run your TypeScript and Luau tests inside Roblox, then see the results in your
 terminal.
 
-jest-roblox-cli takes your test files, builds a Roblox place, runs the tests
-in Roblox, and brings the results back to you. It works with both roblox-ts
-(TypeScript) and pure Luau projects. For TypeScript projects, it maps errors
-back to your original source.
+jest-roblox-cli builds a Roblox place from your test files, runs it in Roblox,
+and reports results in your terminal. It works with roblox-ts and pure Luau
+projects. For TypeScript, it maps Luau errors back to your `.ts` source.
 
-## Why use this?
+## Why?
 
-Roblox code needs Roblox to run. You can't test it with normal tools because
-the Roblox API only exists inside the engine. This tool runs your tests in a
-real Roblox session, then reports results in your terminal.
+Roblox code can only run inside the Roblox engine. Standard test runners
+can't access the Roblox API. This tool bridges that gap by running tests in a
+real Roblox session and piping results back to your terminal.
 
-- Works with roblox-ts and pure Luau projects
-- For TypeScript projects, maps Luau errors back to your `.ts` files
-- Collects code coverage so you know which lines your tests touch
-- Supports two backends: Roblox Open Cloud (remote) and Roblox Studio (local)
+- roblox-ts and pure Luau
+- Source-mapped errors (Luau line numbers back to `.ts` files)
+- Code coverage
+- Two backends: Open Cloud (remote) and Studio (local)
 
 ## Install
 
@@ -25,11 +29,28 @@ real Roblox session, then reports results in your terminal.
 npm install @isentinel/jest-roblox
 ```
 
-## Quick start
+### Standalone binary (no Node.js required)
+
+Pre-built binaries are attached to each
+[GitHub release](https://github.com/christopher-buss/jest-roblox-cli/releases).
+Install with your preferred tool manager:
+
+```bash
+mise use github:christopher-buss/jest-roblox-cli
+rokit add christopher-buss/jest-roblox-cli
+
+```
+
+The standalone binary has a few limitations compared to the npm package:
+
+- `--typecheck` and `--typecheckOnly` are not available
+- `.ts` config files are not supported (use `.json`, `.js`, or `.mjs`)
+- External tools (rojo, lute for coverage) must still be on your `PATH`
 
-Create a config file in your project root.
+## Quick start
 
-**roblox-ts project** (`jest.config.ts`):
+Add a `jest.config.ts` (or `.js`, `.json`, `.yaml`, `.toml`) to your project
+root:
 
 ```typescript
 import { defineConfig } from "@isentinel/jest-roblox";
@@ -40,17 +61,7 @@ export default defineConfig({
 });
 ```
 
-**Luau project** (`jest.config.json`):
-
-```json
-{
-	"luauRoots": ["./src"],
-	"placeFile": "./game.rbxl",
-	"projects": ["ReplicatedStorage/shared"]
-}
-```
-
-Then run your tests:
+Then run:
 
 ```bash
 jest-roblox
@@ -80,53 +91,110 @@ jest-roblox --backend open-cloud
 jest-roblox --coverage
 
 # Output JSON results
-jest-roblox --json --outputFile results.json
+jest-roblox --formatters json --outputFile results.json
 
 # Short output for AI tools
-jest-roblox --compact
+jest-roblox --formatters agent
+
+# Save game output (print/warn/error) to file
+jest-roblox --gameOutput game-logs.txt
+
+# Run only specific named projects
+jest-roblox --project client
 ```
 
 ## Configuration
 
-You can put your config in any of these formats (c12 discovers them
-automatically):
+Config files are loaded by [c12](https://github.com/unjs/c12), which
+auto-discovers `jest.config.*` in any format it supports (`.ts`, `.js`, `.mjs`,
+`.cjs`, `.json`, `.yaml`, `.toml`).
 
-- `jest.config.ts` / `jest.config.js` / `jest.config.mjs` / `jest.config.cjs`
-- `jest.config.json` / `jest.config.yaml` / `jest.config.toml`
+Configs can extend a shared base with `extends`:
 
-CLI flags always win over config file values. Config file values always win over
-built-in defaults.
+```typescript
+export default defineConfig({
+	extends: "../../jest.shared.ts",
+	projects: ["ReplicatedStorage/shared"],
+});
+```
+
+Precedence: CLI flags > config file > extended config > defaults.
 
 ### Config fields
 
 | Field | What it does | Default |
 |---|---|---|
 | `projects` | Where to look for tests in the DataModel | **required** |
-| `backend` | `"auto"`, `"open-cloud"`, or `"studio"` | `"auto"` |
+| `backend` | `"open-cloud"` or `"studio"` | — |
 | `placeFile` | Path to your `.rbxl` file | `"./game.rbxl"` |
 | `timeout` | Max time for tests to run (ms) | `300000` (5 min) |
 | `sourceMap` | Map Luau errors back to TypeScript (roblox-ts only) | `true` |
 | `port` | WebSocket port for Studio backend | `3001` |
 | `testMatch` | Glob patterns that find test files | `**/*.spec.ts`, `**/*.test.ts`, etc. |
-| `testPathIgnorePatterns` | Patterns to skip | `/node_modules/`, `/dist/` |
+| `testPathIgnorePatterns` | Patterns to skip | `/node_modules/`, `/dist/`, `/out/` |
 | `rojoProject` | Path to your Rojo project file | auto |
 | `jestPath` | Where Jest lives in the DataModel | auto |
 | `setupFiles` | Scripts to run before the test environment loads | — |
 | `setupFilesAfterEnv` | Scripts to run after the test environment loads | — |
+| `formatters` | Output formatters (`"default"`, `"agent"`, `"json"`, `"github-actions"`) | `["default"]` |
+| `gameOutput` | Path to write game print/warn/error output | — |
+| `showLuau` | Show Luau code snippets in failure output | `true` |
+| `cache` | Cache place file uploads by content hash | `true` |
+| `pollInterval` | How often to poll for results in ms (Open Cloud) | `500` |
 
 ### Coverage fields
 
+> [!IMPORTANT]
+> Coverage requires [Lute](https://github.com/4lve/lute) to be installed and
+> on your `PATH`. Lute parses Luau ASTs so the CLI can insert coverage probes.
+
 | Field | What it does | Default |
 |---|---|---|
 | `collectCoverage` | Turn on coverage | `false` |
 | `coverageDirectory` | Where to write coverage reports | `"coverage"` |
 | `coverageReporters` | Which report formats to use | `["text", "lcov"]` |
 | `coverageThreshold` | Minimum coverage to pass | — |
-| `coveragePathIgnorePatterns` | Files to leave out of coverage | test files, node_modules |
+| `coveragePathIgnorePatterns` | Files to leave out of coverage | test files, `node_modules`, `rbxts_include` |
 | `collectCoverageFrom` | Globs for files to include in coverage | — |
 | `luauRoots` | Where Luau files live (auto from tsconfig `outDir` for roblox-ts, or set by hand for pure Luau) | auto |
 
-### Full example (roblox-ts)
+### Project-level config
+
+`projects` can be strings (DataModel paths) or objects with per-project
+overrides:
+
+```typescript
+import { defineConfig, defineProject } from "@isentinel/jest-roblox";
+
+export default defineConfig({
+	placeFile: "./game.rbxl",
+	projects: [
+		{
+			test: defineProject({
+				displayName: { name: "core", color: "magenta" },
+				include: ["src/**/*.spec.ts"],
+				mockDataModel: true,
+				outDir: "out-test/src",
+			}),
+		},
+		{
+			test: defineProject({
+				displayName: { name: "core:integration", color: "white" },
+				include: ["test/**/*.spec.ts"],
+				mockDataModel: true,
+				outDir: "out-test/test",
+			}),
+		},
+	],
+});
+```
+
+Available per-project fields: `displayName`, `include`, `exclude`, `testMatch`,
+`testRegex`, `testPathIgnorePatterns`, `setupFiles`, `setupFilesAfterEnv`,
+`testTimeout`, `slowTestThreshold`, `testEnvironment`, `snapshotFormat`,
+`outDir`, `root`, and the Jest mock flags (`clearMocks`, `resetMocks`, etc.).
+
+### Full example
 
 ```typescript
 import { defineConfig } from "@isentinel/jest-roblox";
@@ -146,32 +214,13 @@ export default defineConfig({
 });
 ```
 
-### Full example (Luau)
-
-```json
-{
-	"backend": "open-cloud",
-	"collectCoverage": true,
-	"coverageThreshold": {
-		"branches": 70,
-		"functions": 80,
-		"statements": 80
-	},
-	"jestPath": "ReplicatedStorage/Packages/Jest",
-	"luauRoots": ["./src"],
-	"placeFile": "./game.rbxl",
-	"projects": ["ReplicatedStorage/client", "ServerScriptService/server"],
-	"timeout": 60000
-}
-```
-
 ## Backends
 
-jest-roblox-cli can run tests two ways:
+Two ways to run tests:
 
 ### Open Cloud (remote)
 
-Uploads your place file to Roblox, runs the tests there, and polls for results.
+Uploads your place file to Roblox and polls for results.
 
 You need these environment variables:
 
@@ -183,29 +232,26 @@ You need these environment variables:
 
 ### Studio (local)
 
-Connects to Roblox Studio on your machine through a WebSocket plugin. This is
-faster because there is no upload step, but requires Roblox Studio to be open
-and running the plugin.
-
-> [!TIP]
-> In auto mode, the CLI tries Studio first. If Studio is not running, it falls back to Open Cloud.
+Connects to Roblox Studio over WebSocket. Faster than Open Cloud (no upload
+step), but Studio must be open with the plugin running.
 
 ## CLI flags
 
 | Flag | What it does |
 |---|---|
-| `--backend <type>` | Choose `auto`, `open-cloud`, or `studio` |
+| `--backend <type>` | Choose `open-cloud` or `studio` |
 | `--port <n>` | WebSocket port for Studio |
 | `--config <path>` | Path to config file |
 | `--testPathPattern <regex>` | Filter test files by path |
 | `-t, --testNamePattern <regex>` | Filter tests by name |
-| `--json` | Output results as JSON |
-| `--compact` | Short output for AI tools |
+| `--formatters <name...>` | Output formatters (`default`, `agent`, `json`, `github-actions`) |
 | `--outputFile <path>` | Write results to a file |
+| `--gameOutput <path>` | Write game print/warn/error to a file |
 | `--coverage` | Collect coverage |
 | `--coverageDirectory <path>` | Where to put coverage reports |
 | `--coverageReporters <r...>` | Which report formats to use |
 | `--luauRoots <path...>` | Where compiled Luau files live |
+| `--no-show-luau` | Hide Luau code in failure output |
 | `-u, --updateSnapshot` | Update snapshot files |
 | `--sourceMap` | Map Luau errors to TypeScript (roblox-ts only) |
 | `--rojoProject <path>` | Path to Rojo project file |
@@ -214,6 +260,7 @@ and running the plugin.
 | `--no-color` | Turn off colors |
 | `--no-cache` | Force a fresh place file upload |
 | `--pollInterval <ms>` | How often to check for results (Open Cloud) |
+| `--project <name...>` | Filter which named projects to run |
 | `--projects <path...>` | DataModel paths that hold tests |
 | `--setupFiles <path...>` | Scripts to run before env |
 | `--setupFilesAfterEnv <path...>` | Scripts to run after env |
@@ -223,24 +270,21 @@ and running the plugin.
 
 ## How it works
 
-1. Scans your project for files that match `testMatch` patterns
-2. Uses Rojo to build a `.rbxl` file with your code
-3. Sends the place to Roblox via Open Cloud or Studio over WebSocket
-4. Reads Jest JSON output from the Roblox session
-5. For roblox-ts projects, turns Luau line numbers into TypeScript line numbers
-   using source maps
-6. Prints pass/fail results in your terminal
+1. Finds files matching `testMatch` patterns
+2. Builds a `.rbxl` via Rojo
+3. Sends the place to Roblox (Open Cloud upload or Studio WebSocket)
+4. Parses Jest JSON output from the session
+5. Maps Luau line numbers to TypeScript via source maps (roblox-ts only)
+6. Prints results
 
 > [!NOTE]
-> For coverage, there are extra steps. The tool copies your Luau files, adds
-> tracking code to each line, and builds a special place file. After the tests
-> run, it maps the tracking data back to your source. For roblox-ts projects, it
-> maps through source maps to show TypeScript lines.
+> Coverage adds extra steps: copy Luau files, insert tracking probes, build a
+> separate place file, then map hit counts back to source. For roblox-ts, this
+> goes through source maps to report TypeScript lines.
 
 ## Test file patterns
 
-The tool finds test files by these patterns (you can change them with
-`testMatch`):
+Default `testMatch` patterns (configurable):
 
 - TypeScript: `*.spec.ts`, `*.test.ts`, `*.spec.tsx`, `*.test.tsx`
 - Luau: `*.spec.lua`, `*.test.lua`, `*.spec.luau`, `*.test.luau`
@@ -255,7 +299,8 @@ jest-roblox-cli/
 │   ├── backends/     Open Cloud and Studio backends
 │   ├── config/       Config loading and validation
 │   ├── coverage/     Coverage instrumentation pipeline
-│   ├── formatters/   Human, JSON, and compact output
+│   ├── formatters/   Output formatters (default, agent, JSON, GitHub Actions)
+│   ├── highlighter/  Luau syntax highlighting
 │   ├── reporter/     Result parsing and validation
 │   ├── source-mapper/ Luau-to-TypeScript error mapping
 │   ├── snapshot/     Snapshot file handling
@@ -292,7 +337,7 @@ eslint .
 ```
 
 > [!IMPORTANT]
-> This project keeps 100% test coverage. Write tests before you write code. Every pull request must keep full coverage.
+> 100% test coverage is enforced. Write tests first. Every PR must maintain full coverage.
 
 ## License
 

package/bin/jest-roblox.js

@@ -1,4 +1,16 @@
 #!/usr/bin/env node
-import { main } from "../dist/cli.mjs";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
-main();
+const sourceEntry = resolve(dirname(fileURLToPath(import.meta.url)), "../src/cli.ts");
+
+if (existsSync(sourceEntry)) {
+	const { register } = await import("node:module");
+	register("../loaders/luau-raw.mjs", import.meta.url);
+	const { main } = await import("../src/cli.ts");
+	main();
+} else {
+	const { main } = await import("../dist/cli.mjs");
+	main();
+}

package/dist/cli.d.mts

@@ -1,8 +1,10 @@
-import { t as CliOptions } from "./schema-DcDQmTyn.mjs";
+import { _ as ResolvedProjectConfig, n as ExecuteResult, v as CliOptions } from "./executor-DqZE3wME.mjs";
 
 //#region src/cli.d.ts
 declare function parseArgs(args: Array<string>): CliOptions;
+declare function filterByName(projects: Array<ResolvedProjectConfig>, names: Array<string>): Array<ResolvedProjectConfig>;
+declare function mergeProjectResults(results: Array<ExecuteResult>): ExecuteResult;
 declare function run(args: Array<string>): Promise<number>;
 declare function main(): Promise<void>;
 //#endregion
-export { main, parseArgs, run };
+export { filterByName, main, mergeProjectResults, parseArgs, run };