Roblox UtilitiesDevlHub Roblox Documentation

Class

StudioTestService

NotCreatableServiceNotReplicated
Inherits
Instance › Object
Memory category
Instances

Service allowing plugins to automate and customize Test and Run mode testing.

StudioTestService allows plugins to automate and customize Test and Run mode testing. With StudioTestService, your plugins can launch tests that jump straight to a specific part of your game, or run complex code tests automatically.

You can use StudioTestService to start a server with multiple simulated clients, add players mid-session, pass arguments into running tests, end tests from the server, and trigger client disconnections, all without manually clicking through the Test tab in Studio.

These methods complement the existing playtest automation available through Studio's built-in MCP server. Where the MCP server's start_stop_play tool starts a single Play Client session, the StudioTestService methods are designed for scripted multi-client scenarios such as lobby, matchmaking, and join/leave flow testing.

A typical multiplayer test splits across three script contexts: the plugin that launches it, the server that drives it, and the clients that participate:

Plugin script:

Luau
local StudioTestService = game:GetService("StudioTestService")

local toolbar = plugin:CreateToolbar("STS Tests")
local button = toolbar:CreateButton("MyTest", "", "")

button.Click:Connect(function()
    button.Enabled = false
    local result = StudioTestService:ExecuteMultiplayerTestAsync(1, "MyArguments")
    assert(result == "Success!")
    print("Test finished successfully!")
    button.Enabled = true
end)

Server script:

Luau
local Players = game:GetService("Players")
local StudioTestService = game:GetService("StudioTestService")

assert(StudioTestService:GetTestArgs() == "MyArguments")

Players.PlayerRemoving:Connect(function(player)
    print(player.Name .. " left the experience")
    task.wait(3)
    StudioTestService:EndTest("Success!")
end)

Client script:

Luau
if not game:IsLoaded() then
    game.Loaded:Wait()
end

local StudioTestService = game:GetService("StudioTestService")
task.wait(3)
StudioTestService:LeaveTest()
Limitations#
  • ExecuteMultiplayerTestAsync can only be called from plugin scripts. It yields until the test ends, so wrap it in a coroutine if the calling plugin needs to remain responsive.
  • ExecuteMultiplayerTestAsync cannot be called from inside a running test.
  • ExecuteMultiplayerTestAsync supports up to 8 simulated clients per test session.
  • Only one multiplayer test session can run at a time per Studio instance.
  • AddPlayers and EndTest must be called from the server DataModel of a running test.
  • CanLeaveTest and LeaveTest must be called from a client DataModel.
  • GetTestArgs currently has a known issue when called from a client LocalScript.

Properties 1#

EditModeActivebooleanPlugin-facing. Indicates whether the session is the idle edit DataModel with no Studio test session running.Read: PluginSecurityWrite: PluginSecurityReadSafe

EditModeActive: boolean#

Read: PluginSecurityWrite: PluginSecurityReadSafe

Plugin-facing; requires plugin security and is readable only from plugins and the command bar. Indicates whether the session is the edit DataModel with no Studio test session currently running. Defaults to true.

In the edit DataModel, this is true while Studio is idle and becomes false during an in-Studio play or Team Test session, returning to true when that session stops. In the server and client DataModel of a running Test or Run session, it is false.

Methods 8#

AddPlayersAdds additional simulated clients to the running multiplayer test session.
CanLeaveTestReturns whether the calling client DataModel can disconnect from the test.
EndTestEnds the current Studio test session from the server DataModel.
ExecuteMultiplayerTestAsyncLaunches a multiplayer test session and yields until it completes.PluginSecurity securityYields
ExecutePlayModeAsyncStarts a solo Test session and yields until it ends.PluginSecurity securityYields
ExecuteRunModeAsyncStarts a Run test session and yields until it ends.PluginSecurity securityYields
GetTestArgsReturns the argument passed to the method that started the current test session.
LeaveTestDisconnects the calling client from the active multiplayer test.

AddPlayers(numPlayers: int): ()#

Adds numPlayers additional client DataModels to the running test session. Useful for simulating staggered joins, testing lobby-to-game transitions under load, or reproducing race conditions that only appear when clients connect at different times.

Must be called from the server DataModel of an active multiplayer test.

Errors if called outside of an active test, or if called from a client DataModel.

NameTypeDefaultDescription
numPlayersintThe number of additional client DataModels to add. Must be between 1 and 8.
Returns
  • ()

CanLeaveTest(): boolean#

Returns true if the calling client DataModel is allowed to disconnect from the test, and false otherwise. Check this before calling LeaveTest to avoid errors during session teardown or during states where disconnection is blocked.

Call from a client DataModel.

Returns
  • boolean — true if the client can leave, false otherwise.

EndTest(value: Variant): ()#

Ends the current Studio test session if called from the server DataModel, even if the test was not started by this service.

If the test was started by StudioTestService:ExecutePlayModeAsync() or StudioTestService:ExecuteRunModeAsync(), the value passed here is returned by that method.

This method returns immediately and ends the test session asynchronously. It errors if called from any DataModel other than that of the server during a running Studio test session.

NameTypeDefaultDescription
valueVariantValue returned to the calling StudioTestService:ExecutePlayModeAsync() or StudioTestService:ExecuteRunModeAsync() method.
Returns
  • ()

ExecuteMultiplayerTestAsync(numPlayers: int, args: Variant): Variant#

YieldsPluginSecurity security

Launches a multiplayer test session with one server and numPlayers client DataModels. Yields until the test completes and returns the value passed to EndTest on the server.

Supports up to 8 simulated clients per test session.

The optional args value is forwarded to scripts running inside the test session and can be read via GetTestArgs. It can be any Roblox-serializable value, for example a string, a Color3, or a table. Common uses include passing a test name, a timeout, or configuration flags.

Errors if a test is already running. Errors if numPlayers is less than 1 or exceeds 8.

NameTypeDefaultDescription
numPlayersintThe number of client DataModels to create. Must be between 1 and 8.
argsVariantAn optional Roblox-serializable value forwarded to scripts inside the test session.
Returns

ExecutePlayModeAsync(args: Variant): Variant#

YieldsPluginSecurity security

Starts a solo Test session and yields until that session ends.

The args parameter can be retrieved using StudioTestService:GetTestArgs(). Returns the value passed to StudioTestService:EndTest(), or nil if the test ended by other means.

This method errors if a test session is already running.

NameTypeDefaultDescription
argsVariantArgument passed to the test session, or nil.
Returns

ExecuteRunModeAsync(args: Variant): Variant#

YieldsPluginSecurity security

Starts a Run test session and yields until that session ends.

The args parameter can be retrieved using StudioTestService:GetTestArgs(). Returns the value passed to StudioTestService:EndTest(), or nil if the test ended by other means.

This method errors if a test session is already running.

NameTypeDefaultDescription
argsVariantArgument passed to the test session, or nil.
Returns

GetTestArgs(): Variant#

Returns the argument passed to StudioTestService:ExecutePlayModeAsync() or StudioTestService:ExecuteRunModeAsync() for the current test session, or nil if the session was not started by those methods.

GetTestArgs returns the value as-is, preserving its type. For example, if the plugin passed a Color3, GetTestArgs returns a Color3.

Note that if you call GetTestArgs a client LocalScript, it may fail. Server-side calls work as expected.

Returns
  • Variant — Arguments passed to the test, or nil.

LeaveTest(): ()#

Disconnects the calling client from the active multiplayer test. Useful for testing player leave and reconnection logic, cleanup-on-disconnect behavior, and leader reassignment in lobby systems.

Call from a client DataModel. Make sure to check CanLeaveTest() first.

Errors if the client cannot currently leave or if called from a server DataModel.

Returns
  • ()

Inherited members#

Inherited from Instance 58
Properties (10)

Archivable, archivable, Capabilities, IsInSandbox, Name, Parent, PredictionMode, RobloxLocked, Sandboxed, UniqueId

Methods (39)

AddTag, children, ClearAllChildren, Clone, clone, Destroy, destroy, FindFirstAncestor, FindFirstAncestorOfClass, FindFirstAncestorWhichIsA, FindFirstChild, findFirstChild, FindFirstChildOfClass, FindFirstChildWhichIsA, FindFirstDescendant, GetActor, GetAttribute, GetAttributeChangedSignal, GetAttributes, GetChildren, getChildren, GetDebugId, GetDescendants, GetFullName, GetStyled, GetStyledPropertyChangedSignal, GetTags, HasTag, IsAncestorOf, IsDescendantOf, isDescendantOf, IsPropertyModified, QueryDescendants, Remove, remove, RemoveTag, ResetPropertyToDefault, SetAttribute, WaitForChild

Events (9)

AncestryChanged, AttributeChanged, ChildAdded, childAdded, ChildRemoved, DescendantAdded, DescendantRemoving, Destroying, StyledPropertiesChanged

Inherited from Object 6
Properties (2)

ClassName, className

Methods (3)

GetPropertyChangedSignal, IsA, isA

Events (1)

Changed