@quenty/studio-bridge 0.21.0 → 0.22.0

package/src/commands/playtest/run/playtest-runner.luau

@@ -0,0 +1,264 @@
+--!strict
+--[=[
+	Runs a `playtest run` script inside the playtest's server and ends the
+	playtest with the result, so running a script does not depend on Studio
+	loading user plugins into playtests.
+
+	The `run-playtest-script` action plants this source as a Script in the edit
+	DataModel, with the code as a ModuleScript named `Code` under it, and starts a
+	playtest. The playtest copies the edit DataModel, so the runner starts in its
+	server. It only acts in the playtest it was planted for: anywhere else, such
+	as a place saved while it was planted, it does nothing.
+
+	The result crosses back through `StudioTestService:EndTest` in the same shape
+	as an `execute` reply. Instances cannot cross DataModels, so values are
+	marshalled here. Output capture, tracebacks and the marshaller are copies of
+	execute.lua's, since the runner cannot require it.
+
+	@class PlaytestRunner
+]=]
+
+local MAX_DEPTH = 64
+local PLUGIN_PREFIX = "[StudioBridge]"
+-- Tracebacks name this module's frames the way its first line does
+local OWN_FRAME_PREFIX = string.match(debug.traceback(), "^([^\n]-):%d+")
+
+local PlaytestRunner = {}
+
+type LogEntry = {
+	level: string,
+	body: string,
+	timestamp: number,
+}
+
+local LOG_LEVELS: { [Enum.MessageType]: string } = {
+	[Enum.MessageType.MessageOutput] = "Print",
+	[Enum.MessageType.MessageInfo] = "Info",
+	[Enum.MessageType.MessageWarning] = "Warning",
+	[Enum.MessageType.MessageError] = "Error",
+}
+
+--[=[
+	Runs the `Code` module under `runner` and ends the playtest with the result,
+	when this playtest is the one `runner` was planted for.
+]=]
+function PlaytestRunner.runAsync(runner: Instance, studioTestService: any, players: Players)
+	local argsOk, testArgs = pcall(function()
+		return studioTestService:GetTestArgs()
+	end)
+	if not argsOk or type(testArgs) ~= "table" or testArgs.studioBridgeRunnerId ~= runner:GetAttribute("RunnerId") then
+		return
+	end
+
+	local hasEnded = false
+	local captured: { LogEntry } = {}
+	local function endTest(result: { [string]: any })
+		if hasEnded then
+			return
+		end
+		hasEnded = true
+		studioTestService:EndTest(result)
+	end
+
+	local timeoutSec = testArgs.studioBridgeTimeoutSec
+	if type(timeoutSec) == "number" then
+		task.delay(timeoutSec, function()
+			endTest({
+				success = false,
+				error = `Script timed out after {timeoutSec}s`,
+				code = "SCRIPT_TIMEOUT",
+				output = captured,
+			})
+		end)
+	end
+
+	-- The plugin path waits for the client to connect, so match it in play mode
+	if testArgs.studioBridgeWaitForPlayer and #players:GetPlayers() == 0 then
+		players.PlayerAdded:Wait()
+	end
+
+	local scriptArgs = if type(testArgs.studioBridgeScriptArgs) == "table" then testArgs.studioBridgeScriptArgs else {}
+	endTest(PlaytestRunner.run(runner:FindFirstChild("Code"), captured, scriptArgs))
+end
+
+--[=[
+	Runs a code module with `args`, collecting everything logged while it runs
+	into `captured`, and returns the result in the shape of an `execute` reply.
+]=]
+function PlaytestRunner.run(codeModule: Instance?, captured: { LogEntry }, args: { any }?): { [string]: any }
+	if not (codeModule and codeModule:IsA("ModuleScript")) then
+		return { success = false, error = "Runner has no Code module", code = "SCRIPT_LOAD_ERROR", output = captured }
+	end
+
+	local requireOk, fn = pcall(require, codeModule)
+	if not requireOk or type(fn) ~= "function" then
+		return {
+			success = false,
+			error = if requireOk then "Code module did not return a function" else tostring(fn),
+			code = "SCRIPT_LOAD_ERROR",
+			output = captured,
+		}
+	end
+
+	local logConnection = PlaytestRunner._captureOutput(captured)
+	local returned = table.pack(xpcall(fn, function(err)
+		return {
+			message = tostring(err),
+			traceback = PlaytestRunner._dropOwnFrames(debug.traceback(nil, 2)),
+		}
+	end, table.unpack(args or {})))
+
+	-- MessageOut can fire a frame late, after the code's last print
+	task.wait()
+	logConnection:Disconnect()
+
+	if not returned[1] then
+		return {
+			success = false,
+			error = returned[2].message,
+			traceback = returned[2].traceback,
+			code = "SCRIPT_RUNTIME_ERROR",
+			output = captured,
+		}
+	end
+
+	return {
+		success = true,
+		output = captured,
+		returnValues = PlaytestRunner._serializeReturnValues(returned),
+	}
+end
+
+--[[
+	Drops the frames of this module's own wrapper from a traceback, leaving only
+	the script's.
+]]
+function PlaytestRunner._dropOwnFrames(traceback: string): string
+	if not OWN_FRAME_PREFIX then
+		return traceback
+	end
+
+	local lines = {}
+	for _, line in string.split(traceback, "\n") do
+		if string.sub(line, 1, #OWN_FRAME_PREFIX + 1) ~= `{OWN_FRAME_PREFIX}:` then
+			table.insert(lines, line)
+		end
+	end
+	return table.concat(lines, "\n")
+end
+
+--[[
+	Collects every message logged until the connection is disconnected, other
+	than the plugin's own.
+]]
+function PlaytestRunner._captureOutput(captured: { LogEntry }): RBXScriptConnection
+	return game:GetService("LogService").MessageOut:Connect(function(message: string, messageType: Enum.MessageType)
+		if string.sub(message, 1, #PLUGIN_PREFIX) == PLUGIN_PREFIX then
+			return
+		end
+
+		table.insert(captured, {
+			level = LOG_LEVELS[messageType] or "Print",
+			body = message,
+			timestamp = os.clock(),
+		})
+	end)
+end
+
+--[[
+	Marshals what a script returned, in order, skipping the pcall status. A nil
+	becomes an explicit marker, since an array cannot hold a hole.
+]]
+function PlaytestRunner._serializeReturnValues(packed: { n: number, [number]: any }): { any }
+	local returnValues = {}
+	for index = 2, packed.n do
+		local serialized = PlaytestRunner._serializeValue(packed[index], 1, {})
+		if serialized == nil then
+			serialized = { type = "Nil" }
+		end
+		returnValues[index - 1] = serialized
+	end
+	return returnValues
+end
+
+--[[
+	Produces the SerializedReturnValue shapes declared in web-socket-protocol.ts.
+	Copied from execute.lua; keep the two in step.
+]]
+function PlaytestRunner._serializeValue(value: any, depth: number, seen: { [any]: boolean }): any
+	local valueType = typeof(value)
+
+	if valueType == "nil" or valueType == "string" or valueType == "boolean" then
+		return value
+	elseif valueType == "number" then
+		if value ~= value or value == math.huge or value == -math.huge then
+			return PlaytestRunner._unsupported("number", tostring(value))
+		end
+		return value
+	elseif valueType == "table" then
+		if depth > MAX_DEPTH then
+			return PlaytestRunner._unsupported("table", "<max depth exceeded>")
+		end
+		if seen[value] then
+			return PlaytestRunner._unsupported("table", "<cycle>")
+		end
+
+		seen[value] = true
+		local serialized = PlaytestRunner._serializeTable(value, depth, seen)
+		seen[value] = nil
+		return serialized
+	elseif valueType == "Vector3" then
+		return { type = "Vector3", value = { value.X, value.Y, value.Z } }
+	elseif valueType == "Vector2" then
+		return { type = "Vector2", value = { value.X, value.Y } }
+	elseif valueType == "CFrame" then
+		return { type = "CFrame", value = { value:GetComponents() } }
+	elseif valueType == "Color3" then
+		return { type = "Color3", value = { value.R, value.G, value.B } }
+	elseif valueType == "UDim2" then
+		return { type = "UDim2", value = { value.X.Scale, value.X.Offset, value.Y.Scale, value.Y.Offset } }
+	elseif valueType == "UDim" then
+		return { type = "UDim", value = { value.Scale, value.Offset } }
+	elseif valueType == "BrickColor" then
+		return { type = "BrickColor", name = value.Name, value = value.Number }
+	elseif valueType == "EnumItem" then
+		return { type = "EnumItem", enum = tostring(value.EnumType), name = value.Name, value = value.Value }
+	elseif valueType == "Instance" then
+		return { type = "Instance", className = value.ClassName, path = value:GetFullName() }
+	else
+		return PlaytestRunner._unsupported(valueType, tostring(value))
+	end
+end
+
+function PlaytestRunner._serializeTable(value: { [any]: any }, depth: number, seen: { [any]: boolean }): any
+	local count = 0
+	for _ in value do
+		count += 1
+	end
+
+	if count == #value then
+		local array = {}
+		for index = 1, count do
+			array[index] = PlaytestRunner._serializeValue(value[index], depth + 1, seen)
+		end
+		return array
+	end
+
+	local map: { [string]: any } = {}
+	for key, item in value do
+		map[if type(key) == "string" then key else tostring(key)] =
+			PlaytestRunner._serializeValue(item, depth + 1, seen)
+	end
+	return map
+end
+
+function PlaytestRunner._unsupported(typeName: string, text: string): { [string]: any }
+	return { type = "Unsupported", typeName = typeName, toString = text }
+end
+
+-- Planted as a Script it runs; in the test place it is a ModuleScript specs require
+if script:IsA("Script") then
+	task.spawn(PlaytestRunner.runAsync, script, game:GetService("StudioTestService"), game:GetService("Players"))
+end
+
+return PlaytestRunner

package/src/commands/playtest/run/playtest-runner.spec.lua

@@ -0,0 +1,71 @@
+--!strict
+--[[
+	@class playtest-runner.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local PlaytestRunner = require("playtest-runner")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function setup(testArgs: any)
+	local ended = {}
+	local runner = Instance.new("Folder")
+	runner:SetAttribute("RunnerId", "runner-1")
+
+	local studioTestService = {
+		GetTestArgs = function()
+			return testArgs
+		end,
+		EndTest = function(_self, value)
+			table.insert(ended, value)
+		end,
+	}
+
+	return {
+		runner = runner,
+		studioTestService = studioTestService,
+		ended = ended,
+		Destroy = function()
+			runner:Destroy()
+		end,
+	}
+end
+
+describe("PlaytestRunner.runAsync()", function()
+	it("should do nothing in a playtest it was not planted for", function()
+		local controller = setup({ studioBridgeRunnerId = "someone-else" })
+
+		PlaytestRunner.runAsync(controller.runner, controller.studioTestService, game:GetService("Players"))
+
+		expect(controller.ended).toEqual({})
+		controller:Destroy()
+	end)
+
+	it("should end the playtest with a load error when the code module is missing", function()
+		local controller = setup({ studioBridgeRunnerId = "runner-1" })
+
+		PlaytestRunner.runAsync(controller.runner, controller.studioTestService, game:GetService("Players"))
+
+		expect(#controller.ended).toEqual(1)
+		expect(controller.ended[1].success).toEqual(false)
+		expect(controller.ended[1].code).toEqual("SCRIPT_LOAD_ERROR")
+		controller:Destroy()
+	end)
+end)
+
+describe("PlaytestRunner._serializeReturnValues()", function()
+	it("should keep a nil in its position", function()
+		local packed = table.pack(true, 1, nil, Vector3.new(1, 2, 3))
+
+		expect(PlaytestRunner._serializeReturnValues(packed)).toEqual({
+			1,
+			{ type = "Nil" },
+			{ type = "Vector3", value = { 1, 2, 3 } },
+		})
+	end)
+end)

package/src/commands/playtest/run/run-playtest-script.lua

@@ -0,0 +1,139 @@
+--!strict
+--[=[
+	Action that runs a script in a fresh playtest's server and answers with
+	`scriptComplete`, the same reply as `execute`.
+
+	It does not need the playtest's own plugin sessions, so it works whether or
+	not Studio loads user plugins into playtests.
+
+	- Compiles the code first, so a syntax error fails here without starting a
+	  playtest.
+	- Plants the runner source the bridge sends as a Script in
+	  ServerScriptService, with the code as a ModuleScript named `Code` under it.
+	  The playtest copies the edit DataModel, so the runner starts in its server,
+	  runs the code and ends the playtest with the result.
+	- Removes the runner from the edit DataModel once the playtest ends.
+
+	Request: `{ type: "runPlaytestScript", payload: { mode: "play" | "run", script, runnerSource, timeoutSec, args? } }`
+	Response: `{ type: "scriptComplete", payload: { success, output, returnValues?, error?, code? } }`
+
+	@class RunPlaytestScriptAction
+]=]
+
+local RunPlaytestScriptAction = {}
+
+type SendMessage = (message: { [string]: any }) -> ()
+
+--[=[
+	Registers the `runPlaytestScript` handler. The reply waits for the playtest to
+	end, so it needs `sendMessage`.
+]=]
+function RunPlaytestScriptAction.register(router: any, sendMessage: SendMessage?)
+	router:setResponseType("runPlaytestScript", "scriptComplete")
+	router:register(
+		"runPlaytestScript",
+		function(payload: { [string]: any }, requestId: string, sessionId: string): { [string]: any }?
+			local mode = payload.mode
+			if mode ~= "play" and mode ~= "run" then
+				error(`Unknown playtest mode: {tostring(mode)}`)
+			end
+
+			local code = payload.script
+			local runnerSource = payload.runnerSource
+			local timeoutSec = payload.timeoutSec
+			if type(code) ~= "string" or type(runnerSource) ~= "string" or type(timeoutSec) ~= "number" then
+				error("Missing script, runnerSource or timeoutSec in runPlaytestScript request")
+			end
+
+			local compileErr = RunPlaytestScriptAction._getCompileError(router, code)
+			if compileErr then
+				return { success = false, error = compileErr, code = "SCRIPT_LOAD_ERROR", output = {} }
+			end
+
+			if not sendMessage then
+				error("Running a playtest script requires a sendMessage callback")
+			end
+
+			task.spawn(function()
+				local result = RunPlaytestScriptAction._runAsync(mode, code, runnerSource, timeoutSec, payload.args)
+				sendMessage({
+					type = "scriptComplete",
+					sessionId = sessionId,
+					requestId = if requestId ~= "" then requestId else nil,
+					payload = result,
+				})
+			end)
+
+			-- Replied through sendMessage, so the router must not reply as well
+			return nil
+		end
+	)
+end
+
+--[[
+	Returns why the code does not compile, or nil when it does. Routers from
+	older plugins have no Compile, and the edit DataModel always has loadstring.
+]]
+function RunPlaytestScriptAction._getCompileError(router: any, code: string): string?
+	local fn, compileErr
+	if type(router.Compile) == "function" then
+		fn, compileErr = router:Compile(code)
+	else
+		fn, compileErr = (loadstring :: any)(code)
+	end
+
+	if fn then
+		return nil
+	end
+	return if compileErr then tostring(compileErr) else "Failed to compile script"
+end
+
+function RunPlaytestScriptAction._runAsync(
+	mode: string,
+	code: string,
+	runnerSource: string,
+	timeoutSec: number,
+	args: { string }?
+): { [string]: any }
+	local runnerId = game:GetService("HttpService"):GenerateGUID(false)
+
+	local runner = Instance.new("Script")
+	runner.Name = "StudioBridgePlaytestRunner"
+	runner.Source = runnerSource
+	runner:SetAttribute("RunnerId", runnerId)
+
+	local codeModule = Instance.new("ModuleScript")
+	codeModule.Name = "Code"
+	-- Wrapping on the first line keeps a top-level `return` legal and line numbers unchanged
+	codeModule.Source = `return function(...) {code}\nend`
+	codeModule.Parent = runner
+
+	runner.Parent = game:GetService("ServerScriptService")
+
+	local ok, result = pcall(function()
+		local studioTestService = game:GetService("StudioTestService") :: any
+		local testArgs = {
+			studioBridgeRunnerId = runnerId,
+			studioBridgeTimeoutSec = timeoutSec,
+			studioBridgeScriptArgs = args,
+			studioBridgeWaitForPlayer = mode == "play",
+		}
+		if mode == "play" then
+			return studioTestService:ExecutePlayModeAsync(testArgs)
+		else
+			return studioTestService:ExecuteRunModeAsync(testArgs)
+		end
+	end)
+
+	runner:Destroy()
+
+	if not ok then
+		return { success = false, error = `Playtest failed to start: {result}`, output = {} }
+	end
+	if type(result) ~= "table" then
+		return { success = false, error = "Playtest was stopped before the script finished", output = {} }
+	end
+	return result
+end
+
+return RunPlaytestScriptAction

package/src/commands/playtest/run/run-playtest-script.spec.lua

@@ -0,0 +1,43 @@
+--!strict
+--[[
+	@class run-playtest-script.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local ActionRouter = require("ActionRouter")
+local Jest = require("Jest")
+local RunPlaytestScriptAction = require("run-playtest-script")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function dispatch(payload: { [string]: any }): any
+	local router = ActionRouter.new()
+	RunPlaytestScriptAction.register(router, function() end)
+
+	return router:Dispatch({
+		type = "runPlaytestScript",
+		sessionId = "session-1",
+		requestId = "req-1",
+		payload = payload,
+	})
+end
+
+describe("runPlaytestScript", function()
+	it("should fail a script that does not compile without starting a playtest", function()
+		local response = dispatch({ mode = "run", script = "local x = = 1", runnerSource = "", timeoutSec = 10 })
+
+		expect(response.type).toEqual("scriptComplete")
+		expect(response.payload.success).toEqual(false)
+		expect(response.payload.code).toEqual("SCRIPT_LOAD_ERROR")
+	end)
+
+	it("should reject an unknown mode", function()
+		local response = dispatch({ mode = "nope", script = "return 1", runnerSource = "", timeoutSec = 10 })
+
+		expect(response.type).toEqual("error")
+		expect(response.payload.message).toEqual(expect.stringContaining("Unknown playtest mode"))
+	end)
+end)