@quenty/studio-bridge 0.22.1 → 0.24.0

package/src/commands/console/exec/exec.ts

@@ -6,11 +6,16 @@
  */
 
 import * as fs from 'fs/promises';
+import * as path from 'path';
 import { OutputHelper } from '@quenty/cli-output-helpers';
 import { defineCommand } from '../../framework/define-command.js';
 import { arg } from '../../framework/arg-builder.js';
 import { resolveScriptContentAsync } from '../../../cli/resolve-script-content.js';
-import type { BridgeSession } from '../../../bridge/index.js';
+import type { BridgeConnection, BridgeSession } from '../../../bridge/index.js';
+import type { RunAs } from '../../../bridge/types.js';
+import { tryExecuteLuauAsync } from '../../../roblox-mcp/index.js';
+import { listStudioProcessesAsync } from '../../../process/studio-process-closer.js';
+import { resolveSessionPidsAsync } from '../../../process/studio-process-identity.js';
 import type { SerializedReturnValue } from '../../../server/web-socket-protocol.js';
 
 export interface ExecOptions {
@@ -18,6 +23,9 @@ export interface ExecOptions {
   timeout?: number;
   /** Passed to the script as `...`. */
   args?: string[];
+  /** Passed to the script as buffers in `...`, before `args`. */
+  inputs?: Buffer[];
+  runAs?: RunAs;
 }
 
 export interface ExecResult {
@@ -26,6 +34,7 @@ export interface ExecResult {
   error?: string;
   traceback?: string;
   returnValues?: SerializedReturnValue[];
+  ranAs?: RunAs;
   summary: string;
 }
 
@@ -46,8 +55,10 @@ export interface RunResult {
 interface ConsoleExecArgs {
   code?: string;
   file?: string;
-  timeout?: number;
+  scriptTimeout?: number;
   scriptArgs?: string[];
+  input?: string[];
+  runAs?: RunAs;
 }
 
 /**
@@ -55,13 +66,32 @@ interface ConsoleExecArgs {
  */
 export async function execHandlerAsync(
   session: BridgeSession,
-  options: ExecOptions
+  options: ExecOptions,
+  connection?: BridgeConnection
 ): Promise<ExecResult> {
-  const result = await session.execAsync(
-    options.scriptContent,
-    options.timeout,
-    options.args
-  );
+  if (options.runAs === 'mcp') {
+    return execThroughMcpAsync(session, options, connection);
+  }
+  const result = options.runAs
+    ? await session.execAsync(
+        options.scriptContent,
+        options.timeout,
+        options.args,
+        options.inputs,
+        options.runAs
+      )
+    : options.inputs?.length
+    ? await session.execAsync(
+        options.scriptContent,
+        options.timeout,
+        options.args,
+        options.inputs
+      )
+    : await session.execAsync(
+        options.scriptContent,
+        options.timeout,
+        options.args
+      );
 
   const output = (result.output ?? []).map((entry) =>
     typeof entry === 'string' ? entry : entry.body
@@ -73,12 +103,76 @@ export async function execHandlerAsync(
     error: result.error,
     traceback: result.traceback,
     returnValues: result.returnValues,
+    ...(result.ranAs ? { ranAs: result.ranAs } : {}),
     summary: result.success
       ? 'Script executed successfully'
       : `Script failed: ${result.error}`,
   };
 }
 
+export const INPUT_ARG_DESCRIPTION =
+  'File to send with the script, which receives it as a buffer in ... before any args. Repeat for more files';
+
+export async function readInputFilesAsync(
+  files: string[] | undefined
+): Promise<Buffer[]> {
+  return Promise.all(
+    (files ?? []).map(async (file) => {
+      try {
+        return await fs.readFile(path.resolve(file));
+      } catch {
+        throw new Error(`Input file not found: ${file}`);
+      }
+    })
+  );
+}
+
+async function execThroughMcpAsync(
+  session: BridgeSession,
+  options: ExecOptions,
+  connection?: BridgeConnection
+): Promise<ExecResult> {
+  if (options.args?.length || options.inputs?.length) {
+    throw new Error(
+      "--run-as mcp can't pass args or --input: Studio's MCP server only takes the code."
+    );
+  }
+  const processes = connection
+    ? await listStudioProcessesAsync().catch(() => [])
+    : [];
+  const sessionPids =
+    connection && processes.length > 0
+      ? await resolveSessionPidsAsync(connection, processes, [
+          session.info.instanceId,
+        ])
+      : undefined;
+  const result = await tryExecuteLuauAsync(options.scriptContent, {
+    target: session.info.instanceId,
+    context: session.info.context,
+    sessions: connection?.listSessions() ?? [session.info],
+    ...(sessionPids ? { sessionPids } : {}),
+    ...(processes.length > 0
+      ? { listWindowsAsync: async () => processes }
+      : {}),
+    ...(options.timeout !== undefined ? { timeoutMs: options.timeout } : {}),
+  });
+  return result.success
+    ? {
+        success: true,
+        output: [],
+        returnValues: [result.value],
+        ranAs: 'mcp',
+        summary: 'Script executed successfully',
+      }
+    : {
+        success: false,
+        output: [],
+        error: `Studio's MCP server: ${result.message}`,
+        ranAs: 'mcp',
+        summary: `Script failed: ${result.message}`,
+      };
+}
+
 /**
  * Read a Luau script file and execute it in a connected Studio session.
  */
@@ -130,6 +224,7 @@ export function formatExecText(result: {
   returnValues?: SerializedReturnValue[];
   error?: string;
   traceback?: string;
+  ranAs?: RunAs;
   summary: string;
 }): string {
   const lines = [...result.output];
@@ -139,6 +234,9 @@ export function formatExecText(result: {
   if (result.error) lines.push(result.error);
   if (result.traceback)
     lines.push(OutputHelper.formatDim(result.traceback.trimEnd()));
+  if (result.ranAs && result.ranAs !== 'plugin') {
+    lines.push(OutputHelper.formatDim(`(ran as ${result.ranAs})`));
+  }
   return lines.length > 0 ? lines.join('\n') : result.summary;
 }
 
@@ -159,10 +257,19 @@ export const execCommand = defineCommand<ConsoleExecArgs, ExecResult>({
       description: 'Path to a Luau script file to execute',
       alias: 'f',
     }),
-    timeout: arg.option({
-      description: 'Execution timeout in milliseconds',
+    scriptTimeout: arg.option({
+      description: 'Cancel the script after this many milliseconds',
       type: 'number',
     }),
+    input: arg.option({
+      description: INPUT_ARG_DESCRIPTION,
+      array: true,
+    }),
+    runAs: arg.option({
+      description:
+        "Where the code runs: plugin (our plugin, its own copy of modules), game (an ordinary script in a running playtest, so require returns the game's modules) or mcp (Studio's MCP sandbox). Default: plugin where there is one, else game",
+      choices: ['plugin', 'game', 'mcp'],
+    }),
     scriptArgs: arg.passthrough({
       description:
         'Arguments after --, passed to the script as ... (all strings)',
@@ -171,13 +278,20 @@ export const execCommand = defineCommand<ConsoleExecArgs, ExecResult>({
   cli: {
     format: formatExecText,
   },
-  handler: async (session, args) => {
+  handler: async (session, args, connection) => {
     const { scriptContent } = await resolveScriptContentAsync(args);
+    const inputs = await readInputFilesAsync(args.input);
 
-    return execHandlerAsync(session, {
-      scriptContent,
-      timeout: args.timeout,
-      args: args.scriptArgs,
-    });
+    return execHandlerAsync(
+      session,
+      {
+        scriptContent,
+        timeout: args.scriptTimeout,
+        args: args.scriptArgs,
+        inputs,
+        runAs: args.runAs,
+      },
+      connection
+    );
   },
 });

package/src/commands/console/exec/execute.lua

@@ -8,7 +8,8 @@
 	  `SCRIPT_RUNTIME_ERROR` with a `traceback` when it throws, and
 	  `SCRIPT_TIMEOUT` when it outlives `payload.timeoutMs`. A timed out script
 	  is cancelled, so the requests queued behind it still run.
-	- Passes `payload.args`, a list of strings, to the script as `...`.
+	- Passes `payload.inputs`, a list of base64 files, to the script as buffers
+	  in `...`, followed by `payload.args`, a list of strings.
 	- Runs concurrent requests one at a time, in arrival order.
 	- Returns everything printed while the script runs, read from LogService, so
 	  output from required modules and from threads the script starts comes back.
@@ -26,6 +27,18 @@
 
 local MAX_DEPTH = 64
 local CHUNK_NAME = "=exec"
+local GAME_RUNNER_NAME = "StudioBridgeRunAsGame"
+local GAME_RUNNER_HEADER =
+	'local __bridgeArgs = table.pack(script:WaitForChild("Args"):Invoke()) local __bridgeResult = table.pack(xpcall(function(...) '
+local GAME_RUNNER_FOOTER =
+	'\nend, function(err) return { message = tostring(err), traceback = debug.traceback(nil, 2) } end, table.unpack(__bridgeArgs, 1, __bridgeArgs.n))) local __bridgeOut = { n = __bridgeResult.n, ok = __bridgeResult[1] } for i = 2, __bridgeResult.n do __bridgeOut["v" .. (i - 1)] = __bridgeResult[i] end script:WaitForChild("Done"):Fire(__bridgeOut)'
+local NO_PLUGIN_MESSAGE =
+	"This session runs as game code: it is the bridge planted into a playtest because Studio's \"Load user plugins on playtest\" setting is off, so there is no plugin to run in. Turn the setting on, or use --run-as mcp, which runs any code here but cannot require the game's modules."
+local NOT_RUNNING_MESSAGE =
+	"--run-as game needs a running playtest. Start one with 'studio-bridge playtest start', then target --context server or client."
+
+local MIN_OUTPUT_WAIT_FRAMES = 3
+local MAX_OUTPUT_WAIT_FRAMES = 30
 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+")
@@ -177,15 +190,26 @@ function ExecuteAction._handleExecute(
 		return reply({ success = false, error = "Missing code in execute request", code = "SCRIPT_LOAD_ERROR" })
 	end
 
+	local canPlant = ExecuteAction._canPlantScripts()
+	if payload.runAs == "plugin" and not canPlant then
+		return reply({ success = false, error = NO_PLUGIN_MESSAGE, code = "SCRIPT_LOAD_ERROR", ranAs = "game" })
+	end
+	local asGame = payload.runAs == "game" and canPlant
+	if asGame and not game:GetService("RunService"):IsRunning() then
+		return reply({ success = false, error = NOT_RUNNING_MESSAGE, code = "SCRIPT_LOAD_ERROR" })
+	end
+	local ranAs = if asGame or not canPlant then "game" else "plugin"
+
 	local compileOk, fn, compileErr = pcall(compile, code, CHUNK_NAME)
 	if not compileOk then
-		return reply({ success = false, error = tostring(fn), code = "SCRIPT_LOAD_ERROR" })
+		return reply({ success = false, error = tostring(fn), code = "SCRIPT_LOAD_ERROR", ranAs = ranAs })
 	end
 	if not fn then
 		return reply({
 			success = false,
 			error = if compileErr then tostring(compileErr) else "Failed to compile script",
 			code = "SCRIPT_LOAD_ERROR",
+			ranAs = ranAs,
 		})
 	end
 
@@ -194,6 +218,29 @@ function ExecuteAction._handleExecute(
 		return reply({ success = false, error = "Script args must be a list", code = "SCRIPT_LOAD_ERROR" })
 	end
 
+	local inputs = payload.inputs or {}
+	if type(inputs) ~= "table" then
+		return reply({ success = false, error = "Script inputs must be a list", code = "SCRIPT_LOAD_ERROR" })
+	end
+
+	local scriptArgs = {}
+	for index, encoded in inputs do
+		local decodeOk, decoded = pcall(function()
+			return game:GetService("EncodingService"):Base64Decode(buffer.fromstring(encoded))
+		end)
+		if not decodeOk or type(encoded) ~= "string" then
+			return reply({
+				success = false,
+				error = `Script input {index} is not valid base64`,
+				code = "SCRIPT_LOAD_ERROR",
+			})
+		end
+		table.insert(scriptArgs, decoded)
+	end
+	for _, arg in args do
+		table.insert(scriptArgs, arg)
+	end
+
 	local timeoutMs = payload.timeoutMs
 	local timeoutSeconds = if type(timeoutMs) == "number" then timeoutMs / 1000 else nil
 	-- The caller's timeout started when it sent the request, not when its turn came
@@ -210,10 +257,14 @@ function ExecuteAction._handleExecute(
 
 	local captured: { LogEntry } = {}
 	local logConnection = ExecuteAction._captureOutput(captured)
-	local status, result = ExecuteAction._runAsync(fn, timeoutSeconds, args)
+	local status, result
+	if asGame then
+		status, result = ExecuteAction._runAsGameAsync(code, timeoutSeconds, scriptArgs)
+	else
+		status, result = ExecuteAction._runAsync(fn, timeoutSeconds, scriptArgs)
+	end
 
-	-- MessageOut can fire a frame late, after the script's last print
-	task.wait()
+	ExecuteAction._waitForOutputAsync(captured)
 	logConnection:Disconnect()
 
 	if status == "timeout" then
@@ -222,6 +273,7 @@ function ExecuteAction._handleExecute(
 			error = `Script timed out after {timeoutMs}ms and was cancelled`,
 			code = "SCRIPT_TIMEOUT",
 			output = captured,
+			ranAs = ranAs,
 		})
 	elseif status == "error" then
 		return reply({
@@ -230,6 +282,7 @@ function ExecuteAction._handleExecute(
 			traceback = result.traceback,
 			code = "SCRIPT_RUNTIME_ERROR",
 			output = captured,
+			ranAs = ranAs,
 		})
 	end
 
@@ -237,6 +290,7 @@ function ExecuteAction._handleExecute(
 		success = true,
 		output = captured,
 		returnValues = ExecuteAction._serializeReturnValues(result),
+		ranAs = ranAs,
 	})
 end
 
@@ -258,6 +312,23 @@ function ExecuteAction._dropOwnFrames(traceback: string): string
 	return table.concat(lines, "\n")
 end
 
+--[[
+	Waits for the script's last output to arrive. MessageOut fires a frame or
+	two after a print, more in a playtest's server, so this waits a few frames
+	and then for one without new output.
+]]
+function ExecuteAction._waitForOutputAsync(captured: { LogEntry })
+	local seen = #captured
+	local frames = 0
+	local grew
+	repeat
+		task.wait()
+		frames += 1
+		grew = #captured ~= seen
+		seen = #captured
+	until frames >= MAX_OUTPUT_WAIT_FRAMES or (frames >= MIN_OUTPUT_WAIT_FRAMES and not grew)
+end
+
 --[[
 	Collects every message logged until the connection is disconnected, other
 	than the plugin's own.
@@ -331,6 +402,77 @@ function ExecuteAction._runAsync(fn: (...any) -> ...any, timeoutSec: number?, ar
 	return final.status, final.result
 end
 
+--[[
+	Whether this thread may set a script's source: a plugin can, the bridge
+	planted into a playtest cannot.
+]]
+function ExecuteAction._canPlantScripts(): boolean
+	return (pcall(function()
+		local probe = Instance.new("Script")
+		probe.Source = ""
+		probe:Destroy()
+	end))
+end
+
+--[[
+	Runs `code` as an ordinary game Script (server) or LocalScript (client), so
+	`require` returns the modules the running game uses rather than the plugin's
+	own copies. Returns what `_runAsync` returns.
+]]
+function ExecuteAction._runAsGameAsync(code: string, timeoutSec: number?, args: { any }?): (string, any)
+	local RunService = game:GetService("RunService")
+	local isServer = RunService:IsServer()
+	local runner = Instance.new(if isServer then "Script" else "LocalScript")
+	runner.Name = GAME_RUNNER_NAME
+
+	local packedArgs = args or {}
+	local argsFunction = Instance.new("BindableFunction")
+	argsFunction.Name = "Args"
+	argsFunction.OnInvoke = function()
+		return table.unpack(packedArgs)
+	end
+	argsFunction.Parent = runner
+
+	local done = Instance.new("BindableEvent")
+	done.Name = "Done"
+	done.Parent = runner
+
+	local outcome: { [string]: any }? = nil
+	local connection = done.Event:Connect(function(result)
+		outcome = result
+	end)
+
+	runner.Source = GAME_RUNNER_HEADER .. code .. GAME_RUNNER_FOOTER
+	runner.Parent = if isServer
+		then game:GetService("ServerScriptService")
+		else (game:GetService("Players").LocalPlayer :: any):WaitForChild("PlayerScripts")
+
+	local deadline = if timeoutSec then os.clock() + timeoutSec else math.huge
+	while not outcome and os.clock() < deadline do
+		task.wait()
+	end
+	connection:Disconnect()
+	runner:Destroy()
+
+	if not outcome then
+		return "timeout", nil
+	end
+	local final = outcome :: { [string]: any }
+	if final.ok then
+		local packed = { n = final.n, true }
+		for index = 2, final.n do
+			packed[index] = final["v" .. (index - 1)]
+		end
+		return "ok", packed
+	end
+	local err = final.v1
+	return "error",
+		{
+			message = if type(err) == "table" then tostring(err.message) else tostring(err),
+			traceback = if type(err) == "table" then err.traceback else nil,
+		}
+end
+
 --[[
 	Marshals what a script returned, in order, skipping the pcall status. A nil
 	becomes an explicit marker: a JSON array cannot hold a hole, and dropping it

package/src/commands/console/exec/execute.spec.lua

@@ -53,7 +53,7 @@ describe("ExecuteAction.handleExecute()", function()
 	it("should report success with no return values", function()
 		local result = runScript("local _ = 1")
 
-		expect(result).toEqual({ success = true, output = {}, returnValues = {} })
+		expect(result).toEqual({ success = true, output = {}, returnValues = {}, ranAs = "plugin" })
 	end)
 
 	it("should capture print and warn output in order", function()
@@ -141,6 +141,26 @@ describe("ExecuteAction.handleExecute()", function()
 		expect(result.returnValues).toEqual({ "Player1", 3, 2 } :: { any })
 	end)
 
+	it("should pass inputs to the script as buffers before its args", function()
+		local result = ExecuteAction.handleExecute({
+			script = "local data, name = ... return typeof(data), buffer.tostring(data), name",
+			inputs = { "aGVsbG8=" },
+			args = { "Player1" },
+		}, "req-1", "session-1")
+
+		expect(result.returnValues).toEqual({ "buffer", "hello", "Player1" } :: { any })
+	end)
+
+	it("should reject an input that is not a string", function()
+		local result = ExecuteAction.handleExecute({
+			script = "return 1",
+			inputs = { 5 },
+		}, "req-1", "session-1")
+
+		expect(result.success).toEqual(false)
+		expect(result.error).toContain("Script input 1")
+	end)
+
 	it("should cancel a script that outlives its timeout", function()
 		local result = ExecuteAction.handleExecute(
 			{ script = "task.wait(5) print('too late')", timeoutMs = 50 },
@@ -252,7 +272,7 @@ describe("ExecuteAction.register()", function()
 				type = "scriptComplete",
 				sessionId = "session-1",
 				requestId = "req-1",
-				payload = { success = true, output = {}, returnValues = { 1 } },
+				payload = { success = true, output = {}, returnValues = { 1 }, ranAs = "plugin" },
 			},
 		})
 

package/src/commands/framework/action-loader.test.ts

@@ -118,10 +118,10 @@ describe('loadActionSourcesAsync', () => {
       'find-instances',
       'grep-scripts',
       'import-instances',
+      'playtest-players',
       'query-data-model',
       'query-logs',
       'query-state',
-      'run-playtest-script',
       'start-playtest',
     ]);
   });

package/src/commands/playtest/player/playtest-players.lua

@@ -0,0 +1,127 @@
+--!strict
+--[=[
+	Action that reads and changes the players of a running playtest.
+
+	StudioTestService only adds players from the server DataModel of a
+	multiplayer test, so `list`, `add` and `remove` target the server session.
+	`leave` targets a player's client session: it closes that player's Studio
+	process, which kicking from the server leaves open.
+
+	Request: `{ type: "playtestPlayers", payload: { op: "list" } }`
+	Request: `{ type: "playtestPlayers", payload: { op: "add", count, timeoutSec } }`
+	Request: `{ type: "playtestPlayers", payload: { op: "remove", kick: { name }, names: { name }, timeoutSec } }`
+	Request: `{ type: "playtestPlayers", payload: { op: "leave" } }`
+	Response: `{ type: "playtestPlayersResult", payload: { players?, remaining? } }`
+
+	- `add` answers once the players have joined, or with those that joined by
+	  the timeout.
+	- `remove` kicks the players in `kick`, then answers once every player in
+	  `names` has left, with `remaining` listing any still there at the timeout.
+
+	@class PlaytestPlayersAction
+]=]
+
+local Players = game:GetService("Players")
+
+local POLL_INTERVAL_SEC = 0.25
+
+local PlaytestPlayersAction = {}
+
+export type PlayerInfo = {
+	name: string,
+	userId: number,
+	displayName: string,
+}
+
+--[=[
+	Registers the `playtestPlayers` handler.
+]=]
+function PlaytestPlayersAction.register(router: any)
+	router:setResponseType("playtestPlayers", "playtestPlayersResult")
+	router:register("playtestPlayers", function(payload: { [string]: any }, _requestId: string, _sessionId: string)
+		local op = payload.op
+		if op == "list" then
+			return { players = PlaytestPlayersAction._list() }
+		elseif op == "add" then
+			return { players = PlaytestPlayersAction._addAsync(payload.count, payload.timeoutSec) }
+		elseif op == "remove" then
+			return { remaining = PlaytestPlayersAction._removeAsync(payload.kick, payload.names, payload.timeoutSec) }
+		elseif op == "leave" then
+			task.defer(function()
+				(game:GetService("StudioTestService") :: any):LeaveTest()
+			end)
+			return {}
+		end
+		error(`Unknown playtestPlayers op: {tostring(op)}`)
+	end)
+end
+
+function PlaytestPlayersAction._info(player: Player): PlayerInfo
+	return { name = player.Name, userId = player.UserId, displayName = player.DisplayName }
+end
+
+function PlaytestPlayersAction._list(): { PlayerInfo }
+	local players = {}
+	for _, player in Players:GetPlayers() do
+		table.insert(players, PlaytestPlayersAction._info(player))
+	end
+	return players
+end
+
+function PlaytestPlayersAction._addAsync(count: any, timeoutSec: any): { PlayerInfo }
+	if type(count) ~= "number" or count < 1 or type(timeoutSec) ~= "number" then
+		error("add needs a count of at least 1 and a timeoutSec")
+	end
+
+	local before: { [Player]: boolean } = {}
+	for _, player in Players:GetPlayers() do
+		before[player] = true
+	end
+
+	(game:GetService("StudioTestService") :: any):AddPlayers(count)
+
+	local deadline = os.clock() + timeoutSec
+	local added: { PlayerInfo }
+	repeat
+		task.wait(POLL_INTERVAL_SEC)
+		added = {}
+		for _, player in Players:GetPlayers() do
+			if not before[player] then
+				table.insert(added, PlaytestPlayersAction._info(player))
+			end
+		end
+	until #added >= count or os.clock() > deadline
+
+	return added
+end
+
+function PlaytestPlayersAction._removeAsync(kick: any, names: any, timeoutSec: any): { string }
+	if type(kick) ~= "table" or type(names) ~= "table" or type(timeoutSec) ~= "number" then
+		error("remove needs kick, names and timeoutSec")
+	end
+
+	for _, name in kick do
+		local player = Players:FindFirstChild(name)
+		if player and player:IsA("Player") then
+			player:Kick("Removed by studio-bridge")
+		end
+	end
+
+	local deadline = os.clock() + timeoutSec
+	local remaining: { string }
+	repeat
+		remaining = {}
+		for _, name in names do
+			if Players:FindFirstChild(name) then
+				table.insert(remaining, name)
+			end
+		end
+		if #remaining > 0 then
+			task.wait(POLL_INTERVAL_SEC)
+		end
+	until #remaining == 0 or os.clock() > deadline
+
+	return remaining
+end
+
+return PlaytestPlayersAction

package/src/commands/playtest/player/playtest-players.spec.lua

@@ -0,0 +1,48 @@
+--!strict
+--[[
+	@class playtest-players.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local ActionRouter = require("ActionRouter")
+local Jest = require("Jest")
+local PlaytestPlayersAction = require("playtest-players")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function dispatch(payload: { [string]: any })
+	local router = ActionRouter.new()
+	PlaytestPlayersAction.register(router)
+	return router:Dispatch({ type = "playtestPlayers", sessionId = "session-1", requestId = "r1", payload = payload })
+end
+
+describe("playtestPlayers", function()
+	it("should list the players", function()
+		local response = dispatch({ op = "list" })
+
+		expect(response.type).toEqual("playtestPlayersResult")
+		expect(#response.payload.players).toEqual(#game:GetService("Players"):GetPlayers())
+	end)
+
+	it("should answer remove at once with no player left to wait for", function()
+		local response = dispatch({ op = "remove", kick = {}, names = { "NoSuchPlayer" }, timeoutSec = 5 })
+
+		expect(response.payload.remaining).toEqual({})
+	end)
+
+	it("should reject an unknown op", function()
+		local response = dispatch({ op = "nope" })
+
+		expect(response.type).toEqual("error")
+		expect(response.payload.message).toContain("Unknown playtestPlayers op")
+	end)
+
+	it("should reject add without a count", function()
+		local response = dispatch({ op = "add", timeoutSec = 5 })
+
+		expect(response.type).toEqual("error")
+	end)
+end)