@isentinel/jest-roblox 0.0.1 → 0.0.2

package/dist/cli.d.mts

@@ -1,4 +1,4 @@
-import { t as CliOptions } from "./schema-ryuVGD35.mjs";
+import { t as CliOptions } from "./schema-CEsyg-FX.mjs";
 
 //#region src/cli.d.ts
 declare function main(): Promise<void>;

package/dist/cli.mjs

@@ -1,11 +1,115 @@
-import { g as createOpenCloudBackend, i as execute, m as createStudioBackend, n as parseGameOutput, o as writeJsonFile, r as writeGameOutput, t as formatGameOutputNotice, u as loadConfig, y as LuauScriptError } from "./game-output-BKBGosEI.mjs";
+import { g as createOpenCloudBackend, i as execute, m as createStudioBackend, n as parseGameOutput, o as writeJsonFile, r as writeGameOutput, t as formatGameOutputNotice, u as loadConfig, y as LuauScriptError } from "./game-output-BDatGA9S.mjs";
 import * as path$1 from "node:path";
 import process from "node:process";
 import { parseArgs as parseArgs$1 } from "node:util";
+import { WebSocketServer } from "ws";
 import * as fs from "node:fs";
 
 //#region package.json
-var version = "0.0.1";
+var version = "0.0.2";
+
+//#endregion
+//#region src/backends/auto.ts
+var StudioWithFallback = class {
+	studio;
+	constructor(studio) {
+		this.studio = studio;
+	}
+	async runTests(options) {
+		try {
+			return await this.studio.runTests(options);
+		} catch (err) {
+			if (isStudioBusyError(err)) {
+				process.stderr.write("Studio busy, falling back to Open Cloud\n");
+				return createOpenCloudBackend().runTests(options);
+			}
+			throw err;
+		}
+	}
+};
+function isStudioBusyError(error) {
+	if (error instanceof LuauScriptError) return /previous call to start play session/i.test(error.message);
+	return error.code === "EADDRINUSE";
+}
+async function probeStudioPlugin(port, timeoutMs, createServer = (wsPort) => {
+	return new WebSocketServer({ port: wsPort });
+}) {
+	return new Promise((resolve) => {
+		const wss = createServer(port);
+		const timer = setTimeout(() => {
+			wss.close();
+			resolve(false);
+		}, timeoutMs);
+		wss.on("connection", () => {
+			clearTimeout(timer);
+			wss.close();
+			resolve(true);
+		});
+		wss.on("error", () => {
+			clearTimeout(timer);
+			wss.close();
+			resolve(false);
+		});
+	});
+}
+async function resolveBackend(config, probe = probeStudioPlugin) {
+	if (config.backend === "studio") return createStudioBackend({
+		port: config.port,
+		timeout: config.timeout
+	});
+	if (config.backend === "open-cloud") return createOpenCloudBackend();
+	if (await probe(config.port, 500)) {
+		process.stderr.write("Backend: studio (plugin detected)\n");
+		const studio = createStudioBackend({
+			port: config.port,
+			timeout: config.timeout
+		});
+		if (hasOpenCloudCredentials()) return new StudioWithFallback(studio);
+		return studio;
+	}
+	if (hasOpenCloudCredentials()) {
+		process.stderr.write("Backend: open-cloud (no plugin, using Open Cloud)\n");
+		return createOpenCloudBackend();
+	}
+	throw new Error("No backend available: Studio plugin not detected and Open Cloud env vars (ROBLOX_OPEN_CLOUD_API_KEY, ROBLOX_UNIVERSE_ID, ROBLOX_PLACE_ID) are missing");
+}
+function hasOpenCloudCredentials() {
+	return process.env["ROBLOX_OPEN_CLOUD_API_KEY"] !== void 0 && process.env["ROBLOX_UNIVERSE_ID"] !== void 0 && process.env["ROBLOX_PLACE_ID"] !== void 0;
+}
+
+//#endregion
+//#region src/patch.ts
+const PATCH_MARKER = "-- jest-roblox-cli patch: enable snapshot mock override";
+const PATCH_LINES = `${PATCH_MARKER}
+if _G.__mockGetDataModelService then
+\treturn _G.__mockGetDataModelService
+end
+
+`;
+const PACKAGE_SUBPATH = path$1.join("node_modules", "@rbxts-js", "roblox-shared", "src", "getDataModelService.lua");
+function patchGetDataModelService(rootDirectory) {
+	const filePath = findSourceFile(rootDirectory);
+	const content = fs.readFileSync(filePath, "utf-8");
+	if (content.includes(PATCH_MARKER)) return {
+		filePath,
+		status: "already-patched"
+	};
+	fs.writeFileSync(filePath, PATCH_LINES + content);
+	return {
+		filePath,
+		status: "patched"
+	};
+}
+function findSourceFile(rootDirectory) {
+	let current = path$1.resolve(rootDirectory);
+	const { root } = path$1.parse(current);
+	while (current !== root) {
+		const candidate = path$1.join(current, PACKAGE_SUBPATH);
+		if (fs.existsSync(candidate)) return candidate;
+		current = path$1.dirname(current);
+	}
+	throw new Error(`Cannot find @rbxts-js/roblox-shared. Searched from ${rootDirectory} to filesystem root.`);
+}
 
 //#endregion
 //#region src/utils/glob.ts
@@ -38,7 +142,7 @@ const HELP_TEXT = `
 Usage: jest-roblox [options] [files...]
 
 Options:
-  --backend <type>          Backend: "open-cloud" or "studio" (default: open-cloud)
+  --backend <type>          Backend: "auto", "open-cloud", or "studio" (default: auto)
   --port <number>           WebSocket port for studio backend (default: 3001)
   --config <path>           Path to config file
   --testPathPattern <regex> Filter test files by path pattern
@@ -53,6 +157,7 @@ Options:
   --verbose                 Show individual test results
   --silent                  Suppress output
   --no-color                Disable colored output
+  -u, --updateSnapshot      Update snapshot files
   --no-cache                Force re-upload place file (skip cache)
   --pollInterval <ms>       Open Cloud poll interval in ms (default: 500)
   --projects <path...>      DataModel paths to search for tests
@@ -118,6 +223,10 @@ function parseArgs(args) {
 			},
 			"testPathPattern": { type: "string" },
 			"timeout": { type: "string" },
+			"updateSnapshot": {
+				short: "u",
+				type: "boolean"
+			},
 			"verbose": { type: "boolean" },
 			"version": {
 				default: false,
@@ -153,6 +262,7 @@ function parseArgs(args) {
 		testNamePattern: values.testNamePattern,
 		testPathPattern: values.testPathPattern,
 		timeout,
+		updateSnapshot: values.updateSnapshot,
 		verbose: values.verbose,
 		version: values.version
 	};
@@ -175,6 +285,7 @@ function printError(err) {
 	else console.error("An unknown error occurred");
 }
 async function runInner(args) {
+	if (args[0] === "patch") return runPatch();
 	const cli = parseArgs(args);
 	if (cli.help === true) {
 		console.log(HELP_TEXT);
@@ -192,10 +303,7 @@ async function runInner(args) {
 	}
 	if (!config.silent && !config.compact && !config.json && discovery.files.length !== discovery.totalFiles) process.stderr.write(`Running ${discovery.files.length} of ${discovery.totalFiles} test files\n`);
 	const result = await execute({
-		backend: config.backend === "studio" ? createStudioBackend({
-			port: config.port,
-			timeout: config.timeout
-		}) : createOpenCloudBackend(),
+		backend: await resolveBackend(config),
 		config,
 		testFiles: discovery.files,
 		version
@@ -273,9 +381,19 @@ function mergeCliWithConfig(cli, config) {
 		testNamePattern: cli.testNamePattern ?? config.testNamePattern,
 		testPathPattern: cli.testPathPattern ?? config.testPathPattern,
 		timeout: cli.timeout ?? config.timeout,
+		updateSnapshot: cli.updateSnapshot ?? config.updateSnapshot,
 		verbose: cli.verbose ?? config.verbose
 	};
 }
+function runPatch() {
+	const result = patchGetDataModelService(process.cwd());
+	if (result.status === "already-patched") console.log(`Already patched: ${result.filePath}`);
+	else {
+		console.log(`Patched: ${result.filePath}`);
+		console.log("Rebuild your .rbxl to include the patch.");
+	}
+	return 0;
+}
 
 //#endregion
 export { main, parseArgs, run };

package/dist/{game-output-BKBGosEI.mjs → game-output-BDatGA9S.mjs}

@@ -1,14 +1,14 @@
 import * as path$1 from "node:path";
 import path from "node:path";
 import process from "node:process";
+import { WebSocketServer } from "ws";
+import { type } from "arktype";
 import * as fs from "node:fs";
 import { existsSync } from "node:fs";
-import { type } from "arktype";
 import { homedir, tmpdir } from "node:os";
 import * as crypto from "node:crypto";
 import { randomUUID } from "node:crypto";
 import buffer from "node:buffer";
-import { WebSocketServer } from "ws";
 import { createJiti } from "jiti";
 import color from "tinyrainbow";
 import hljs from "highlight.js/lib/core";
@@ -55,6 +55,7 @@ function parseJestOutput(output) {
 	if (trimmed.startsWith("{")) {
 		const parsed = JSON.parse(trimmed);
 		const luauTiming = extractLuauTiming(parsed);
+		const snapshotWrites = extractSnapshotWrites(parsed);
 		const unwrapped = unwrapResult(parsed);
 		if (unwrapped["kind"] === "ExecutionError") {
 			const errorMessage = extractExecutionError(unwrapped);
@@ -62,12 +63,14 @@ function parseJestOutput(output) {
 		}
 		if (unwrapped["results"] !== void 0 && typeof unwrapped["results"] === "object") return {
 			luauTiming,
-			result: validateJestResult(unwrapped["results"])
+			result: validateJestResult(unwrapped["results"]),
+			snapshotWrites
 		};
 		try {
 			return {
 				luauTiming,
-				result: validateJestResult(unwrapped)
+				result: validateJestResult(unwrapped),
+				snapshotWrites
 			};
 		} catch {}
 	}
@@ -95,6 +98,13 @@ function extractLuauTiming(parsed) {
 	for (const [key, value] of Object.entries(timing)) if (typeof value === "number") record[key] = value;
 	return Object.keys(record).length > 0 ? record : void 0;
 }
+function extractSnapshotWrites(parsed) {
+	const writes = parsed["_snapshotWrites"];
+	if (writes === void 0 || writes === null || typeof writes !== "object") return;
+	const record = {};
+	for (const [key, value] of Object.entries(writes)) if (typeof value === "string") record[key] = value;
+	return Object.keys(record).length > 0 ? record : void 0;
+}
 function isValidJson(text) {
 	try {
 		JSON.parse(text);
@@ -116,7 +126,7 @@ function validateJestResult(value) {
 
 //#endregion
 //#region src/test-runner.luau
-var test_runner_default = "local HttpService = game:GetService(\"HttpService\")\nlocal LogService = game:GetService(\"LogService\")\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\n\nlocal t0 = os.clock()\nlocal baseConfig = HttpService:JSONDecode([[__CONFIG_JSON__]])\nlocal t_configDecode = os.clock()\n\ntype Config = {\n	jestPath: string?,\n	projects: { string }?,\n	setupFiles: { string }?,\n	_timing: boolean?,\n}\n\nlocal function fail(err: string)\n	return {\n		success = false,\n		err = err,\n	}\nend\n\nlocal config = table.clone(baseConfig) :: Config\nlocal timingEnabled = config._timing\n\nlocal function findInstance(path: string, class: string?): Instance\n	local parts = string.split(path, \"/\")\n\n	local result, current: Instance? = pcall(function()\n		return game:FindService(parts[1])\n	end)\n	assert(result, `Failed to find service {parts[1]}: {current}`)\n\n	for i = 2, #parts do\n		assert(current, `Failed to find instance at {parts[i]}`)\n		current = current:FindFirstChild(parts[i])\n	end\n\n	assert(current, `Failed to find instance at path {path}: {current}`)\n\n	return current\nend\n\nlocal function getJest(): ModuleScript\n	local jestPath = config.jestPath\n	if jestPath then\n		local instance = findInstance(jestPath)\n		assert(instance, `Failed to find Jest instance at path ${jestPath}`)\n		assert(instance:IsA(\"ModuleScript\"), `Instance at path ${jestPath} is not a ModuleScript`)\n		return instance\n	end\n\n	local jestInstance = ReplicatedStorage:FindFirstChild(\"Jest\", true)\n	assert(jestInstance, \"Failed to find Jest instance in ReplicatedStorage\")\n	assert(\n		jestInstance:IsA(\"ModuleScript\"),\n		\"Jest instance in ReplicatedStorage is not a ModuleScript\"\n	)\n	return jestInstance\nend\n\nlocal t_findJest0 = os.clock()\nlocal findSuccess, findValue = pcall(getJest)\nlocal t_findJest = os.clock()\n\nif not findSuccess then\n	local logSuccess, logHistory = pcall(function()\n		return HttpService:JSONEncode(LogService:GetLogHistory())\n	end)\n\n	return HttpService:JSONEncode(fail(findValue :: any)), if logSuccess then logHistory else \"[]\"\nend\n\nlocal t_requireJest0 = os.clock()\nlocal Jest = (require :: any)(findValue)\nlocal t_requireJest = os.clock()\n\nlocal function runTests()\n	LogService:ClearOutput()\n\n	local t_resolveProjects0 = os.clock()\n	local projects = {}\n\n	assert(\n		config.projects and #config.projects > 0,\n		\"No projects configured. Set 'projects' in jest.config.ts or pass --projects.\"\n	)\n\n	for _, projectPath in config.projects do\n		table.insert(projects, findInstance(projectPath))\n	end\n\n	config.projects = {}\n	local t_resolveProjects = os.clock()\n\n	local t_resolveSetupFiles0 = os.clock()\n	if config.setupFiles and #config.setupFiles > 0 then\n		local resolved = {}\n\n		for _, setupPath in config.setupFiles do\n			table.insert(resolved, findInstance(setupPath))\n		end\n\n		config.setupFiles = resolved :: any\n	end\n	local t_resolveSetupFiles = os.clock()\n\n	config._timing = nil :: any\n\n	local t_jestRunCLI0 = os.clock()\n	local jestResult = Jest.runCLI(script, config, projects):expect()\n	local t_jestRunCLI = os.clock()\n\n	local result: { [string]: any } = {\n		success = true,\n		value = jestResult,\n	}\n\n	if timingEnabled then\n		result._timing = {\n			configDecode = t_configDecode - t0,\n			findJest = t_findJest - t_findJest0,\n			requireJest = t_requireJest - t_requireJest0,\n			resolveProjects = t_resolveProjects - t_resolveProjects0,\n			resolveSetupFiles = t_resolveSetupFiles - t_resolveSetupFiles0,\n			jestRunCLI = t_jestRunCLI - t_jestRunCLI0,\n		}\n	end\n\n	return result\nend\n\nlocal runSuccess, runValue = pcall(runTests)\n\nlocal jestResult\nif not runSuccess then\n	jestResult = HttpService:JSONEncode(fail(runValue :: any))\nelse\n	jestResult = HttpService:JSONEncode(runValue)\nend\n\nlocal logSuccess, logHistory = pcall(function()\n	return HttpService:JSONEncode(LogService:GetLogHistory())\nend)\n\nreturn jestResult, if logSuccess then logHistory else \"[]\"\n";
+var test_runner_default = "local HttpService = game:GetService(\"HttpService\")\nlocal LogService = game:GetService(\"LogService\")\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\n\nlocal t0 = os.clock()\nlocal baseConfig = HttpService:JSONDecode([[__CONFIG_JSON__]])\nlocal t_configDecode = os.clock()\n\ntype Config = {\n	jestPath: string?,\n	projects: { string }?,\n	setupFiles: { string }?,\n	_timing: boolean?,\n}\n\nlocal function fail(err: string)\n	return {\n		success = false,\n		err = err,\n	}\nend\n\nlocal config = table.clone(baseConfig) :: Config\nlocal timingEnabled = config._timing\n\nlocal function findInstance(path: string, class: string?): Instance\n	local parts = string.split(path, \"/\")\n\n	local result, current: Instance? = pcall(function()\n		return game:FindService(parts[1])\n	end)\n	assert(result, `Failed to find service {parts[1]}: {current}`)\n\n	for i = 2, #parts do\n		assert(current, `Failed to find instance at {parts[i]}`)\n		current = current:FindFirstChild(parts[i])\n	end\n\n	assert(current, `Failed to find instance at path {path}: {current}`)\n\n	return current\nend\n\nlocal function getJest(): ModuleScript\n	local jestPath = config.jestPath\n	if jestPath then\n		local instance = findInstance(jestPath)\n		assert(instance, `Failed to find Jest instance at path ${jestPath}`)\n		assert(instance:IsA(\"ModuleScript\"), `Instance at path ${jestPath} is not a ModuleScript`)\n		return instance\n	end\n\n	local jestInstance = ReplicatedStorage:FindFirstChild(\"Jest\", true)\n	assert(jestInstance, \"Failed to find Jest instance in ReplicatedStorage\")\n	assert(\n		jestInstance:IsA(\"ModuleScript\"),\n		\"Jest instance in ReplicatedStorage is not a ModuleScript\"\n	)\n	return jestInstance\nend\n\nlocal t_findJest0 = os.clock()\nlocal findSuccess, findValue = pcall(getJest)\nlocal t_findJest = os.clock()\n\nif not findSuccess then\n	local logSuccess, logHistory = pcall(function()\n		return HttpService:JSONEncode(LogService:GetLogHistory())\n	end)\n\n	return HttpService:JSONEncode(fail(findValue :: any)), if logSuccess then logHistory else \"[]\"\nend\n\nLogService:ClearOutput()\n\n-- Snapshot support: patch jest-roblox-shared before requiring Jest\nlocal snapshotWrites: { [string]: string } = {}\n\nlocal function getInstancePath(instance: Instance): string\n	local parts = {} :: { string }\n	local curr: Instance? = instance\n	while curr and curr ~= game do\n		table.insert(parts, 1, curr.Name)\n		curr = curr.Parent\n	end\n\n	return table.concat(parts, \"/\")\nend\n\nlocal mockFileSystemService = {\n	WriteFile = function(self: any, path: string, contents: string)\n		-- Rewrite .snap.lua → .snap.luau\n		snapshotWrites[string.gsub(path, \"%.snap%.lua$\", \".snap.luau\")] = contents\n	end,\n	CreateDirectories = function(self: any, _path: string) end,\n	Exists = function(self: any, path: string): boolean\n		return snapshotWrites[string.gsub(path, \"%.snap%.lua$\", \".snap.luau\")] ~= nil\n	end,\n	Remove = function(self: any, path: string)\n		snapshotWrites[string.gsub(path, \"%.snap%.lua$\", \".snap.luau\")] = nil\n	end,\n	IsRegularFile = function(self: any, path: string): boolean\n		return snapshotWrites[string.gsub(path, \"%.snap%.lua$\", \".snap.luau\")] ~= nil\n	end,\n}\n\nlocal mockCoreScriptSyncService = {}\nfunction mockCoreScriptSyncService:GetScriptFilePath(script_: Instance): string\n	return getInstancePath(script_)\nend\n\n-- Use _G so the mock survives across Jest's separate module loader context.\n-- Requires getDataModelService.lua to be patched (jest-roblox patch).\n_G.__mockGetDataModelService = function(service: string): any\n	if service == \"FileSystemService\" then\n		return mockFileSystemService\n	elseif service == \"CoreScriptSyncService\" then\n		return mockCoreScriptSyncService\n	end\n\n	local success, result = pcall(function()\n		local svc = game:GetService(service)\n		local _ = svc.Name\n		return svc\n	end)\n\n	return if success then result else nil\nend\n\nlocal t_requireJest0 = os.clock()\nlocal Jest = (require :: any)(findValue)\nlocal t_requireJest = os.clock()\n\nlocal function runTests()\n	local t_resolveProjects0 = os.clock()\n	local projects = {}\n\n	assert(\n		config.projects and #config.projects > 0,\n		\"No projects configured. Set 'projects' in jest.config.ts or pass --projects.\"\n	)\n\n	for _, projectPath in config.projects do\n		table.insert(projects, findInstance(projectPath))\n	end\n\n	config.projects = {}\n	local t_resolveProjects = os.clock()\n\n	local t_resolveSetupFiles0 = os.clock()\n	if config.setupFiles and #config.setupFiles > 0 then\n		local resolved = {}\n\n		for _, setupPath in config.setupFiles do\n			table.insert(resolved, findInstance(setupPath))\n		end\n\n		config.setupFiles = resolved :: any\n	end\n	local t_resolveSetupFiles = os.clock()\n\n	config._timing = nil :: any\n\n	local t_jestRunCLI0 = os.clock()\n	local jestResult = Jest.runCLI(script, config, projects):expect()\n	local t_jestRunCLI = os.clock()\n\n	local result: { [string]: any } = {\n		success = true,\n		value = jestResult,\n	}\n\n	if timingEnabled then\n		result._timing = {\n			configDecode = t_configDecode - t0,\n			findJest = t_findJest - t_findJest0,\n			requireJest = t_requireJest - t_requireJest0,\n			resolveProjects = t_resolveProjects - t_resolveProjects0,\n			resolveSetupFiles = t_resolveSetupFiles - t_resolveSetupFiles0,\n			jestRunCLI = t_jestRunCLI - t_jestRunCLI0,\n		}\n	end\n\n	if next(snapshotWrites) then\n		result._snapshotWrites = snapshotWrites\n	end\n\n	return result\nend\n\nlocal runSuccess, runValue = pcall(runTests)\n\n_G.__mockGetDataModelService = nil\n\nlocal jestResult\nif not runSuccess then\n	jestResult = HttpService:JSONEncode(fail(runValue :: any))\nelse\n	jestResult = HttpService:JSONEncode(runValue)\nend\n\nlocal logSuccess, logHistory = pcall(function()\n	return HttpService:JSONEncode(LogService:GetLogHistory())\nend)\n\nreturn jestResult, if logSuccess then logHistory else \"[]\"\n";
 
 //#endregion
 //#region src/test-script.ts
@@ -265,6 +275,7 @@ var OpenCloudBackend = class {
 			gameOutput,
 			luauTiming: parsed.luauTiming,
 			result: parsed.result,
+			snapshotWrites: parsed.snapshotWrites,
 			timing: {
 				executionMs,
 				uploadCached,
@@ -381,6 +392,7 @@ var StudioBackend = class {
 			gameOutput: message.gameOutput,
 			luauTiming: parsed.luauTiming,
 			result: parsed.result,
+			snapshotWrites: parsed.snapshotWrites,
 			timing: { executionMs }
 		};
 	}
@@ -427,7 +439,7 @@ function createStudioBackend(options) {
 //#endregion
 //#region src/config/schema.ts
 const DEFAULT_CONFIG = {
-	backend: "open-cloud",
+	backend: "auto",
 	cache: true,
 	color: true,
 	compact: false,
@@ -910,7 +922,7 @@ function formatTestSummary(result, timing, styles) {
 	const testParts = [];
 	if (result.numPassedTests > 0) testParts.push(st.summary.passed(`${result.numPassedTests} passed`));
 	if (result.numFailedTests > 0) testParts.push(st.summary.failed(`${result.numFailedTests} failed`));
-	if (result.numPendingTests > 0) testParts.push(st.summary.pending(`${result.numPendingTests} pending`));
+	if (result.numPendingTests > 0) testParts.push(st.summary.pending(`${result.numPendingTests} skipped`));
 	const testTotalLabel = st.dim(`(${result.numTotalTests})`);
 	const testsLabel = labelStyle("      Tests");
 	lines.push(`${testsLabel}  ${testParts.join(" | ")} ${testTotalLabel}`);
@@ -932,8 +944,8 @@ function formatTestSummary(result, timing, styles) {
 }
 function parseErrorMessage(message) {
 	const lines = message.split("\n");
-	const expectedMatch = message.match(/Expected:\s*(.+)/);
-	const receivedMatch = message.match(/Received:\s*(.+)/);
+	const expectedMatch = message.match(/Expected\b.*?:\s*(.+)/);
+	const receivedMatch = message.match(/Received\b.*?:\s*(.+)/);
 	return {
 		expected: expectedMatch?.[1],
 		message: lines[0] ?? message,
@@ -1251,6 +1263,32 @@ async function writeJsonFile(result, filePath) {
 	fs.writeFileSync(absolutePath, formatJson(result), "utf8");
 }
 
+//#endregion
+//#region src/snapshot/path-resolver.ts
+function createSnapshotPathResolver(config) {
+	const mappings = buildMappings(config.rojoProject.tree, "");
+	return { resolve(virtualPath) {
+		const normalized = virtualPath.replaceAll("\\", "/");
+		for (const [prefix, basePath] of mappings) {
+			if (!normalized.startsWith(`${prefix}/`) && normalized !== prefix) continue;
+			let result = `${basePath}/${normalized.slice(prefix.length + 1)}`;
+			if (config.outDir !== void 0 && config.rootDir !== void 0 && result.startsWith(`${config.outDir}/`)) result = config.rootDir + result.slice(config.outDir.length);
+			return result;
+		}
+	} };
+}
+function buildMappings(tree, prefix) {
+	const mappings = [];
+	for (const [key, value] of Object.entries(tree)) {
+		if (key.startsWith("$") || typeof value !== "object") continue;
+		const dataModelPath = prefix ? `${prefix}/${key}` : key;
+		if (value.$path !== void 0) mappings.push([dataModelPath, value.$path]);
+		mappings.push(...buildMappings(value, dataModelPath));
+	}
+	mappings.sort((a, b) => b[0].length - a[0].length);
+	return mappings;
+}
+
 //#endregion
 //#region src/executor.ts
 const rojoProjectSchema = type({ tree: "object" });
@@ -1260,10 +1298,11 @@ const tsconfigSchema = type({ "compilerOptions?": {
 } });
 async function execute(options) {
 	const startTime = Date.now();
-	const { gameOutput, luauTiming, result, timing: backendTiming } = await options.backend.runTests({
+	const { gameOutput, luauTiming, result, snapshotWrites, timing: backendTiming } = await options.backend.runTests({
 		config: options.config,
 		testFiles: options.testFiles
 	});
+	if (snapshotWrites !== void 0) writeSnapshots(snapshotWrites, options.config);
 	const testsMs = calculateTestsMs(result.testResults);
 	const sourceMapper = options.config.sourceMap ? buildSourceMapper(options.config) : void 0;
 	const totalMs = Date.now() - startTime;
@@ -1336,6 +1375,50 @@ function printLuauTiming(timing) {
 	}
 	process.stderr.write(`[TIMING] total: ${String(total)}ms\n`);
 }
+function writeSnapshots(snapshotWrites, config) {
+	const rojoProjectPath = config.rojoProject ?? findRojoProject(config.rootDir);
+	if (rojoProjectPath === void 0 || !fs.existsSync(rojoProjectPath)) {
+		process.stderr.write("Warning: Cannot write snapshots - no rojo project found\n");
+		return;
+	}
+	try {
+		const rojoResult = rojoProjectSchema(JSON.parse(fs.readFileSync(rojoProjectPath, "utf-8")));
+		if (rojoResult instanceof type.errors) {
+			process.stderr.write("Warning: Cannot write snapshots - invalid rojo project\n");
+			return;
+		}
+		const tsconfigPath = path$1.join(config.rootDir, "tsconfig.json");
+		let outDirectory;
+		let rootDirectory;
+		if (fs.existsSync(tsconfigPath)) {
+			const tsconfigResult = tsconfigSchema(JSON.parse(fs.readFileSync(tsconfigPath, "utf-8")));
+			if (!(tsconfigResult instanceof type.errors)) {
+				outDirectory = tsconfigResult.compilerOptions?.outDir ?? "out";
+				rootDirectory = tsconfigResult.compilerOptions?.rootDir ?? "src";
+			}
+		}
+		const resolver = createSnapshotPathResolver({
+			outDir: outDirectory,
+			rojoProject: rojoResult,
+			rootDir: rootDirectory
+		});
+		let written = 0;
+		for (const [virtualPath, content] of Object.entries(snapshotWrites)) {
+			const fsPath = resolver.resolve(virtualPath);
+			if (fsPath === void 0) {
+				process.stderr.write(`Warning: Cannot resolve snapshot path: ${virtualPath}\n`);
+				continue;
+			}
+			const absolutePath = path$1.resolve(config.rootDir, fsPath);
+			fs.mkdirSync(path$1.dirname(absolutePath), { recursive: true });
+			fs.writeFileSync(absolutePath, content);
+			written++;
+		}
+		if (written > 0) process.stderr.write(`Wrote ${String(written)} snapshot file${written === 1 ? "" : "s"}\n`);
+	} catch (err) {
+		process.stderr.write(`Warning: Failed to write snapshot files: ${String(err)}\n`);
+	}
+}
 
 //#endregion
 //#region src/utils/game-output.ts

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { a as Argv, i as ResolvedConfig, n as Config, r as DEFAULT_CONFIG, t as CliOptions } from "./schema-ryuVGD35.mjs";
-import buffer from "node:buffer";
+import { a as Argv, i as ResolvedConfig, n as Config, r as DEFAULT_CONFIG, t as CliOptions } from "./schema-CEsyg-FX.mjs";
 import { WebSocketServer } from "ws";
+import buffer from "node:buffer";
 
 //#region src/types/jest-result.d.ts
 interface JestResult {
@@ -29,6 +29,16 @@ interface TestFileResult {
 }
 type TestStatus = "failed" | "passed" | "pending" | "skipped";
 //#endregion
+//#region src/reporter/parser.d.ts
+interface ParseResult {
+  luauTiming?: Record<string, number>;
+  result: JestResult;
+  snapshotWrites?: SnapshotWrites;
+}
+type SnapshotWrites = Record<string, string>;
+declare function extractJsonFromOutput(output: string): string | undefined;
+declare function parseJestOutput(output: string): ParseResult;
+//#endregion
 //#region src/backends/interface.d.ts
 interface Backend {
   runTests(options: BackendOptions): Promise<BackendResult>;
@@ -41,6 +51,7 @@ interface BackendResult {
   gameOutput?: string;
   luauTiming?: Record<string, number>;
   result: JestResult;
+  snapshotWrites?: SnapshotWrites;
   timing: BackendTiming;
 }
 interface BackendTiming {
@@ -213,14 +224,6 @@ declare function formatTestSummary(result: JestResult, timing: TimingResult, sty
 declare function formatJson(result: JestResult): string;
 declare function writeJsonFile(result: JestResult, filePath: string): Promise<void>;
 //#endregion
-//#region src/reporter/parser.d.ts
-interface ParseResult {
-  luauTiming?: Record<string, number>;
-  result: JestResult;
-}
-declare function extractJsonFromOutput(output: string): string | undefined;
-declare function parseJestOutput(output: string): ParseResult;
-//#endregion
 //#region src/test-script.d.ts
 type JestArgv = Argv & {
   testMatch: Array<string>;

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { _ as buildJestArgv, a as formatJson, b as extractJsonFromOutput, c as formatResult, d as resolveConfig, f as DEFAULT_CONFIG, g as createOpenCloudBackend, h as OpenCloudBackend, i as execute, l as formatTestSummary, m as createStudioBackend, n as parseGameOutput, o as writeJsonFile, p as StudioBackend, r as writeGameOutput, s as formatFailure, t as formatGameOutputNotice, u as loadConfig, v as generateTestScript, x as parseJestOutput } from "./game-output-BKBGosEI.mjs";
+import { _ as buildJestArgv, a as formatJson, b as extractJsonFromOutput, c as formatResult, d as resolveConfig, f as DEFAULT_CONFIG, g as createOpenCloudBackend, h as OpenCloudBackend, i as execute, l as formatTestSummary, m as createStudioBackend, n as parseGameOutput, o as writeJsonFile, p as StudioBackend, r as writeGameOutput, s as formatFailure, t as formatGameOutputNotice, u as loadConfig, v as generateTestScript, x as parseJestOutput } from "./game-output-BDatGA9S.mjs";
 
 export { DEFAULT_CONFIG, OpenCloudBackend, StudioBackend, buildJestArgv, createOpenCloudBackend, createStudioBackend, execute, extractJsonFromOutput, formatFailure, formatGameOutputNotice, formatJson, formatResult, formatTestSummary, generateTestScript, loadConfig, parseGameOutput, parseJestOutput, resolveConfig, writeGameOutput, writeJsonFile };

package/dist/{schema-ryuVGD35.d.mts → schema-CEsyg-FX.d.mts}

@@ -758,7 +758,7 @@ type _Except<ObjectType, KeysType extends keyof ObjectType, Options extends Requ
 //#endregion
 //#region src/config/schema.d.ts
 interface Config extends Except<Argv, "rootDir" | "setupFiles" | "testPathPattern"> {
-  backend?: "open-cloud" | "studio";
+  backend?: Backend;
   cache?: boolean;
   compact?: boolean;
   compactMaxFailures?: number;
@@ -774,9 +774,10 @@ interface Config extends Except<Argv, "rootDir" | "setupFiles" | "testPathPatter
   sourceMap?: boolean;
   testPathPattern?: string;
   timeout?: number;
+  updateSnapshot?: boolean;
 }
 interface ResolvedConfig extends Config {
-  backend: "open-cloud" | "studio";
+  backend: "auto" | "open-cloud" | "studio";
   cache: boolean;
   color: boolean;
   compact: boolean;
@@ -795,9 +796,10 @@ interface ResolvedConfig extends Config {
   timeout: number;
   verbose: boolean;
 }
+type Backend = "auto" | "open-cloud" | "studio";
 declare const DEFAULT_CONFIG: ResolvedConfig;
 interface CliOptions {
-  backend?: "open-cloud" | "studio";
+  backend?: Backend;
   cache?: boolean;
   color?: boolean;
   compact?: boolean;
@@ -819,6 +821,7 @@ interface CliOptions {
   testNamePattern?: string;
   testPathPattern?: string;
   timeout?: number;
+  updateSnapshot?: boolean;
   verbose?: boolean;
   version?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isentinel/jest-roblox",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Jest-compatible CLI for running roblox-ts tests via Roblox Open Cloud",
   "keywords": [
     "jest",

package/plugin/src/init.server.luau

@@ -9,7 +9,7 @@ if RunService:IsRunning() then
 end
 
 local WEBSOCKET_URL = "ws://localhost:3001"
-local RECONNECT_DELAY = 5
+local RECONNECT_DELAY = 0.1
 
 local IsDebug = ReplicatedStorage:GetAttribute("JEST_ROBLOX_DEBUG") == true
 ReplicatedStorage:GetAttributeChangedSignal("JEST_ROBLOX_DEBUG"):Connect(function(): ()

package/plugin/src/patch/CoreScriptSyncService.luau

@@ -0,0 +1,19 @@
+-- Mock CoreScriptSyncService: builds instance-to-path mapping
+-- Uses custom getInstancePath that stops at game (excludes DataModel name)
+local function getInstancePath(instance: Instance): string
+	local parts = {}
+	local curr: Instance? = instance
+	while curr and curr ~= game do
+		table.insert(parts, 1, (curr :: Instance).Name)
+		curr = (curr :: Instance).Parent
+	end
+	return table.concat(parts, "/")
+end
+
+local CoreScriptSyncService = {}
+
+function CoreScriptSyncService:GetScriptFilePath(script_: Instance): string
+	return getInstancePath(script_)
+end
+
+return CoreScriptSyncService

package/plugin/src/patch/FileSystemService.luau

@@ -0,0 +1,27 @@
+-- Mock FileSystemService: collects snapshot writes in-memory Uses
+-- _G.__snapshotWrites so all module load contexts (standard Luau + Jest
+-- runtime) share the same table. The test-runner creates this before patching.
+local snapshotWrites: { [string]: string } = _G.__snapshotWrites or {}
+
+local FileSystemService = {}
+
+function FileSystemService:WriteFile(path: string, contents: string)
+	-- Rewrite .snap.lua -> .snap.luau for Rojo compatibility
+	snapshotWrites[string.gsub(path, "%.snap%.lua$", ".snap.luau")] = contents
+end
+
+function FileSystemService:CreateDirectories(_path: string) end
+
+function FileSystemService:Exists(path: string): boolean
+	return snapshotWrites[string.gsub(path, "%.snap%.lua$", ".snap.luau")] ~= nil
+end
+
+function FileSystemService:Remove(path: string)
+	snapshotWrites[string.gsub(path, "%.snap%.lua$", ".snap.luau")] = nil
+end
+
+function FileSystemService:IsRegularFile(path: string): boolean
+	return snapshotWrites[string.gsub(path, "%.snap%.lua$", ".snap.luau")] ~= nil
+end
+
+return FileSystemService

package/plugin/src/patch/getDataModelService.luau

@@ -0,0 +1,19 @@
+-- Patched getDataModelService: returns mock services for snapshot support
+local CoreScriptSyncService = require(script.Parent.CoreScriptSyncService)
+local FileSystemService = require(script.Parent.FileSystemService)
+
+return function(service: string)
+	if service == "FileSystemService" then
+		return FileSystemService
+	elseif service == "CoreScriptSyncService" then
+		return CoreScriptSyncService
+	end
+
+	local success, result = pcall(function()
+		local svc = game:GetService(service)
+		local _ = svc.Name
+		return svc
+	end)
+
+	return success and result or nil
+end

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

@@ -30,6 +30,19 @@ end
 local TestRunner = require(script.Parent["test-runner"])
 local jestOutput, gameOutput = TestRunner.runTestsAync(script, testArgs.config or {})
 
+-- Inject snapshot writes from shared global table into jestOutput
+local snapshotWrites = _G.__snapshotWrites
+if snapshotWrites and next(snapshotWrites) then
+	local ok, decoded = pcall(function()
+		return HttpService:JSONDecode(jestOutput)
+	end)
+
+	if ok and type(decoded) == "table" then
+		decoded._snapshotWrites = snapshotWrites
+		jestOutput = HttpService:JSONEncode(decoded)
+	end
+end
+
 StudioTestService:EndTest({
 	jestOutput = jestOutput,
 	gameOutput = gameOutput,

package/plugin/src/test-runner.luau

@@ -41,6 +41,66 @@ function module.getJest(config: { jestPath: string? }): ModuleScript
 	return jestInstance
 end
 
+-- Find RobloxShared relative to Jest module
+local function findRobloxShared(jestModule: ModuleScript): Instance?
+	local parent = jestModule.Parent
+	if parent then
+		local found = parent:FindFirstChild("RobloxShared")
+			or parent:FindFirstChild("jest-roblox-shared")
+		if found then
+			return found
+		end
+
+		if parent.Parent then
+			found = parent.Parent:FindFirstChild("RobloxShared")
+				or parent.Parent:FindFirstChild("jest-roblox-shared")
+			if found then
+				return found
+			end
+		end
+	end
+
+	return game:FindFirstChild("RobloxShared", true)
+end
+
+-- Replace a child ModuleScript inside RobloxShared with a patched clone
+local function replaceChild(parent: Instance, name: string, patchSource: ModuleScript)
+	local original = parent:FindFirstChild(name)
+	if original then
+		original:Destroy()
+	end
+
+	local clone = patchSource:Clone()
+	clone.Name = name
+	clone.Parent = parent
+end
+
+-- Patch RobloxShared by replacing ModuleScript children
+local function patchRobloxShared(jestModule: ModuleScript, patchFolder: Instance): boolean
+	local robloxShared = findRobloxShared(jestModule)
+	if not robloxShared then
+		warn("[jest-roblox-cli] Could not find RobloxShared; snapshot support disabled")
+		return false
+	end
+
+	local patchGetDataModelService = patchFolder:FindFirstChild("getDataModelService")
+	local patchFileSystemService = patchFolder:FindFirstChild("FileSystemService")
+	local patchCoreScriptSyncService = patchFolder:FindFirstChild("CoreScriptSyncService")
+
+	if not (patchGetDataModelService and patchFileSystemService and patchCoreScriptSyncService) then
+		warn("[jest-roblox-cli] Missing patch modules; snapshot support disabled")
+		return false
+	end
+
+	-- Replace children inside RobloxShared
+	replaceChild(robloxShared, "FileSystemService", patchFileSystemService :: ModuleScript)
+	replaceChild(robloxShared, "CoreScriptSyncService", patchCoreScriptSyncService :: ModuleScript)
+	replaceChild(robloxShared, "getDataModelService", patchGetDataModelService :: ModuleScript)
+
+	warn("[jest-roblox-cli] Patched RobloxShared at:", robloxShared:GetFullName())
+	return true
+end
+
 function module.runTestsAync(
 	callingScript: LuaSourceContainer,
 	config: {
@@ -66,6 +126,17 @@ function module.runTestsAync(
 			if logSuccess then logHistory else "[]"
 	end
 
+	-- Snapshot support: create shared table BEFORE patching so all module
+	-- load contexts (standard Luau + Jest runtime) reference the same table
+	_G.__snapshotWrites = {}
+
+	local t_patchSnapshot0 = os.clock()
+	local patchFolder = (callingScript :: any).Parent.patch
+	if patchFolder then
+		patchRobloxShared(findValue, patchFolder)
+	end
+	local t_patchSnapshot = os.clock()
+
 	local t_requireJest0 = os.clock()
 	local Jest = (require :: any)(findValue)
 	local t_requireJest = os.clock()
@@ -115,6 +186,7 @@ function module.runTestsAync(
 			result._timing = {
 				configDecode = 0,
 				findJest = t_findJest - t_findJest0,
+				patchSnapshot = t_patchSnapshot - t_patchSnapshot0,
 				requireJest = t_requireJest - t_requireJest0,
 				resolveProjects = t_resolveProjects - t_resolveProjects0,
 				resolveSetupFiles = t_resolveSetupFiles - t_resolveSetupFiles0,