@isentinel/jest-roblox 0.3.7 → 0.3.9

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

@@ -819,7 +819,7 @@ interface TypecheckConfig {
 }
 //#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. */
@@ -1028,7 +1028,12 @@ interface GlobalTestConfig extends SharedTestConfig {
   expand?: boolean;
   /** A JSON string of globals to expose in every test environment. */
   globals?: string;
-  /** Globs selecting Runtime Test files when no `projects` are configured. */
+  /**
+  * 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
@@ -1081,7 +1086,10 @@ 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. Default `"auto"`.
+  * `"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`. */
@@ -1148,6 +1156,12 @@ interface Config {
   /** 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.
   */
@@ -1214,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;
@@ -1229,6 +1248,7 @@ interface CliOptions {
   showLuau?: boolean;
   silent?: boolean;
   sourceMap?: boolean;
+  studioPath?: string;
   testNamePattern?: string;
   testPathPattern?: string;
   timeout?: number;

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.7",
+  "version": "0.3.9",
   "description": "Jest-compatible CLI for running roblox-ts tests via Roblox Open Cloud",
   "keywords": [
     "jest",
@@ -66,8 +66,8 @@
     "ws": "8.20.1"
   },
   "devDependencies": {
-    "@isentinel/eslint-config": "5.2.0",
-    "@isentinel/roblox-ts": "4.0.7",
+    "@isentinel/eslint-config": "6.0.0-beta.3",
+    "@isentinel/roblox-ts": "4.0.10",
     "@isentinel/tsconfig": "1.2.0",
     "@isentinel/weld": "0.2.0",
     "@oxc-project/types": "0.123.0",
@@ -86,9 +86,9 @@
     "@vitest/eslint-plugin": "1.6.19",
     "better-typescript-lib": "2.12.0",
     "bumpp": "11.1.0",
-    "eslint": "9.39.4",
+    "eslint": "10.6.0",
     "eslint-plugin-jest-extended": "3.0.1",
-    "eslint-plugin-n": "18.0.1",
+    "eslint-plugin-n": "18.2.1",
     "eslint-plugin-pnpm": "1.6.1",
     "jest-extended": "7.0.0",
     "memfs": "4.57.2",

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)
 

package/plugin/src/test-in-run-mode.server.luau

@@ -7,11 +7,23 @@ if not RunService:IsRunning() then
 	return
 end
 
-local function endWithError(err: string): ()
+-- Plugin/CLI protocol version. Must match `STUDIO_PROTOCOL_VERSION` in
+-- `src/backends/studio.ts` and `STUDIO_CLI_PROTOCOL_VERSION` in
+-- `src/backends/studio-cli.ts`. v3 added the run-mode workspace dispatch + this
+-- version echo. The runner validates the version the CLI sent and echoes its own
+-- in `EndTest`, so the CLI surfaces a clean "update the plugin" error against a
+-- mismatched plugin rather than running with stale runtime semantics.
+local PROTOCOL_VERSION = 3
+
+-- Every result (success or failure) echoes `protocolVersion` so the studio-cli
+-- host can detect a stale plugin: one predating this echo omits the field and
+-- the host rejects it as a version mismatch.
+local function endTest(jestOutput: string, gameOutput: string?): ()
 	local ok, endErr = pcall(function()
 		StudioTestService:EndTest({
-			jestOutput = HttpService:JSONEncode({ success = false, err = err }),
-			gameOutput = "[]",
+			jestOutput = jestOutput,
+			gameOutput = gameOutput or "[]",
+			protocolVersion = PROTOCOL_VERSION,
 		})
 	end)
 	if not ok then
@@ -19,6 +31,10 @@ local function endWithError(err: string): ()
 	end
 end
 
+local function endWithError(err: string): ()
+	endTest(HttpService:JSONEncode({ success = false, err = err }), "[]")
+end
+
 local testArgs = StudioTestService:GetTestArgs()
 if testArgs == nil then
 	for _ = 1, 50 do
@@ -34,16 +50,24 @@ if testArgs == nil then
 	return
 end
 
-if testArgs.config == nil or testArgs.config.configs == nil then
-	local keysOk, keys = pcall(HttpService.JSONEncode, HttpService, testArgs)
+-- Version handshake: reject a missing or mismatched `protocolVersion` before
+-- running anything, mirroring the WebSocket `version_mismatch` path. The error
+-- envelope still echoes our version (via endTest), so the CLI surfaces the
+-- upgrade message either through this error or the version echo.
+local clientVersion = if typeof(testArgs.protocolVersion) == "number"
+	then testArgs.protocolVersion
+	else nil
+if clientVersion ~= PROTOCOL_VERSION then
 	endWithError(
-		"testArgs.config.configs is nil. Keys: " .. (if keysOk then keys else "<unencodable>")
+		"Studio plugin protocol version mismatch — plugin v"
+			.. tostring(PROTOCOL_VERSION)
+			.. ", CLI v"
+			.. tostring(clientVersion)
+			.. ". Update the jest-roblox Studio plugin to match the CLI."
 	)
 	return
 end
 
-local configs = testArgs.config.configs
-
 local loadStringEnabled = pcall(function()
 	loadstring("return true")
 end)
@@ -53,6 +77,41 @@ if not loadStringEnabled then
 	return
 end
 
+-- Dispatch by payload shape. A `workspace` payload drives the staged
+-- materializer (clone each package from the mega-place's `__pkg_stage`, run,
+-- reset) via the shared single-process embedded runner — the same code OCALE
+-- runs, minus the MemoryStore queue. Otherwise the existing single-/multi-
+-- project configs path runs `Runner.runProjects`.
+if testArgs.workspace ~= nil then
+	local embeddedOk, EmbeddedRunner =
+		pcall(require, script.Parent.shared.staging["embedded-runner"])
+	if not embeddedOk then
+		endWithError(
+			"Failed to require shared.staging.embedded-runner: " .. tostring(EmbeddedRunner)
+		)
+		return
+	end
+
+	local runOk, entriesOrErr = pcall(EmbeddedRunner.runEmbedded, script, testArgs.workspace)
+	if not runOk then
+		endWithError("EmbeddedRunner.runEmbedded threw: " .. tostring(entriesOrErr))
+		return
+	end
+
+	endTest(HttpService:JSONEncode({ entries = entriesOrErr }), "[]")
+	return
+end
+
+if testArgs.config == nil or testArgs.config.configs == nil then
+	local keysOk, keys = pcall(HttpService.JSONEncode, HttpService, testArgs)
+	endWithError(
+		"testArgs.config.configs is nil. Keys: " .. (if keysOk then keys else "<unencodable>")
+	)
+	return
+end
+
+local configs = testArgs.config.configs
+
 local requireOk, Runner = pcall(require, script.Parent.shared.runner)
 if not requireOk then
 	endWithError("Failed to require shared.runner: " .. tostring(Runner))
@@ -117,11 +176,7 @@ local function injectStubsForConfig(cfg, configIndex: number, injectionPaths: {
 		)
 		local stub = Instance.new("ModuleScript")
 		stub.Name = "jest.config"
-		stub.Source = string.format(
-			'return _G["%s"].configs[%d]',
-			SESSION_KEY,
-			configIndex
-		)
+		stub.Source = string.format('return _G["%s"].configs[%d]', SESSION_KEY, configIndex)
 		stub.Parent = leaf
 		-- Record immediately after parenting so a subsequent mount's
 		-- failure does not strand this one.
@@ -133,7 +188,9 @@ local function cleanupStubsForConfig(configIndex: number)
 	local injected = injectedPerConfig[configIndex]
 	if injected ~= nil then
 		for _, inst in injected do
-			pcall(function() inst:Destroy() end)
+			pcall(function()
+				inst:Destroy()
+			end)
 		end
 		injectedPerConfig[configIndex] = nil
 	end
@@ -159,8 +216,7 @@ end
 -- nested-project mounts (e.g. `ReplicatedStorage` and `ReplicatedStorage/Foo`)
 -- never have stubs in DataModel simultaneously — which would let Jest's
 -- parent-traversal config lookup resolve the wrong project's config.
-local runtimeStubMounts: { { string } } = testArgs.runtimeStubMounts
-	or table.create(#configs, {})
+local runtimeStubMounts: { { string } } = testArgs.runtimeStubMounts or table.create(#configs, {})
 
 local hooks = {
 	beforeConfig = function(cfg, index)
@@ -181,7 +237,4 @@ if not runOk then
 	return
 end
 
-StudioTestService:EndTest({
-	jestOutput = HttpService:JSONEncode({ entries = entriesOrErr }),
-	gameOutput = "[]",
-})
+endTest(HttpService:JSONEncode({ entries = entriesOrErr }), "[]")