15 min read

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

TestService

Inherits from: Instance → Object

TestService is a service used by Roblox internally to run analytical tests on the engine.

Scripts that are executed inside of TestService (via TestService:RunAsync()) have access to special macros that directly invoke functions under the service. Macros are essentially substitutions for large blocks of code that shouldn't need to be rewritten each time you want to call them.

RBX_CHECK

This macro does tests with calls to the TestService:Check() function.

Macro	Test Condition
`RBX_CHECK(cond)`	`cond == true`
`RBX_CHECK_MESSAGE(cond, failMsg)`	`cond == true`
`RBX_CHECK_THROW(CODE)`	`pcall(function() CODE end) == false`
`RBX_CHECK_NO_THROW(CODE)`	`pcall(function() CODE end) == true`
`RBX_CHECK_EQUAL(a, b)`	`a == b`
`RBX_CHECK_NE(a, b)`	`a ~= b`
`RBX_CHECK_GE(a, b)`	`a >= b`
`RBX_CHECK_LE(a, b)`	`a <= b`
`RBX_CHECK_GT(a, b)`	`a > b`
`RBX_CHECK_LT(a, b)`	`a < b`

RBX_REQUIRE

This macro does tests with calls to the TestService:Require() function.

Macro	Test Condition
`RBX_REQUIRE(cond)`	`cond == true`
`RBX_REQUIRE_MESSAGE(cond, failMsg)`	`cond == true`
`RBX_REQUIRE_THROW(CODE)`	`pcall(function() CODE end) == false`
`RBX_REQUIRE_NO_THROW(CODE)`	`pcall(function() CODE end) == true`
`RBX_REQUIRE_EQUAL(a, b)`	`a == b`
`RBX_REQUIRE_NE(a, b)`	`a ~= b`
`RBX_REQUIRE_GE(a, b)`	`a >= b`
`RBX_REQUIRE_LE(a, b)`	`a <= b`
`RBX_REQUIRE_GT(a, b)`	`a > b`
`RBX_REQUIRE_LT(a, b)`	`a < b`

RBX_WARN

This macro does tests with calls to the TestService:Warn() function.

Macro	Test Condition
`RBX_WARN(cond)`	`cond == true`
`RBX_WARN_MESSAGE(cond, failMsg)`	`cond == true`
`RBX_WARN_THROW(CODE)`	`pcall(function() CODE end) == false`
`RBX_WARN_NO_THROW(CODE)`	`pcall(function() CODE end) == true`
`RBX_WARN_EQUAL(a, b)`	`a == b`
`RBX_WARN_NE(a, b)`	`a ~= b`
`RBX_WARN_GE(a, b)`	`a >= b`
`RBX_WARN_LE(a, b)`	`a <= b`
`RBX_WARN_GT(a, b)`	`a > b`
`RBX_WARN_LT(a, b)`	`a < b`

Additional Macros

Macro	Description
`RBX_ERROR(msg)`	Directly calls the `Class.TestService:Error()` function.
`RBX_FAIL(msg)`	Directly calls the `Class.TestService:Fail()` function.
`RBX_MESSAGE(msg)`	Directly calls the `Class.TestService:Message()` function.

Inherits from: Instance

Memory category: Instances

Tags: Service

Properties

Name	Type / Returns	Description
TestService.AutoRuns	boolean	If set to `true`, the game will start running when the service's `TestService:RunAsync()` method is called.
TestService.Description	string	A description of the test being executed.
TestService.ErrorCount	int	Measures how many errors have been recorded in the test session.
TestService.ExecuteWithStudioRun	boolean	When set to `true`, `TestService` will be executed when using the Run action in Roblox Studio.
TestService.Is30FpsThrottleEnabled	boolean	Sets whether or not the physics engine should be throttled to 30 FPS while the test is being ran.
TestService.IsPhysicsEnvironmentalThrottled	boolean	Sets whether or not the physics environment should be throttled while running this test.
TestService.IsSleepAllowed	boolean	Sets whether or not physics objects will be allowed to fall asleep while the test simulation is running.
TestService.NumberOfPlayers	int	The number of players expected in this test, if any.
TestService.SimulateSecondsLag	double	Sets a specific amount of additional latency experienced by players during the test session.
TestService.TestCount	int	Measures how many test calls have been recorded in the test session.
TestService.ThrottlePhysicsToRealtime	boolean	Sets whether the test should be throttled to simulate time according to real world time or as fast as possible.
TestService.Timeout	double	The maximum amount of time that tests are allowed to run for.
TestService.WarnCount	int	Measures how many warning calls have been recorded in the test session.

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

TestService.AutoRuns

If set to true, the game will start running when the service's TestService:RunAsync() method is called.

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

TestService.Description

A description of the test being executed.

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

TestService.ErrorCount

Measures how many errors have been recorded in the test session.

Field	Value
type	int
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Results
serialization	{"can_load":false,"can_save":true}

TestService.ExecuteWithStudioRun

When set to true, TestService will be executed when using the Run action in Roblox Studio.

Note that if the NumberOfPlayers property is set to a value above 0, running the game will open NumberOfPlayers + 1 Studio windows where one window is a server and the rest are players connected to that server. Try to keep this value within a rational range (1 to 8 players) or else your computer's CPU will get overloaded.

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

TestService.Is30FpsThrottleEnabled

Deprecated. This has been deprecated and directly renamed to ThrottlePhysicsToRealtime to better reflect its practical use.

Sets whether or not the physics engine should be throttled to 30 FPS while the test is being ran.

Field	Value
type	boolean
tags	["NotReplicated","Deprecated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Physics
serialization	{"can_load":true,"can_save":false}

TestService.IsPhysicsEnvironmentalThrottled

Sets whether or not the physics environment should be throttled while running this test.

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

TestService.IsSleepAllowed

Sets whether or not physics objects will be allowed to fall asleep while the test simulation is running.

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

TestService.NumberOfPlayers

The number of players expected in this test, if any.

Field	Value
type	int
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Settings
serialization	{"can_load":true,"can_save":true}

TestService.SimulateSecondsLag

Sets a specific amount of additional latency experienced by players during the test session.

Field	Value
type	double
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Settings
serialization	{"can_load":true,"can_save":true}

TestService.TestCount

Measures how many test calls have been recorded in the test session.

Field	Value
type	int
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Results
serialization	{"can_load":false,"can_save":true}

TestService.ThrottlePhysicsToRealtime

Sets whether the test should be throttled to simulate time according to real world time or as fast as possible.

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

TestService.Timeout

The maximum amount of time that tests are allowed to run for.

Field	Value
type	double
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Settings
serialization	{"can_load":true,"can_save":true}

TestService.WarnCount

Measures how many warning calls have been recorded in the test session.

Field	Value
type	int
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Results
serialization	{"can_load":false,"can_save":true}

Methods

Name	Type / Returns	Description
TestService:Check	()	Prints result of a condition to the output.
TestService:Checkpoint	()	Prints `Test checkpoint:` followed by a string to the output in blue text.
TestService:Done	()	Prints `Testing Done` to the output in blue text.
TestService:Error	()	Prints a red error message to the output, prefixed by `TestService:` .
TestService:Fail	()	Indicates a fatal error in a `TestService` run.
TestService:isFeatureEnabled	boolean	Returns whether the named feature identified by `name` is currently enabled.
TestService:Message	()	Prints `TestService:` followed by a string to the output in blue text.
TestService:Require	()	Prints whether a condition is true along with a description string.
TestService:Run	()	Runs scripts which are parented to `TestService`.
TestService:RunAsync	()	Runs scripts which are parented to `TestService`.
TestService:ScopeTime	Dictionary	Returns a dictionary of per-scope physics simulation timings for performance testing.
TestService:Warn	()	Prints if a condition is `true`, otherwise prints a warning.

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

TestService:Check

If condition is true, prints Check passed: followed by description to the output in blue text. Otherwise, prints Check failed: followed by description in red text.

Parameters

Name	Type	Default	Description
condition	boolean		The boolean expression to evaluate as the test assertion.
description	string		A label that identifies this check in the test output.
source	Instance	nil	The script instance that invoked the check, used for output attribution. Defaults to `nil`.
line	int	0	The line number in the source script where the check was called. Defaults to `0`.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

Code samples: View on Creator Hub (TestService-Check1).

TestService:Checkpoint

Prints Test checkpoint: followed by text to the output in blue text.

Parameters

Name	Type	Default	Description
text	string		The message to print alongside the checkpoint label.
source	Instance	nil	The script instance that invoked the checkpoint, used for output attribution. Defaults to `nil`.
line	int	0	The line number in the source script where the checkpoint was called. Defaults to `0`.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

Code samples: View on Creator Hub (TestService-Checkpoint1).

TestService:Done

Prints Testing Done to the output in blue text.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

Code samples: View on Creator Hub (TestService-Done1).

TestService:Error

Prints a red error message (description) to the output, prefixed by TestService: .

Parameters

Name	Type	Default	Description
description	string		The error message text to display.
source	Instance	nil	The script instance that raised the error, used for output attribution. Defaults to `nil`.
line	int	0	The line number in the source script where the error was raised. Defaults to `0`.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

Code samples: View on Creator Hub (TestService-Error1).

TestService:Fail

Indicates a fatal error in a TestService run. If this is called inside of a script running inside the service, it will initiate a breakpoint on the line that invoked the error.

Parameters

Name	Type	Default	Description
description	string		The failure message text to display.
source	Instance	nil	The script instance where the failure occurred, used for output attribution. Defaults to `nil`.
line	int	0	The line number in the source script where the failure was triggered. Defaults to `0`.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

TestService:isFeatureEnabled

Returns true if the feature identified by name is set to true, and false if it is set to any other value. Raises an error if name doesn't correspond to a defined feature.

Parameters

Name	Type	Default	Description
name	string		The name of the feature to query.

Returns

Type	Description
boolean	`true` if the named feature resolves to `true`, `false` otherwise.

Field	Value
security	None
thread safety	Unsafe

TestService:Message

Prints TestService: followed by text to the output in blue text.

Parameters

Name	Type	Default	Description
text	string		The message to print to the output.
source	Instance	nil	The script instance that sent the message, used for output attribution. Defaults to `nil`.
line	int	0	The line number in the source script where the message was sent. Defaults to `0`.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

Code samples: View on Creator Hub (TestService-Message1).

TestService:Require

If condition is true, prints Require passed: followed by description to the output in blue text. Otherwise prints Require failed. Test ended: followed by description in red text.

Parameters

Name	Type	Default	Description
condition	boolean		The boolean expression to evaluate as a required assertion.
description	string		A label that identifies this requirement in the test output.
source	Instance	nil	The script instance that invoked the requirement, used for output attribution. Defaults to `nil`.
line	int	0	The line number in the source script where the requirement was called. Defaults to `0`.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

Code samples: View on Creator Hub (TestService-Require1).

TestService:Run

Deprecated. Use RunAsync() instead.

Runs scripts which are parented to TestService.

Returns

Type	Description
()

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

TestService:RunAsync

Runs scripts which are parented to TestService.

Returns

Type	Description
()

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

TestService:ScopeTime

Returns a dictionary mapping physics simulation scopes to their measured step times, used for per-scope physics performance testing. Raises an error if the caller lacks permission.

Returns

Type	Description
Dictionary	A dictionary mapping physics simulation scopes to their measured step times.

Field	Value
security	None
thread safety	Unsafe

TestService:Warn

If condition is true, prints Warning passed: followed by description to the output in blue text. Otherwise prints Warning: followed by description to the output in yellow text.

Parameters

Name	Type	Default	Description
condition	boolean		The boolean expression to evaluate as the warning assertion.
description	string		A label that identifies this warning check in the test output.
source	Instance	nil	The script instance that invoked the warning, used for output attribution. Defaults to `nil`.
line	int	0	The line number in the source script where the warning was called. Defaults to `0`.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

Code samples: View on Creator Hub (TestService-Warn1).

Events

Name	Type / Returns	Description
TestService.ServerCollectConditionalResult		Fires when the server should collect a conditional test result.
TestService.ServerCollectResult		Fires when the server should collect a test result.

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.

TestService.ServerCollectConditionalResult

Fires when the server should collect a conditional test result.

Parameters

Name	Type	Description
condition	boolean	Whether the conditional test assertion passed or failed.
text	string	The description label associated with the test assertion.
script	Instance	The script instance that produced the result.
line	int	The line number in the script where the assertion was made.

Field	Value
security	None

TestService.ServerCollectResult

Fires when the server should collect a test result.

Parameters

Name	Type	Description
text	string	The result message text sent from the client.
script	Instance	The script instance that produced the result.
line	int	The line number in the script where the result was generated.

Field	Value
security	None