Roblox UtilitiesDevlHub Roblox Documentation

Class

`TestService`

Service

Inherits: Instance › Object
Memory category: Instances

A service used by Roblox to run controlled tests of the engine. It is available for developers to use, to a limited degree.

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.

Properties 13#

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

`AutoRuns`: `boolean`#

ReadSafe

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

`Description`: `string`#

ReadSafe

A description of the test being executed.

`ErrorCount`: `int`#

ReadOnlyNotReplicatedReadSafe

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

`ExecuteWithStudioRun`: `boolean`#

ReadSafe

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.

`Is30FpsThrottleEnabled`: `boolean`#

NotReplicatedDeprecatedReadSafeDeprecated

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.

`IsPhysicsEnvironmentalThrottled`: `boolean`#

ReadSafe

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

`IsSleepAllowed`: `boolean`#

ReadSafe

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

`NumberOfPlayers`: `int`#

ReadSafe

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

`SimulateSecondsLag`: `double`#

ReadSafe

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

`TestCount`: `int`#

ReadOnlyNotReplicatedReadSafe

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

`ThrottlePhysicsToRealtime`: `boolean`#

ReadSafe

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

`Timeout`: `double`#

ReadSafe

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

`WarnCount`: `int`#

ReadOnlyNotReplicatedReadSafe

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

Methods 12#

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

`Check(condition: boolean, description: string, source: Instance = nil, line: int = 0)`: ()#

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.

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

()

`Checkpoint(text: string, source: Instance = nil, line: int = 0)`: ()#

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

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

()

`Done()`: ()#

Prints Testing Done to the output in blue text.

Returns

()

`Error(description: string, source: Instance = nil, line: int = 0)`: ()#

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

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

()

`Fail(description: string, source: Instance = nil, line: int = 0)`: ()#

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.

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

()

`isFeatureEnabled(name: string)`: boolean#

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.

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

Returns

boolean — true if the named feature resolves to true, false otherwise.

`Message(text: string, source: Instance = nil, line: int = 0)`: ()#

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

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

()

`Require(condition: boolean, description: string, source: Instance = nil, line: int = 0)`: ()#

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.

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

()

`Run()`: ()#

YieldsDeprecatedPluginSecurity securityDeprecated

Deprecated. Use RunAsync() instead.

Runs scripts which are parented to TestService.

Returns

()

`RunAsync()`: ()#

YieldsPluginSecurity security

Runs scripts which are parented to TestService.

Returns

()

`ScopeTime()`: Dictionary#

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

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

`Warn(condition: boolean, description: string, source: Instance = nil, line: int = 0)`: ()#

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.

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

()

Events 2#

ServerCollectConditionalResult	Fires when the server should collect a conditional test result.
ServerCollectResult	Fires when the server should collect a test result.

`ServerCollectConditionalResult(condition: boolean, text: string, script: Instance, line: int)`#

Fires when the server should collect a conditional test result.

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.

`ServerCollectResult(text: string, script: Instance, line: int)`#

Fires when the server should collect a test result.

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.

Inherited members#

Inherited from Instance 58

Properties (10)

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

Events (9)

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

Inherited from Object 6

RBX_CHECK#

RBX_REQUIRE#

RBX_WARN#

Additional Macros#

Properties 13#

AutoRuns: boolean#

Description: string#

ErrorCount: int#

ExecuteWithStudioRun: boolean#

Is30FpsThrottleEnabled: boolean#

IsPhysicsEnvironmentalThrottled: boolean#

IsSleepAllowed: boolean#

NumberOfPlayers: int#

SimulateSecondsLag: double#

TestCount: int#

ThrottlePhysicsToRealtime: boolean#

Timeout: double#

WarnCount: int#

Methods 12#

Check(condition: boolean, description: string, source: Instance = nil, line: int = 0): ()#

Returns

Checkpoint(text: string, source: Instance = nil, line: int = 0): ()#

Returns

Done(): ()#

Returns

Error(description: string, source: Instance = nil, line: int = 0): ()#

Returns

Fail(description: string, source: Instance = nil, line: int = 0): ()#

Returns

isFeatureEnabled(name: string): boolean#

Returns

Message(text: string, source: Instance = nil, line: int = 0): ()#

Returns

Require(condition: boolean, description: string, source: Instance = nil, line: int = 0): ()#

Returns

Run(): ()#

Returns

RunAsync(): ()#

Returns

ScopeTime(): Dictionary#

Returns

Warn(condition: boolean, description: string, source: Instance = nil, line: int = 0): ()#

Returns

Events 2#

ServerCollectConditionalResult(condition: boolean, text: string, script: Instance, line: int)#

ServerCollectResult(text: string, script: Instance, line: int)#

Inherited members#

Properties (10)

Methods (39)

Events (9)

Properties (2)

Methods (3)

Events (1)

`AutoRuns`: `boolean`#

`Description`: `string`#

`ErrorCount`: `int`#

`ExecuteWithStudioRun`: `boolean`#

`Is30FpsThrottleEnabled`: `boolean`#

`IsPhysicsEnvironmentalThrottled`: `boolean`#

`IsSleepAllowed`: `boolean`#

`NumberOfPlayers`: `int`#

`SimulateSecondsLag`: `double`#

`TestCount`: `int`#

`ThrottlePhysicsToRealtime`: `boolean`#

`Timeout`: `double`#

`WarnCount`: `int`#

`Check(condition: boolean, description: string, source: Instance = nil, line: int = 0)`: ()#

`Checkpoint(text: string, source: Instance = nil, line: int = 0)`: ()#

`Done()`: ()#

`Error(description: string, source: Instance = nil, line: int = 0)`: ()#

`Fail(description: string, source: Instance = nil, line: int = 0)`: ()#

`isFeatureEnabled(name: string)`: boolean#

`Message(text: string, source: Instance = nil, line: int = 0)`: ()#

`Require(condition: boolean, description: string, source: Instance = nil, line: int = 0)`: ()#

`Run()`: ()#

`RunAsync()`: ()#

`ScopeTime()`: Dictionary#

`Warn(condition: boolean, description: string, source: Instance = nil, line: int = 0)`: ()#

`ServerCollectConditionalResult(condition: boolean, text: string, script: Instance, line: int)`#

`ServerCollectResult(text: string, script: Instance, line: int)`#