@isentinel/jest-roblox 0.2.6 → 0.3.0

package/README.md

@@ -58,7 +58,9 @@ import { defineConfig } from "@isentinel/jest-roblox";
 
 export default defineConfig({
 	placeFile: "./game.rbxl",
-	projects: ["ReplicatedStorage/shared"],
+	test: {
+		projects: ["ReplicatedStorage/shared"],
+	},
 });
 ```
 
@@ -85,7 +87,8 @@ jest-roblox -t "should spawn"
 jest-roblox --testPathPattern player
 jest-roblox --testPathPattern="modifiers|define\\.spec|triggers"
 
-# Use a specific backend
+# Use a specific backend (default "auto" picks Studio if the plugin is
+# connected, else Open Cloud if credentials are set — see Backends below)
 jest-roblox --backend studio
 jest-roblox --backend open-cloud
 
@@ -110,37 +113,77 @@ Configs can extend a shared base with `extends`:
 ```typescript
 export default defineConfig({
 	extends: "../../jest.shared.ts",
-	projects: ["ReplicatedStorage/shared"],
+	test: {
+		projects: ["ReplicatedStorage/shared"],
+	},
 });
 ```
 
 Precedence: CLI flags > config file > extended config > defaults.
 
-### Config fields
+### Root config fields
+
+Two distinct buckets live at the root level. Jest passthrough fields live
+under `test:` (see "Test fields" below).
+
+#### Workspace Run Options
+
+Atomic to one invocation — these describe what the run targets and how the
+CLI presents output, not how any individual package runs. In `--workspace`
+mode they resolve as: CLI flag > unanimous per-package declaration >
+default. Mixed per-package declarations error loudly.
+
+| Field | What it does | Default |
+|---|---|---|
+| `backend` | `"auto"`, `"open-cloud"`, or `"studio"` | `"auto"` |
+| `color` | Use ANSI colors in console output | `true` |
+| `formatters` | Output formatters (`"default"`, `"agent"`, `"json"`, `"github-actions"`) | `["default"]` |
+| `gameOutput` | Write Game Output to a file — a path, or `true` for `game-output.log` under the root. In `--workspace` mode this is one grouped aggregate file across every package | — |
+| `outputFile` | Write the Jest result JSON — a path, or `true` for `jest-output.log` under the root. In `--workspace` mode this is the single merged result across every package | — |
+| `workspace.gameOutput` | `true` to also emit per-package Game Output files under `.jest-roblox/output/` (`--workspace` only) | — |
+| `workspace.outputFile` | `true` to also emit per-package result files under `.jest-roblox/output/` (`--workspace` only) | — |
+| `parallel` | Number of concurrent Open Cloud sessions, or `"auto"` (= `min(jobs, 3)`) | — |
+| `placeId` | Open Cloud place ID | — |
+| `port` | WebSocket port for Studio backend | `3001` |
+| `silent` | Suppress console output | `false` |
+| `universeId` | Open Cloud universe ID | — |
+
+#### Per-package fields
+
+Loaded per package (directly or via `extends: "../jest.shared.ts"`). The
+workspace-root config is NOT a source of truth for these — declare them in
+each package's own jest.config or in a shared config that every package
+extends.
 
 | Field | What it does | Default |
 |---|---|---|
-| `projects` | Where to look for tests in the DataModel | **required** |
-| `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/`, `/out/` |
 | `rojoProject` | Path to your Rojo project file | auto |
 | `jestPath` | Where Jest lives in the DataModel | auto |
+| `showLuau` | Show Luau code snippets in failure output | `true` |
+| `coverageCache` | Reuse incrementally-instrumented coverage shadow dir between runs | `true` |
+| `luauRoots` | Where Luau files live for coverage instrumentation | auto from tsconfig `outDir` |
+
+### Test fields
+
+Put these under `test: { ... }`.
+
+| Field | What it does | Default |
+|---|---|---|
+| `projects` | Where to look for tests in the DataModel | **required** |
+| `testMatch` | Glob patterns that find test files | `**/*.spec.ts`, `**/*.test.ts`, etc. |
+| `testPathIgnorePatterns` | Patterns to skip | `/node_modules/`, `/dist/`, `/out/` |
 | `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` |
-| `parallel` | Number of concurrent Open Cloud sessions, or `"auto"` (= `min(jobs, 3)`) | — |
+| `verbose` | Show individual test results | `false` |
+| `silent` | Suppress console output | `false` |
 
 ### Coverage fields
 
+Put these under `test: { ... }`.
+
 > [!IMPORTANT]
 > Coverage requires [Lute](https://github.com/luau-lang/lute) to be installed and
 > on your `PATH`. Lute parses Luau ASTs so the CLI can insert coverage probes.
@@ -153,7 +196,6 @@ Precedence: CLI flags > config file > extended config > defaults.
 | `coverageThreshold` | Minimum coverage to pass | — |
 | `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 |
 
 ### Project-level config
 
@@ -165,23 +207,25 @@ import { defineConfig, defineProject } from "@isentinel/jest-roblox";
 
 export default defineConfig({
 	placeFile: "./game.rbxl",
-	projects: [
-		{
-			test: defineProject({
-				displayName: { name: "client", color: "magenta" },
-				include: ["**/*.spec.ts"],
-				mockDataModel: true,
-				outDir: "out/src/client",
+	test: {
+		projects: [
+			defineProject({
+				test: {
+					displayName: { name: "client", color: "magenta" },
+					include: ["**/*.spec.ts"],
+					mockDataModel: true,
+					outDir: "out/src/client",
+				},
 			}),
-		},
-		{
-			test: defineProject({
-				displayName: { name: "server", color: "white" },
-				include: ["**/*.spec.ts"],
-				outDir: "out/src/server",
+			defineProject({
+				test: {
+					displayName: { name: "server", color: "white" },
+					include: ["**/*.spec.ts"],
+					outDir: "out/src/server",
+				},
 			}),
-		},
-	],
+		],
+	},
 });
 ```
 
@@ -192,22 +236,31 @@ import { defineConfig } from "@isentinel/jest-roblox";
 
 export default defineConfig({
 	backend: "open-cloud",
-	collectCoverage: true,
-	coverageThreshold: {
-		branches: 70,
-		functions: 80,
-		statements: 80,
-	},
 	jestPath: "ReplicatedStorage/Packages/Jest",
 	placeFile: "./game.rbxl",
-	projects: ["ReplicatedStorage/client", "ServerScriptService/server"],
+	test: {
+		collectCoverage: true,
+		coverageThreshold: {
+			branches: 70,
+			functions: 80,
+			statements: 80,
+		},
+		projects: ["ReplicatedStorage/client", "ServerScriptService/server"],
+	},
 	timeout: 60000,
 });
 ```
 
 ## Backends
 
-Two ways to run tests:
+Two ways to run tests, plus an auto-pick:
+
+### Auto (default)
+
+`--backend auto` (the default) probes for a connected Studio plugin first.
+If detected, runs via Studio; otherwise falls back to Open Cloud — but only
+if credentials are available (see Open Cloud below). With no plugin and no
+credentials, the run errors instead of silently falling back.
 
 ### Open Cloud (remote)
 
@@ -221,6 +274,39 @@ You need these environment variables:
 | `ROBLOX_UNIVERSE_ID` | The universe to run tests in |
 | `ROBLOX_PLACE_ID` | The place to run tests in |
 
+> Prefix any of the above with `JEST_` (e.g. `JEST_ROBLOX_PLACE_ID`) to override the unprefixed value. Use the `JEST_`-prefixed form when the generic names collide with other tooling.
+
+#### Required scopes
+
+Create the API key in the Creator Dashboard against the target universe, then
+grant it the scopes below. A `403` at runtime surfaces as a `PermissionError`
+with the missing scope name.
+
+Always required:
+
+| Scope | What it's for |
+|---|---|
+| `universe-places:write` | Publish the built `.rbxl` as a new place version |
+| `universe.place.luau-execution-session:write` | Start the Luau session that runs the tests |
+
+`--workspace --parallel >1` additionally requires the queue scopes for
+work-stealing across concurrent sessions:
+
+| Scope | What it's for |
+|---|---|
+| `memory-store.queue:add` / `:dequeue` / `:discard` | Work-stealing queue across concurrent sessions |
+
+`--workspace --parallel >1` with a streaming formatter additionally requires:
+
+| Scope | What it's for |
+|---|---|
+| `memory-store.sorted-map:read` / `:write` | Stream live per-package results back as packages finish |
+
+Streaming is enabled by default and disabled only for `--silent`,
+`--formatters json`, and `--formatters agent` (without `--verbose`).
+`--formatters agent --verbose` re-enables streaming and therefore still
+needs the sorted-map scopes; `--formatters github-actions` also streams.
+
 ### Studio (local)
 
 Connects to Roblox Studio over WebSocket. Faster than Open Cloud (no upload
@@ -229,7 +315,7 @@ multiple concurrent projects aren't supported yet.
 
 > [!NOTE]
 > For `--coverage`, prefer `--backend open-cloud` since the coverage output is
-> built to a separate output under `.jest-roblox-coverage/` that is likely not
+> built to a separate output under `.jest-roblox/coverage/` that is likely not
 > the studio place being served.
 
 Install the plugin with [Drillbit](https://github.com/jacktabscode/drillbit):
@@ -240,7 +326,7 @@ Create a file named drillbit.toml in your project's directory.
 
 ```toml
 [plugins.jest_roblox]
-github = "https://github.com/christopher-buss/jest-roblox-cli/releases/download/v0.2.4/JestRobloxRunner.rbxm"
+github = "https://github.com/christopher-buss/jest-roblox-cli/releases/download/v0.3.0/JestRobloxRunner.rbxm"
 ```
 
 Then run `drillbit` and it will download the plugin and install it in Studio for you.
@@ -249,11 +335,107 @@ Or download `JestRobloxRunner.rbxm` from the
 [latest release](https://github.com/christopher-buss/jest-roblox-cli/releases)
 and drop it into your Studio plugins folder.
 
+## Workspace mode
+
+Run tests across multiple packages in a pnpm workspace in a single
+invocation. Open Cloud only — Studio backend is not supported.
+
+> [!NOTE]
+> Package discovery uses one of two sources. By default it reads
+> `pnpm-workspace.yaml` at the workspace root. Alternatively, declare a
+> `workspace` block in your jest config (see
+> [Workspaces without pnpm](#workspaces-without-pnpm)) to enumerate packages
+> by glob — this works in Luau-only, npm, and yarn repos. `--affected-since`
+> always delegates change detection to `turbo` or `nx` and is not yet wired
+> for the `workspace.packages` source. When using Nx, each project's Nx name
+> must match the `package.json` `name` field — `--affected-since` returns Nx
+> project names and looks them up against the package list, so a mismatch
+> surfaces as `Package "<name>" not found in workspace`.
+
+Pick packages explicitly or by what changed:
+
+```bash
+# Specific packages
+jest-roblox --workspace --packages @scope/pkg-a,@scope/pkg-b
+
+# Everything changed since a git ref (via turbo/nx affected)
+jest-roblox --workspace --affected-since main
+```
+
+`--workspace` must be combined with `--packages` or `--affected-since` —
+the two are mutually exclusive, and either flag requires `--workspace`.
+
+### Workspaces without pnpm
+
+`pnpm-workspace.yaml` isn't required. Declare a `workspace` block in a shared
+config and have every package extend it:
+
+```ts
+// packages/testing/jest.shared.ts
+import { defineConfig } from "@isentinel/jest-roblox";
+
+export default defineConfig({
+	workspace: {
+		packages: ["packages/*"], // globs relative to root
+		root: "../..", // relative to THIS file; resolved at load
+	},
+	// shared jest options…
+});
+```
+
+```ts
+// packages/foo/jest.config.ts
+export default { extends: "../testing/jest.shared.ts" };
+```
+
+`workspace.root` and `workspace.packages` must be declared together. `root` is
+resolved to an absolute path relative to the file that declares it (the shared
+config), so it points at the same directory no matter which package you run
+from. Each glob in `packages` selects directories that contain a
+`jest.config.*`; the package name comes from `package.json#name`, falling back
+to the directory name (so Luau-only packages need no `package.json`). Every
+selected package must resolve the same `workspace.packages`/`root` — inheriting
+from one shared config guarantees this, and a package that overrides or omits
+it fails the run.
+
+Run from inside any package as usual. To run from a directory with no
+resolvable jest config (e.g. the repo root), either point at the shared config
+with `--workspace-root`:
+
+```bash
+jest-roblox --workspace --packages foo --workspace-root packages/testing
+```
+
+or add a re-export at the repo root so the config is discovered there:
+
+```ts
+// jest.config.ts (repo root)
+export { default } from "./packages/testing/jest.shared.ts";
+```
+
+Per-package coverage is aggregated into a single report under
+`<rootDir>/<coverageDirectory>`. `rootDir` defaults to the current working
+directory, so run from the workspace root (or set `rootDir`) if you want
+the report to land there.
+
+Game Output has two independent sinks. Setting `gameOutput` (a path, or
+`true`) writes one **grouped** aggregate file at the workspace root —
+`[{ package, project, entries }]`, one group per (package, project) that ran.
+Setting `workspace.gameOutput: true` writes a **per-package** file per
+(package, project) under `.jest-roblox/output/`. Either, both, or neither
+may be set; with both, humans see the aggregate announced and agents see the
+per-package paths.
+
+`outputFile` (the Jest result JSON) follows the same two-sink model:
+`outputFile` (a path, or `true`) writes one merged result at the workspace
+root, and `workspace.outputFile: true` writes a per-package result file per
+(package, project) under `.jest-roblox/output/`.
+
 ## CLI flags
 
 | Flag | What it does |
 |---|---|
-| `--backend <type>` | Choose `open-cloud` or `studio` |
+| `--backend <type>` | Choose `auto`, `open-cloud`, or `studio` |
 | `--port <n>` | WebSocket port for Studio |
 | `--config <path>` | Path to config file |
 | `--testPathPattern <regex>` | Filter test files by path |
@@ -264,24 +446,30 @@ and drop it into your Studio plugins folder.
 | `--coverage` | Collect coverage |
 | `--coverageDirectory <path>` | Where to put coverage reports |
 | `--coverageReporters <r...>` | Which report formats to use |
-| `--luauRoots <path...>` | Where compiled Luau files live |
+| `--collectCoverageFrom <glob>` | Globs for files to include in coverage (repeatable) |
 | `--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 |
+| `--timeout <ms>` | Max time for tests to run |
+| `--passWithNoTests` | Exit `0` when no test files are found |
 | `--verbose` | Show each test result |
 | `--silent` | Hide all output |
 | `--no-color` | Turn off colors |
-| `--no-cache` | Force a fresh place file upload |
-| `--pollInterval <ms>` | How often to check for results (Open Cloud) |
+| `--no-coverage-cache` | Force a clean coverage re-instrumentation |
 | `--parallel [n]` | Open Cloud concurrent sessions, or `auto` (= `min(jobs, 3)`) |
 | `--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 |
 | `--typecheck` | Run type tests too |
 | `--typecheckOnly` | Run only type tests |
 | `--typecheckTsconfig <path>` | tsconfig for type tests |
+| `--workspace` | Enable workspace mode (pair with `--packages` or `--affected-since`; see [Workspace mode](#workspace-mode)) |
+| `--packages <names>` | Comma-separated package names (workspace mode) |
+| `--affected-since <ref>` | Run only packages affected since a git ref (workspace mode) |
+| `--apiKey <key>` | Open Cloud API key (prefer env vars in CI — visible in process listings) |
+| `--universeId <id>` | Target universe ID (Open Cloud) |
+| `--placeId <id>` | Target place ID (Open Cloud) |
 
 ## How it works
 

package/dist/cli.d.mts

@@ -1,10 +1,8 @@
-import { _ as ResolvedProjectConfig, n as ExecuteResult, v as CliOptions } from "./executor-COuwZJJX.mjs";
+import { t as CliOptions } from "./schema-BpjBo-Aw.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 { filterByName, main, mergeProjectResults, parseArgs, run };
+export { main, parseArgs, run };