@isentinel/jest-roblox 0.3.6 → 0.3.8

package/dist/{schema-BCTnsaiC.d.mts → schema-i-pZhLCV.d.mts}

@@ -788,7 +788,12 @@ type _Except<ObjectType, KeysType extends keyof ObjectType, Options extends Requ
 //#region src/config/resolve-typecheck-config.d.ts
 /** Host-only Type Test config. Valid at root `test:` and per-project `test:`. */
 interface TypecheckConfig {
+  /**
+  * Enable Type Tests (`*.spec-d.ts`/`*.test-d.ts`). This is the only gate —
+  * setting other typecheck fields does not auto-enable. Default `false`.
+  */
   enabled?: boolean;
+  /** Globs excluded from Type Test discovery. */
   exclude?: Array<string>;
   /**
   * When `false` (default), type errors in non-test source files surface as
@@ -796,50 +801,111 @@ interface TypecheckConfig {
   * discovered Type Test files are suppressed.
   */
   ignoreSourceErrors?: boolean;
+  /**
+  * Globs selecting Type Test files. When unset, derived from the project's
+  * runtime `include` (`.spec.` → `.spec-d.`).
+  */
   include?: Array<string>;
+  /** Run only Type Tests and skip Runtime Tests. Implies `enabled`. Default `false`. */
   only?: boolean;
-  /** Milliseconds the tsgo spawn may run before it is killed and the pass throws. */
+  /**
+  * Milliseconds to wait for the tsgo process to start before the pass
+  * throws. Bounds only startup, not the type-check itself — a slow check is
+  * governed by the run-level `timeout`. Default `10000`.
+  */
   spawnTimeout?: number;
+  /** Custom tsconfig used for type checking (root-only in projects mode). */
   tsconfig?: string;
 }
 //#endregion
 //#region src/config/schema.d.ts
-type Backend = "auto" | "open-cloud" | "studio";
+type Backend = "auto" | "open-cloud" | "studio" | "studio-cli";
 type CoverageReporter = keyof ReportOptions;
 type FormatterEntry = [string, Record<string, unknown>] | string;
+/** pretty-format options controlling how snapshots are serialized. */
 interface SnapshotFormatOptions {
+  /** Call a value's `toJSON` method (when present) before serializing it. */
   callToJSON?: boolean;
+  /** Escape regex special characters in string snapshots. */
   escapeRegex?: boolean;
+  /** Escape backslashes and quotes in string snapshots. */
   escapeString?: boolean;
+  /** Number of spaces per indentation level. */
   indent?: number;
+  /** Maximum depth of nested objects/arrays to print before collapsing. */
   maxDepth?: number;
+  /** Print on a single line with no indentation. */
   min?: boolean;
+  /** Print the `Object`/class prototype name for plain objects. */
   printBasicPrototype?: boolean;
+  /** Print function names instead of `[Function]`. */
   printFunctionName?: boolean;
 }
+/** A reporter label with a colour, used to tag a project's output. */
 interface DisplayName {
+  /** The label shown in reporter output. */
   name: string;
+  /** Colour applied to the label (e.g. `"magenta"`, `"white"`). */
   color: string;
 }
 /** Jest-passthrough keys valid both at `test:` and per-project. */
 interface SharedTestConfig {
+  /** Automatically mock every required module. Default `false`. */
   automock?: boolean;
+  /**
+  * Clear `mock.calls`/`instances`/`results` on every mock before each test
+  * (like `jest.clearAllMocks()`). Default `false`.
+  */
   clearMocks?: boolean;
+  /**
+  * Inject Jest's globals (`describe`, `it`, `expect`, …) into the test
+  * environment instead of requiring them explicitly. Default `true`.
+  */
   injectGlobals?: boolean;
+  /**
+  * Swap the live Roblox DataModel for a fresh mock instance per test file so
+  * tests can mutate the tree in isolation. Default `false`.
+  */
   mockDataModel?: boolean;
+  /**
+  * Reset mock state and remove any mocked implementation before each test
+  * (like `jest.resetAllMocks()`). Default `false`.
+  */
   resetMocks?: boolean;
+  /**
+  * Reset the module registry before each test so every test re-requires a
+  * fresh module graph. Default `false`.
+  */
   resetModules?: boolean;
+  /**
+  * Restore `spyOn` mocks to their original implementations before each test
+  * (like `jest.restoreAllMocks()`). Default `false`.
+  */
   restoreMocks?: boolean;
+  /** DataModel paths to scripts run once before the test framework is installed. */
   setupFiles?: Array<string>;
+  /**
+  * DataModel paths to scripts run after the framework is installed, before
+  * each test file — the place for global hooks and custom matchers.
+  */
   setupFilesAfterEnv?: Array<string>;
+  /** Seconds after which a single test is reported as slow. Default `5`. */
   slowTestThreshold?: number;
+  /** pretty-format options controlling how snapshots are serialized. */
   snapshotFormat?: SnapshotFormatOptions;
+  /** DataModel paths to custom snapshot serializer modules. */
   snapshotSerializers?: Array<string>;
+  /** Test environment used to run the tests. */
   testEnvironment?: string;
+  /** Options forwarded to the test environment. */
   testEnvironmentOptions?: Record<string, unknown> | string;
+  /** Glob patterns Jest uses to detect test files. */
   testMatch?: Array<string>;
+  /** Regex patterns; a test file is skipped when its path matches any of them. */
   testPathIgnorePatterns?: Array<string>;
+  /** Regex pattern(s) Jest uses to detect test files (alternative to `testMatch`). */
   testRegex?: Array<string> | string;
+  /** Default per-test timeout in milliseconds. Default `5000`. */
   testTimeout?: number;
   /**
   * Host-only Type Test config. Never forwarded to the Roblox runtime.
@@ -849,10 +915,27 @@ interface SharedTestConfig {
 }
 /** Jest-passthrough keys valid only per-project (under `projects[N].test`). */
 interface ProjectTestConfig extends SharedTestConfig {
+  /**
+  * Reporter label identifying this project's tests — a string, or
+  * `{ name, color }` to tint it. Must be unique across projects.
+  */
   displayName: DisplayName | string;
+  /** Globs subtracted from this project's Runtime Test discovery. */
   exclude?: Array<string>;
+  /**
+  * Globs (with TS extensions) selecting this project's test files, relative
+  * to `root`. The static directory prefix of each glob maps to a Rojo
+  * `$path`/DataModel mount.
+  */
   include: Array<string>;
+  /**
+  * Compiled-output directory the project's `.luau` lives in. Setting it pins
+  * the project to a single DataModel mount (exact Rojo lookup, no
+  * auto-expand). roblox-ts users point this at the compiled output (e.g.
+  * `"out/client"`), not `"src/…"`.
+  */
   outDir?: string;
+  /** Base path prepended to this project's `include`, `exclude`, and `outDir`. */
   root?: string;
 }
 interface InlineProjectConfig {
@@ -890,47 +973,109 @@ interface WorkspaceConfig {
 type ProjectEntry = InlineProjectConfig | string;
 /** Jest-passthrough keys valid only at root `test:` (not per-project). */
 interface GlobalTestConfig extends SharedTestConfig {
+  /**
+  * Report coverage for every file matched by the coverage globs, even those
+  * no test exercised (untested files count as 0%). Default `false`.
+  */
   all?: boolean;
+  /**
+  * Stop the run after `n` failing test suites (`true` ⇒ after the first).
+  * Default `0` (never bail).
+  */
   bail?: boolean | number;
+  /** Run only tests affected by files changed since the given git ref. */
   changedSince?: string;
+  /** Assume a CI environment, which disables writing new snapshots. */
   ci?: boolean;
+  /** Clear Jest's transform cache before running, then exit. */
   clearCache?: boolean;
+  /** Collect code coverage during the run. Default `false`. */
   collectCoverage?: boolean;
+  /** Globs selecting which source files coverage is collected from. */
   collectCoverageFrom?: Array<string>;
+  /** Alias for {@link collectCoverage}. */
   coverage?: boolean;
+  /** Directory coverage reports are written to. Default `"coverage"`. */
   coverageDirectory?: string;
+  /** Globs excluded from coverage collection. */
   coveragePathIgnorePatterns?: Array<string>;
+  /**
+  * Istanbul reporters to emit (e.g. `"text"`, `"lcov"`, `"html"`). Default
+  * `["text", "lcov"]`.
+  */
   coverageReporters?: Array<CoverageReporter>;
+  /**
+  * Minimum coverage percentages (0–100); the run fails when any is not met.
+  */
   coverageThreshold?: {
     branches?: number;
     functions?: number;
     lines?: number;
     statements?: number;
   };
+  /** Print Jest's resolved config and debugging info. */
   debug?: boolean;
+  /** Reporter label for the whole run — a string, or `{ name, color }`. */
   displayName?: DisplayName | string;
+  /** Test environment to use, forwarded to the Jest runtime. */
   env?: string;
+  /**
+  * Globs subtracted from Runtime Test discovery. Applies to single-,
+  * multi-project, and `--workspace` runs (skipped for explicit file args).
+  */
   exclude?: Array<string>;
+  /** Show full diffs and error output instead of truncating. */
   expand?: boolean;
+  /** A JSON string of globals to expose in every test environment. */
   globals?: string;
+  /**
+  * Per-project globs selecting Runtime Test files. With no `projects`
+  * configured, the run derives one project per `luauRoots` mount and runtime
+  * discovery uses `testMatch` — this root-level `include` is not consumed
+  * there.
+  */
   include?: Array<string>;
+  /**
+  * Maximum worker count, or a percentage string like `"50%"`, for parallel
+  * test execution.
+  */
   maxWorkers?: number | string;
+  /** Omit stack traces from failure output. */
   noStackTrace?: boolean;
+  /** Default compiled-output directory for test discovery when not set per-project. */
   outDir?: string;
+  /** Exit `0` even when no tests are found. Default `false`. */
   passWithNoTests?: boolean;
+  /** Name of a preset that supplies base Jest config. */
   preset?: string;
+  /**
+  * Per-project configs for a multi-project run. Each entry is a DataModel
+  * path string, or an inline {@link defineProject} object.
+  */
   projects?: Array<ProjectEntry>;
+  /** Reporter modules (DataModel paths) used to format results. */
   reporters?: Array<string>;
+  /** Root directories Jest scans for tests and modules. */
   roots?: Array<string>;
+  /** Run all tests serially in the current process instead of in workers. */
   runInBand?: boolean;
+  /** Run only the projects whose `displayName` is listed. */
   selectProjects?: Array<string>;
+  /** Print the resolved config and exit without running tests. */
   showConfig?: boolean;
+  /** Suppress test `print`/console output. Default `false`. */
   silent?: boolean;
+  /** Process exit code used when tests fail. */
   testFailureExitCode?: string;
+  /** Run only tests whose full name matches this regex. */
   testNamePattern?: string;
+  /** Run only test files whose path matches this regex. */
   testPathPattern?: string;
+  /** Fake-timers mode (e.g. `"real"`, `"fake"`). */
   timers?: string;
+  /** Update stored snapshots to match current output. */
   updateSnapshot?: boolean;
+  /** Report each individual test result, not just suite summaries. Default `false`. */
   verbose?: boolean;
 }
 /**
@@ -938,10 +1083,32 @@ interface GlobalTestConfig extends SharedTestConfig {
 * jest-passthrough options live.
 */
 interface Config {
+  /**
+  * Execution backend. `"auto"` probes for a running Studio then falls back to
+  * Open Cloud; `"open-cloud"` uploads and runs via Roblox Open Cloud;
+  * `"studio"` drives a locally running Studio; `"studio-cli"` launches its own
+  * headless Studio via `--task RunScript` and quits it (pass `--headed` to show
+  * the Studio window during the run). Default `"auto"`. `"studio-cli"` is never
+  * selected by `"auto"` — request it explicitly.
+  */
   backend?: Backend;
+  /** Force ANSI colour in output. Default `true`. */
   color?: boolean;
+  /**
+  * Reuse the incrementally-instrumented coverage place between runs when
+  * nothing changed. Default `true`.
+  */
   coverageCache?: boolean;
+  /**
+  * One or more config files to inherit from (c12 layering), relative to this
+  * file. Local keys win over extended ones.
+  */
   extends?: Array<string> | string;
+  /**
+  * Output formatters — `"default"`, `"agent"`, `"json"`,
+  * `"github-actions"` — each a name or a `[name, options]` pair. Default
+  * `["default"]`.
+  */
   formatters?: Array<FormatterEntry>;
   /**
   * Where to write Game Output. A path, or `true` to default to
@@ -949,7 +1116,16 @@ interface Config {
   * single Aggregated Game Output file (consensus-resolved).
   */
   gameOutput?: string | true;
+  /**
+  * DataModel path to the Jest module the runner requires (e.g.
+  * `"ReplicatedStorage/Packages/Jest"`). Defaults to auto-detection in
+  * ReplicatedStorage.
+  */
   jestPath?: string;
+  /**
+  * Compiled-Luau directories to instrument for coverage. Defaults to the
+  * tsconfig `outDir`.
+  */
   luauRoots?: Array<string>;
   /**
   * Where to write the Jest result JSON. A path, or `true` to default to
@@ -957,17 +1133,50 @@ interface Config {
   * single aggregated result file (consensus-resolved).
   */
   outputFile?: string | true;
+  /** Number of places to shard the run across, or `"auto"` to pick automatically. */
   parallel?: "auto" | number;
+  /** Path to the `.rbxl` place uploaded and run. Default `"./game.rbxl"`. */
   placeFile?: string;
+  /** Open Cloud place id to publish/run against. */
   placeId?: string;
+  /** WebSocket port for the Studio backend. Default `3001`. */
   port?: number;
+  /**
+  * Path to the Rojo project file used to map DataModel paths to source.
+  * Auto-detected when unset.
+  */
   rojoProject?: string;
+  /**
+  * Base directory for resolving relative paths. Defaults to the current
+  * working directory.
+  */
   rootDir?: string;
+  /** Include the translated Luau line in error/stack output. Default `true`. */
   showLuau?: boolean;
+  /** Map Luau stack traces back to TypeScript source. Default `true`. */
   sourceMap?: boolean;
+  /**
+  * Path to the Roblox Studio executable the `"studio-cli"` backend launches.
+  * Overrides per-OS auto-discovery. Also settable via `--studioPath` or the
+  * `JEST_ROBLOX_STUDIO_PATH` environment variable.
+  */
+  studioPath?: string;
+  /**
+  * The Jest options block. Every jest-passthrough setting lives here, kept
+  * separate from the CLI/runner keys above.
+  */
   test?: GlobalTestConfig;
+  /**
+  * Maximum remote execution time in milliseconds before the run is
+  * abandoned. Default `300000`.
+  */
   timeout?: number;
+  /** Open Cloud universe id that owns the place. */
   universeId?: string;
+  /**
+  * Workspace-mode knobs for multi-package runs. Ignored outside
+  * `--workspace`.
+  */
   workspace?: WorkspaceConfig;
 }
 /**
@@ -1019,6 +1228,11 @@ interface CliOptions {
   files?: Array<string>;
   formatters?: Array<string>;
   gameOutput?: string;
+  /**
+  * Show the Studio window during a `studio-cli` run (`--headed`). CLI-only;
+  * inert for every other backend. Never sourced from config or env.
+  */
+  headed?: boolean;
   help?: boolean;
   outputFile?: string;
   packages?: string;
@@ -1034,6 +1248,7 @@ interface CliOptions {
   showLuau?: boolean;
   silent?: boolean;
   sourceMap?: boolean;
+  studioPath?: string;
   testNamePattern?: string;
   testPathPattern?: string;
   timeout?: number;
@@ -1048,13 +1263,9 @@ interface CliOptions {
   /** Directory to load the workspace config from when run outside a package. */
   workspaceRoot?: string;
 }
-interface ConfigInput extends Except<Config, "formatters" | "luauRoots" | "test"> {
-  formatters?: Mergeable<Array<FormatterEntry>>;
-  luauRoots?: Mergeable<Array<string>>;
-  test?: GlobalTestConfigInput;
-}
+type ConfigInput = { [K in keyof Config]?: K extends "formatters" ? Mergeable<Array<FormatterEntry>> : K extends "luauRoots" ? Mergeable<Array<string>> : K extends "test" ? GlobalTestConfigInput : Config[K] };
 type MergeableTestKey = "collectCoverageFrom" | "coveragePathIgnorePatterns" | "coverageReporters" | "coverageThreshold" | "reporters" | "roots" | "selectProjects" | "setupFiles" | "setupFilesAfterEnv" | "snapshotFormat" | "snapshotSerializers" | "testMatch" | "testPathIgnorePatterns";
-type GlobalTestConfigInput = Except<GlobalTestConfig, MergeableTestKey> & { [K in MergeableTestKey]?: Mergeable<NonNullable<GlobalTestConfig[K]>> };
+type GlobalTestConfigInput = { [K in keyof GlobalTestConfig]?: K extends MergeableTestKey ? Mergeable<NonNullable<GlobalTestConfig[K]>> : GlobalTestConfig[K] };
 declare const SHARED_TEST_KEYS: ReadonlySet<string>;
 /** Keys valid in `test:` (root) but not per-project (`projects[N].test`). */
 declare const GLOBAL_TEST_KEYS: ReadonlySet<string>;
@@ -1067,7 +1278,28 @@ declare const ROOT_CLI_KEYS: ReadonlySet<string>;
 * (not jest itself).
 */
 declare const JEST_ARGV_EXCLUDED_KEYS: ReadonlySet<string>;
+/**
+* Identity helper for authoring a typed `jest.config.*` file. Returns its
+* input unchanged; it exists purely to give editors autocompletion and
+* type-checking for the root config shape (`Config` plus the c12 layer props
+* on `ConfigInput`).
+*
+* Use it as the default export of a config file discovered by c12 (`.ts`,
+* `.js`, `.mjs`, `.cjs`, `.json`, `.yaml`, `.toml`). All jest-passthrough
+* options live under the `test:` block; root keys are CLI/runner-level.
+* Configs may extend a shared base via `extends`, and any `Mergeable` array
+* field (e.g. `test.testMatch`) accepts a function that receives the inherited
+* defaults and returns the merged value. Precedence is CLI flags > config file
+* > extended config > defaults.
+*/
 declare const defineConfig: (input: ConfigInput) => ConfigInput;
+/**
+* Identity helper for a single entry inside `test.projects`, mirroring
+* {@link defineConfig} for per-project overrides. Returns its input unchanged
+* and exists only for editor autocompletion and type-checking of the
+* `InlineProjectConfig` shape — a `test:` block carrying the project's
+* `include`/`displayName` plus any shared per-project jest options.
+*/
 declare const defineProject: (input: InlineProjectConfig) => InlineProjectConfig;
 //#endregion
 export { SnapshotFormatOptions as _, DisplayName as a, defineProject as b, GlobalTestConfig as c, ProjectEntry as d, ProjectTestConfig as f, SharedTestConfig as g, SHARED_TEST_KEYS as h, DEFAULT_CONFIG as i, InlineProjectConfig as l, ResolvedConfig as m, Config as n, FormatterEntry as o, ROOT_CLI_KEYS as p, ConfigInput as r, GLOBAL_TEST_KEYS as s, CliOptions as t, JEST_ARGV_EXCLUDED_KEYS as u, WorkspaceConfig as v, TypecheckConfig as x, defineConfig as y };

package/loaders/luau-raw.d.mts

@@ -9,7 +9,7 @@ interface ResolveResult {
 	url: string;
 }
 
-type NextResolve = (specifier: string, context: ResolveContext) => Promise<ResolveResult>;
+type NextResolve = (specifier: string, context: ResolveContext) => ResolveResult;
 
 interface LoadContext {
 	conditions?: Array<string>;
@@ -23,12 +23,12 @@ interface LoadResult {
 	source: string;
 }
 
-type NextLoad = (url: string, context: LoadContext) => Promise<LoadResult>;
+type NextLoad = (url: string, context: LoadContext) => LoadResult;
 
 export function resolve(
 	specifier: string,
 	context: ResolveContext,
 	nextResolve: NextResolve,
-): Promise<ResolveResult>;
+): ResolveResult;
 
-export function load(url: string, context: LoadContext, nextLoad: NextLoad): Promise<LoadResult>;
+export function load(url: string, context: LoadContext, nextLoad: NextLoad): LoadResult;

package/loaders/luau-raw.mjs

@@ -1,8 +1,8 @@
-import { readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
-export async function resolve(specifier, context, nextResolve) {
-	const resolved = await nextResolve(specifier, context);
+export function resolve(specifier, context, nextResolve) {
+	const resolved = nextResolve(specifier, context);
 
 	if (resolved.url.endsWith(".luau") || resolved.url.endsWith(".lua")) {
 		return { ...resolved, format: "luau-raw" };
@@ -11,7 +11,7 @@ export async function resolve(specifier, context, nextResolve) {
 	return resolved;
 }
 
-export async function load(url, context, nextLoad) {
+export function load(url, context, nextLoad) {
 	if (context.format === "luau-raw") {
 		if (url.endsWith(".lua")) {
 			return {
@@ -21,7 +21,7 @@ export async function load(url, context, nextLoad) {
 			};
 		}
 
-		const content = await readFile(fileURLToPath(url), "utf-8");
+		const content = readFileSync(fileURLToPath(url), "utf-8");
 		return {
 			format: "module",
 			shortCircuit: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isentinel/jest-roblox",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Jest-compatible CLI for running roblox-ts tests via Roblox Open Cloud",
   "keywords": [
     "jest",
@@ -48,7 +48,7 @@
     "!dist/**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@bedrock-rbx/ocale": "0.1.0-beta.18",
+    "@bedrock-rbx/ocale": "0.1.0-beta.19",
     "@jridgewell/trace-mapping": "0.3.31",
     "arktype": "2.2.0",
     "c12": "4.0.0-beta.5",
@@ -67,7 +67,7 @@
   },
   "devDependencies": {
     "@isentinel/eslint-config": "5.2.0",
-    "@isentinel/roblox-ts": "4.0.7",
+    "@isentinel/roblox-ts": "4.0.10",
     "@isentinel/tsconfig": "1.2.0",
     "@isentinel/weld": "0.2.0",
     "@oxc-project/types": "0.123.0",

package/plugin/src/init.server.luau

@@ -12,11 +12,11 @@ local WEBSOCKET_URL = "ws://localhost:3001"
 local RECONNECT_DELAY = 0.1
 
 -- Plugin/CLI protocol version. Must match `STUDIO_PROTOCOL_VERSION` in
--- `src/backends/studio.ts`. Bumped when the runtime contract changes (e.g.
--- runtime-injection payload shape). The plugin rejects mismatched CLI
--- versions with a `version_mismatch` response so users see a clear upgrade
+-- `src/backends/studio.ts`. Bumped when the runtime contract changes — v3 added
+-- the run-mode workspace dispatch + version echo. The plugin rejects mismatched
+-- CLI versions with a `version_mismatch` response so users see a clear upgrade
 -- message rather than running with stale behaviour or an opaque timeout.
-local PROTOCOL_VERSION = 2
+local PROTOCOL_VERSION = 3
 
 local IsDebug = ReplicatedStorage:GetAttribute("JEST_ROBLOX_DEBUG") == true
 ReplicatedStorage:GetAttributeChangedSignal("JEST_ROBLOX_DEBUG"):Connect(function(): ()
@@ -130,11 +130,18 @@ local function connect(): ()
 				local runOk, result = pcall(function(): any
 					return StudioTestService:ExecuteRunModeAsync({
 						test = true,
+						-- Echo the negotiated version into the Run-mode payload so
+						-- the run-mode runner's own handshake passes (it validates
+						-- `protocolVersion`, shared with the studio-cli path).
+						protocolVersion = PROTOCOL_VERSION,
 						config = message.config,
 						-- Filtered injection targets (parallel to configs)
 						-- so the Run Mode runner skips mounts that already
 						-- have a user-authored jest.config on disk.
 						runtimeStubMounts = message.runtimeStubMounts,
+						-- Present only for workspace runs: the staged entries the
+						-- run-mode runner dispatches to the embedded materializer.
+						workspace = message.workspace,
 					})
 				end)