11 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

StudioTestService

Inherits from: Instance → Object

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:

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:

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:

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.

Inherits from: Instance

Memory category: Instances

Tags: NotCreatable, Service, NotReplicated

Properties

Name	Type / Returns	Description
StudioTestService.EditModeActive	boolean	Plugin-facing. Indicates whether the session is the idle edit `DataModel` with no Studio test session running.

Inherited from Instance

Name	Type / Returns	Description
Instance.Archivable	boolean	Determines if an `Instance` and its descendants can be cloned using `Instance:Clone()`, and can be saved/published.
Instance.archivable	boolean
Instance.Capabilities	SecurityCapabilities	The set of capabilities allowed to be used for scripts inside this container.
Instance.IsInSandbox	boolean	Indicates whether the instance is inside a sandboxed container.
Instance.Name	string	A non-unique identifier of the `Instance`.
Instance.Parent	Instance	Determines the hierarchical parent of the `Instance`.
Instance.PredictionMode	PredictionMode	Reflects the client-side prediction mode applied to the instance under server-authoritative physics.
Instance.RobloxLocked	boolean	A deprecated property that used to protect `CoreGui` objects.
Instance.Sandboxed	boolean	When enabled, the instance can only access abilities in its `Capabilities` list.
Instance.UniqueId	UniqueId	A unique identifier for the instance.

Inherited from Object

Name	Type / Returns	Description
Object.ClassName	string	A read-only string representing the class this `Object` belongs to.
Object.className	string

StudioTestService.EditModeActive

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.

Field	Value
type	boolean
security	{"read":"PluginSecurity","write":"PluginSecurity"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":true,"can_save":true}

Methods

Name	Type / Returns	Description
StudioTestService:AddPlayers	()	Adds additional simulated clients to the running multiplayer test session.
StudioTestService:CanLeaveTest	boolean	Returns whether the calling client DataModel can disconnect from the test.
StudioTestService:EndTest	()	Ends the current Studio test session from the server DataModel.
StudioTestService:ExecuteMultiplayerTestAsync	Variant	Launches a multiplayer test session and yields until it completes.
StudioTestService:ExecutePlayModeAsync	Variant	Starts a solo Test session and yields until it ends.
StudioTestService:ExecuteRunModeAsync	Variant	Starts a Run test session and yields until it ends.
StudioTestService:GetTestArgs	Variant	Returns the argument passed to the method that started the current test session.
StudioTestService:LeaveTest	()	Disconnects the calling client from the active multiplayer test.

Inherited from Instance

Name	Type / Returns	Description
Instance:AddTag	()	Applies a tag to the instance.
Instance:children	Instances	Returns an array of the object's children.
Instance:ClearAllChildren	()	This method destroys all of an instance's children.
Instance:Clone	Instance	Create a copy of an instance and all its descendants, ignoring instances that are not `Archivable`.
Instance:clone	Instance
Instance:Destroy	()	Sets the `Instance.Parent` property to `nil`, locks the `Instance.Parent` property, disconnects all connections, and calls `Destroy()` on all children.
Instance:destroy	()
Instance:FindFirstAncestor	Instance?	Returns the first ancestor of the `Instance` whose `Instance.Name` is equal to the given name.
Instance:FindFirstAncestorOfClass	Instance?	Returns the first ancestor of the `Instance` whose `Object.ClassName` is equal to the given className.
Instance:FindFirstAncestorWhichIsA	Instance?	Returns the first ancestor of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstChild	Instance?	Returns the first child of the `Instance` found with the given name.
Instance:findFirstChild	Instance
Instance:FindFirstChildOfClass	Instance?	Returns the first child of the `Instance` whose `ClassName` is equal to the given class name.
Instance:FindFirstChildWhichIsA	Instance?	Returns the first child of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstDescendant	Instance?	Returns the first descendant found with the given `Instance.Name`.
Instance:GetActor	Actor?	Returns the `Actor` associated with the Instance, if any.
Instance:GetAttribute	Variant	Returns the value which has been assigned to the given attribute name.
Instance:GetAttributeChangedSignal	RBXScriptSignal	Returns an event that fires when the given attribute changes.
Instance:GetAttributes	Dictionary	Returns a dictionary of the instance's attributes.
Instance:GetChildren	Instances	Returns an array containing all of the instance's children.
Instance:getChildren	Instances
Instance:GetDebugId	string	Returns a coded string of the debug ID used internally by Roblox.
Instance:GetDescendants	Instances	Returns an array containing all of the descendants of the instance.
Instance:GetFullName	string	Returns a string describing the instance's ancestry.
Instance:GetStyled	Variant	Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified.
Instance:GetStyledPropertyChangedSignal	RBXScriptSignal	Returns an event that fires when the given style property changes on the instance.
Instance:GetTags	Array	Gets an array of all tags applied to the instance.
Instance:HasTag	boolean	Check whether the instance has a given tag.
Instance:IsAncestorOf	boolean	Returns true if an `Instance` is an ancestor of the given descendant.
Instance:IsDescendantOf	boolean	Returns `true` if an `Instance` is a descendant of the given ancestor.
Instance:isDescendantOf	boolean
Instance:IsPropertyModified	boolean	Returns `true` if the value stored in the specified property is not equal to the code-instantiated default.
Instance:QueryDescendants	Instances	Returns an array containing all descendants of the instance that match the `selector` string.
Instance:Remove	()	Sets the object's `Parent` to `nil`, and does the same for all its descendants.
Instance:remove	()
Instance:RemoveTag	()	Removes a tag from the instance.
Instance:ResetPropertyToDefault	()	Resets a property to its default value.
Instance:SetAttribute	()	Sets the attribute with the given name to the given value.
Instance:WaitForChild	Instance	Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.

Inherited from Object

Name	Type / Returns	Description
Object:GetPropertyChangedSignal	RBXScriptSignal	Get an event that fires when a given property of the object changes.
Object:IsA	boolean	Returns true if an object's class matches or inherits from a given class.
Object:isA	boolean

StudioTestService:AddPlayers

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.

Parameters

Name	Type	Default	Description
numPlayers	int		The number of additional client DataModels to add. Must be between 1 and 8.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

Code samples: View on Creator Hub (StudioTestService-AddPlayers).

StudioTestService:CanLeaveTest

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

Type	Description
boolean	`true` if the client can leave, `false` otherwise.

Field	Value
security	None
thread safety	Unsafe

Code samples: View on Creator Hub (StudioTestService-CanLeaveTest).

StudioTestService:EndTest

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.

Parameters

Name	Type	Default	Description
value	Variant		Value returned to the calling `StudioTestService:ExecutePlayModeAsync()` or `StudioTestService:ExecuteRunModeAsync()` method.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

Code samples: View on Creator Hub (StudioTestService-EndTest).

StudioTestService:ExecuteMultiplayerTestAsync

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.

Parameters

Name	Type	Default	Description
numPlayers	int		The number of client DataModels to create. Must be between 1 and 8.
args	Variant		An optional Roblox-serializable value forwarded to scripts inside the test session.

Returns

Type	Description
Variant	The value passed to `StudioTestService:EndTest()`.

Field	Value
tags	["Yields"]
security	PluginSecurity
thread safety	Unsafe

Code samples: View on Creator Hub (StudioTestService-ExecuteMultiplayerTestAsync).

StudioTestService:ExecutePlayModeAsync

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.

Parameters

Name	Type	Default	Description
args	Variant		Argument passed to the test session, or `nil`.

Returns

Type	Description
Variant	Value passed from `StudioTestService:EndTest()`, or `nil`.

Field	Value
tags	["Yields"]
security	PluginSecurity
thread safety	Unsafe

StudioTestService:ExecuteRunModeAsync

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.

Parameters

Name	Type	Default	Description
args	Variant		Argument passed to the test session, or `nil`.

Returns

Type	Description
Variant	Value passed from `StudioTestService:EndTest()`, or `nil`.

Field	Value
tags	["Yields"]
security	PluginSecurity
thread safety	Unsafe

StudioTestService:GetTestArgs

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

Type	Description
Variant	Arguments passed to the test, or `nil`.

Field	Value
security	None
thread safety	Unsafe

Code samples: View on Creator Hub (StudioTestService-GetTestArgs).

StudioTestService: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

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

Events

Inherited from Instance

Name	Type / Returns	Description
Instance.AncestryChanged		Fires when the `Instance.Parent` property of this object or one of its ancestors is changed.
Instance.AttributeChanged		Fires whenever an attribute is changed on the `Instance`.
Instance.ChildAdded		Fires after an object is parented to this `Instance`.
Instance.childAdded
Instance.ChildRemoved		Fires after a child is removed from this `Instance`.
Instance.DescendantAdded		Fires after a descendant is added to the `Instance`.
Instance.DescendantRemoving		Fires immediately before a descendant of the `Instance` is removed.
Instance.Destroying		Fires immediately before (or is deferred until after) the instance is destroyed via `Instance:Destroy()`.
Instance.StyledPropertiesChanged		Fires whenever any style property is changed on the instance, including when a property is set to `nil`.

Inherited from Object

Name	Type / Returns	Description
Object.Changed		Fires immediately after a property of the object changes, with some limitations.