---
name: TestService
last_updated: 2026-11-17T23:34:14Z
inherits:
  - Instance
  - Object
type: class
memory_category: Instances
tags:
  - Service
summary: "Registers and runs automated tests written in Luau while playtesting your experience."
---

# Class: TestService

> Registers and runs automated tests written in Luau while playtesting your
> experience.

## Description

`TestService` lets you write automated tests for your experience in Luau and
run them inside a live playtest, against the same scripts, physics, and
replication your players get. Register each test with a callback, run them
with [RunTestsAsync()](/docs/reference/engine/classes/TestService.md), and read the
returned [TestRunResult](/docs/reference/engine/classes/TestRunResult.md) to see what passed and what failed.

#### Where tests can run

The test APIs only work while `TestService.Enabled` is `true`. That's the case
while playtesting in Studio (**Play**, **Play Here**, or **Run**) and on a
Team Test server. [Enabled](/docs/reference/engine/classes/TestService.md) is `false` in Edit mode
(including the command bar while you're editing) and in live servers, and
there every method below throws an error. Tests can't run in a published
experience.

#### Writing a test

A test is a callback registered with
[RegisterTest()](/docs/reference/engine/classes/TestService.md). The callback receives the
test's [TestCase](/docs/reference/engine/classes/TestCase.md) and a [TestExecutionContext](/docs/reference/engine/classes/TestExecutionContext.md). Inside the
callback:

- [TestCase:Check()](/docs/reference/engine/classes/TestCase.md) compares a value to the one you expect. A mismatch
  is recorded as a failure, and the test keeps running.
- [TestCase:Require()](/docs/reference/engine/classes/TestCase.md) does the same comparison, but a mismatch also
  stops the test right away. Use it when the rest of the test can't continue,
  such as when a part it needs doesn't exist.
- [TestExecutionContext:Skip()](/docs/reference/engine/classes/TestExecutionContext.md) stops the test and records it as
  skipped, for example when it doesn't apply on the current device. If a check
  fails in the test, or the callback catches the skip and then throws a
  different error, the test fails instead.

A test passes if its callback returns with no failed checks. It fails if any
check failed or if the callback throws an error. A test can yield (for
example, with `task.wait()` or by waiting on an event), and it times out if it
runs longer than its [TestCase.TimeoutSec](/docs/reference/engine/classes/TestCase.md).

Group related tests with [RegisterSuite()](/docs/reference/engine/classes/TestService.md).
Tests in a suite inherit the suite's tags and timeout.

```lua
-- Script in ServerScriptService
local TestService = game:GetService("TestService")
local Workspace = game:GetService("Workspace")

if not TestService.Enabled then
	return -- Not playtesting
end

local doorSuite = TestService:RegisterSuite("Door", { Tags = { "gameplay" } })

doorSuite:RegisterTest("starts closed", function(test)
	local door = Workspace:FindFirstChild("Door")
	test:Require(door ~= nil, true, "Workspace.Door should exist")
	test:Check(door:GetAttribute("Open"), false)
end)

doorSuite:RegisterTest("opens when triggered", function(test)
	local door = Workspace.Door
	door:SetAttribute("Open", true)
	task.wait(0.5) -- Let the door animate
	test:Check(door.CanCollide, false, "an open door shouldn't block players")
end, { TimeoutSec = 5 })

local result = TestService:RunTestsAsync()
print(result.Summary) -- 2 passed, 0 failed, 0 skipped (2 total) in 512ms
```

#### Reading results

[RunTestsAsync()](/docs/reference/engine/classes/TestService.md) yields until every test it
selects has finished and returns a [TestRunResult](/docs/reference/engine/classes/TestRunResult.md). Check its
[TestRunResult.Status](/docs/reference/engine/classes/TestRunResult.md) against [TestRunStatus.Pass](/docs/reference/engine/enums/TestRunStatus.md) to decide if
the run passed, and call [TestRunResult:GetTests()](/docs/reference/engine/classes/TestRunResult.md) for a
[TestResult](/docs/reference/engine/classes/TestResult.md) per test. Each failed check is a [TestFailure](/docs/reference/engine/classes/TestFailure.md) with
the expected and actual values and the line it came from.

```lua
local result = TestService:RunTestsAsync({ Suite = "Door" })
if result.Status ~= Enum.TestRunStatus.Pass then
	for _, test in result:GetTests() do
		if test.Status == Enum.TestCaseStatus.Fail or test.Status == Enum.TestCaseStatus.TimedOut then
			warn(test.TestId, test.UncaughtError)
			for _, failure in test:GetFailures() do
				warn(`  line {failure.Line}: {failure.Message}`)
			end
		end
	end
end
```

[RunTestsAsync()](/docs/reference/engine/classes/TestService.md) also prints a summary of
the run to the **Output** window, followed by the [TestResult.TestId](/docs/reference/engine/classes/TestResult.md) of
each test that failed or timed out and why: its timeout, its uncaught error,
or its first failed check.

#### Test IDs

Each test has a [TestCase.TestId](/docs/reference/engine/classes/TestCase.md) that identifies it in results and
filters. It's built from the suite and test names, but treat it as an opaque
string: read it from [TestCase.TestId](/docs/reference/engine/classes/TestCase.md) or [TestResult.TestId](/docs/reference/engine/classes/TestResult.md)
rather than building it yourself.

## Properties

### Property: TestService.Enabled

```json
{
  "type": "boolean",
  "access": "ReadWrite",
  "security": {
    "read": "None",
    "write": "None"
  },
  "serialization": {
    "can_load": false,
    "can_save": false
  },
  "thread_safety": "Unsafe",
  "category": "Data"
}
```

Whether tests can be registered and run in the current session. This is
`true` while playtesting in Studio and on a Team Test server. It's `false`
in Edit mode (including the command bar while you're editing) and in live
servers.

While [Enabled](/docs/reference/engine/classes/TestService.md) is `false`,
[RegisterTest()](/docs/reference/engine/classes/TestService.md),
[RegisterSuite()](/docs/reference/engine/classes/TestService.md),
[RunTestsAsync()](/docs/reference/engine/classes/TestService.md),
[ListTests()](/docs/reference/engine/classes/TestService.md), and
[ResetTestRegistry()](/docs/reference/engine/classes/TestService.md) throw an
error, so check it before registering tests from a script that also runs
in live servers.

## Methods

### Method: TestService:ListTests

**Signature:** `TestService:ListTests(): Array`

Returns every registered test as a [TestCase](/docs/reference/engine/classes/TestCase.md), in the order the
tests were registered, including tests registered with
[TestSuite:RegisterTest()](/docs/reference/engine/classes/TestSuite.md). Use it to see what
[RunTestsAsync()](/docs/reference/engine/classes/TestService.md) can run, or to build a
test picker.

Throws an error if [Enabled](/docs/reference/engine/classes/TestService.md) is `false`.

*Security: None · Thread Safety: Unsafe*

**Returns:** `Array` — An array of [TestCase](/docs/reference/engine/classes/TestCase.md) objects in the order they were
registered.

### Method: TestService:RegisterSuite

**Signature:** `TestService:RegisterSuite(suiteName: string, options?: Dictionary): TestSuite`

Creates a suite: a named group of tests. Register tests in it with
[TestSuite:RegisterTest()](/docs/reference/engine/classes/TestSuite.md). Every test in the suite gets the suite's
tags and timeout, and you can select the whole suite with the `Suite`
filter of [RunTestsAsync()](/docs/reference/engine/classes/TestService.md).

The `options` table accepts:

- `Tags`: an array of strings. Tests in the suite get these tags in
  addition to their own.
- `TimeoutSec`: the default timeout for tests in the suite, from `0` to
  `86400` seconds. Defaults to `30`. A test can override it with its own
  `TimeoutSec`.

Calling [RegisterSuite()](/docs/reference/engine/classes/TestService.md) again with the
same name and no `options` (or an empty table) returns the existing suite,
so several scripts can add tests to one suite. If the second call passes
`options`, they must match the original (tags in any order), with any
field you leave out counting as its default, or the call throws an error.

Throws an error if [Enabled](/docs/reference/engine/classes/TestService.md) is `false`, if
`suiteName` is empty, if `Tags` isn't an array of strings, or if
`TimeoutSec` isn't a number from `0` to `86400`.

*Security: None · Thread Safety: Unsafe*

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `suiteName` | `string` |  | The name of the suite. Must not be empty. |
| `options` | `Dictionary` | `nil` | Optional settings for the suite: `Tags` (an array of strings) and `TimeoutSec` (a number of seconds). |

**Returns:** `TestSuite` — The [TestSuite](/docs/reference/engine/classes/TestSuite.md), which you use to register tests in it.

### Method: TestService:RegisterTest

**Signature:** `TestService:RegisterTest(testName: string, callback: Function, options?: Dictionary): TestCase`

Registers a test. The test doesn't run until you call
[RunTestsAsync()](/docs/reference/engine/classes/TestService.md). Tests registered with
this method belong to the `Default` suite; to put a test in your own
suite, use [TestSuite:RegisterTest()](/docs/reference/engine/classes/TestSuite.md).

When the test runs, `callback` is called with two arguments: the test's
[TestCase](/docs/reference/engine/classes/TestCase.md), which you use to check values, and a
[TestExecutionContext](/docs/reference/engine/classes/TestExecutionContext.md), which you use to skip the test. The callback
can yield.

The `options` table accepts:

- `Tags`: an array of strings that you can select tests by with the
  `IncludeTags` filter of
  [RunTestsAsync()](/docs/reference/engine/classes/TestService.md).
- `TimeoutSec`: how long the test can run, from `0` to `86400` seconds.
  Defaults to `30`. A test that runs longer is reported as
  [TestCaseStatus.TimedOut](/docs/reference/engine/enums/TestCaseStatus.md). If the test is yielding when its time
  runs out, it's stopped there, though threads it spawned keep running. If
  it's running without yielding, it's reported as timed out when it
  finishes. Set `TimeoutSec` to `0` for no per-test timeout. Either way,
  the place's script timeout still stops a test that runs too long without
  yielding, and that test is reported as timed out too.

Each test in a suite must have a unique name. Throws an error if
[Enabled](/docs/reference/engine/classes/TestService.md) is `false`, if `testName` is empty or
is already registered in the suite, if `Tags` isn't an array of strings,
or if `TimeoutSec` isn't a number from `0` to `86400`.

```lua
local TestService = game:GetService("TestService")

TestService:RegisterTest("spawn location exists", function(test)
	local spawnLocation = workspace:FindFirstChildWhichIsA("SpawnLocation")
	test:Check(spawnLocation ~= nil, true, "the place needs a SpawnLocation")
end, { Tags = { "smoke" } })
```

*Security: None · Thread Safety: Unsafe*

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `testName` | `string` |  | The name of the test. Must not be empty. |
| `callback` | `Function` |  | The function that runs the test. It receives the test's [TestCase](/docs/reference/engine/classes/TestCase.md) and a [TestExecutionContext](/docs/reference/engine/classes/TestExecutionContext.md). |
| `options` | `Dictionary` | `nil` | Optional settings for the test: `Tags` (an array of strings) and `TimeoutSec` (a number of seconds). |

**Returns:** `TestCase` — The `TestCase` for the registered test.

### Method: TestService:ResetTestRegistry

**Signature:** `TestService:ResetTestRegistry(): ()`

Removes every registered test and suite, so you can register a fresh set.
[TestCase](/docs/reference/engine/classes/TestCase.md) objects you already hold stay readable but no longer run.
A [TestSuite](/docs/reference/engine/classes/TestSuite.md) from before the reset still registers tests with its
old settings, but it's no longer the registered suite of that name. Call
[RegisterSuite()](/docs/reference/engine/classes/TestService.md) again to get the
current one.

Throws an error if [Enabled](/docs/reference/engine/classes/TestService.md) is `false` or if a
test run is in progress.

*Security: None · Thread Safety: Unsafe*

**Returns:** `()`

### Method: TestService:RunTestsAsync

**Signature:** `TestService:RunTestsAsync(filter?: Dictionary): TestRunResult`

Runs the registered tests one at a time, in the order they were
registered, and yields until the last one finishes. It returns a
[TestRunResult](/docs/reference/engine/classes/TestRunResult.md) and prints a summary of the run to the **Output**
window.

The optional `filter` table selects which tests run. A test runs only if
it matches every field you set:

- `TestId`: a string. Matches the test with exactly this
  [TestCase.TestId](/docs/reference/engine/classes/TestCase.md).
- `Suite`: a string. Matches tests in the suite with this name.
- `NamePattern`: a string. Matches tests whose name contains this text.
  The match is case-sensitive and is plain text, not a string pattern.
- `IncludeTags`: an array of strings. Matches tests that have at least one
  of these tags.

```lua
-- Run the "gameplay" tests in the Door suite
local result = TestService:RunTestsAsync({ Suite = "Door", IncludeTags = { "gameplay" } })
```

The run uses the tests that were registered when it started; tests
registered during the run wait for the next one. Only one run can be in
progress at a time.

Throws an error if [Enabled](/docs/reference/engine/classes/TestService.md) is `false`, if
another run is in progress, if `filter` has a field not listed above, if a
field has the wrong type, or if `TestId`, `Suite`, or `IncludeTags` is
empty.

*Yields · Security: None · Thread Safety: Unsafe*

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `filter` | `Dictionary` | `nil` | Optional fields that select which tests run: `TestId`, `Suite`, `NamePattern`, and `IncludeTags`. Omit it to run every registered test. |

**Returns:** `TestRunResult` — A [TestRunResult](/docs/reference/engine/classes/TestRunResult.md) with the outcome of the run and of each test.

## Events

### Event: TestService.TestRegistryChanged

**Signature:** `TestService.TestRegistryChanged()`

Fires after tests or suites are registered or after
[ResetTestRegistry()](/docs/reference/engine/classes/TestService.md) is called. It
fires at most once per [RunService.Heartbeat](/docs/reference/engine/classes/RunService.md), so a script that
registers many tests at once doesn't flood listeners. Call
[ListTests()](/docs/reference/engine/classes/TestService.md) to see the current tests.

```lua
local TestService = game:GetService("TestService")

TestService.TestRegistryChanged:Connect(function()
	for _, test in TestService:ListTests() do
		print(test.TestId, table.concat(test:GetTestTags(), ", "))
	end
end)
```

*Security: None*

## Inherited Members

### From [Instance](/docs/reference/engine/classes/Instance.md)

- **Property `Archivable`** (`boolean`): Determines if an Instance and its descendants can be cloned using
- **Property `archivable`** (`boolean`):  *(deprecated, hidden)*
- **Property `Capabilities`** (`SecurityCapabilities`): The set of capabilities allowed to be used for scripts inside this
- **Property `IsInSandbox`** (`boolean`): Indicates whether the instance is inside a sandboxed container.
- **Property `Name`** (`string`): A non-unique identifier of the Instance.
- **Property `Parent`** (`Instance`): Determines the hierarchical parent of the Instance.
- **Property `PredictionMode`** (`PredictionMode`): Reflects the client-side prediction mode applied to the instance under
- **Property `RobloxLocked`** (`boolean`): A deprecated property that used to protect CoreGui objects. *(hidden)*
- **Property `Sandboxed`** (`boolean`): When enabled, the instance can only access abilities in its `Capabilities`
- **Property `UniqueId`** (`UniqueId`): A unique identifier for the instance.
- **Method `AddTag(tag: string): ()`**: Applies a tag to the instance.
- **Method `children(): Instances`**: Returns an array of the object's children. *(deprecated)*
- **Method `ClearAllChildren(): ()`**: This method destroys all of an instance's children.
- **Method `Clone(): Instance`**: Create a copy of an instance and all its descendants, ignoring instances
- **Method `clone(): Instance`**:  *(deprecated)*
- **Method `Destroy(): ()`**: Sets the Instance.Parent property to `nil`, locks the
- **Method `destroy(): ()`**:  *(deprecated)*
- **Method `FindFirstAncestor(name: string): Instance?`**: Returns the first ancestor of the Instance whose
- **Method `FindFirstAncestorOfClass(className: string): Instance?`**: Returns the first ancestor of the Instance whose
- **Method `FindFirstAncestorWhichIsA(className: string): Instance?`**: Returns the first ancestor of the Instance for whom
- **Method `FindFirstChild(name: string, recursive?: boolean): Instance?`**: Returns the first child of the Instance found with the given name.
- **Method `findFirstChild(name: string, recursive?: boolean): Instance`**:  *(deprecated)*
- **Method `FindFirstChildOfClass(className: string): Instance?`**: Returns the first child of the Instance whose
- **Method `FindFirstChildWhichIsA(className: string, recursive?: boolean): Instance?`**: Returns the first child of the Instance for whom
- **Method `FindFirstDescendant(name: string): Instance?`**: Returns the first descendant found with the given Instance.Name.
- **Method `GetActor(): Actor?`**: Returns the Actor associated with the Instance, if any.
- **Method `GetAttribute(attribute: string): Variant`**: Returns the value which has been assigned to the given attribute name.
- **Method `GetAttributeChangedSignal(attribute: string): RBXScriptSignal`**: Returns an event that fires when the given attribute changes.
- **Method `GetAttributes(): Dictionary`**: Returns a dictionary of the instance's attributes.
- **Method `GetChildren(): Instances`**: Returns an array containing all of the instance's children.
- **Method `getChildren(): Instances`**:  *(deprecated)*
- **Method `GetDebugId(scopeLength?: int): string`**: Returns a coded string of the debug ID used internally by Roblox.
- **Method `GetDescendants(): Instances`**: Returns an array containing all of the descendants of the instance.
- **Method `GetFullName(): string`**: Returns a string describing the instance's ancestry.
- **Method `GetStyled(name: string, selector: string?): Variant`**: Returns the styled or explicitly modified value of the specified property,
- **Method `GetStyledPropertyChangedSignal(property: string): RBXScriptSignal`**: Returns an event that fires when the given style property changes on the
- **Method `GetTags(): Array`**: Gets an array of all tags applied to the instance.
- **Method `HasTag(tag: string): boolean`**: Check whether the instance has a given tag.
- **Method `IsAncestorOf(descendant: Instance): boolean`**: Returns true if an Instance is an ancestor of the given
- **Method `IsDescendantOf(ancestor: Instance): boolean`**: Returns `true` if an Instance is a descendant of the given
- **Method `isDescendantOf(ancestor: Instance): boolean`**:  *(deprecated)*
- **Method `IsPropertyModified(property: string): boolean`**: Returns `true` if the value stored in the specified property is not equal
- **Method `QueryDescendants(selector: string): Instances`**: Returns an array containing all descendants of the instance that match the
- **Method `Remove(): ()`**: Sets the object's `Parent` to `nil`, and does the same for all its *(deprecated)*
- **Method `remove(): ()`**:  *(deprecated)*
- **Method `RemoveTag(tag: string): ()`**: Removes a tag from the instance.
- **Method `ResetPropertyToDefault(property: string): ()`**: Resets a property to its default value.
- **Method `SetAttribute(attribute: string, value: Variant): ()`**: Sets the attribute with the given name to the given value.
- **Method `WaitForChild(childName: string, timeOut: double): Instance`**: Returns the child of the Instance with the given name. If the
- **Event `AncestryChanged`**: Fires when the Instance.Parent property of this object or one of
- **Event `AttributeChanged`**: Fires whenever an attribute is changed on the Instance.
- **Event `ChildAdded`**: Fires after an object is parented to this Instance.
- **Event `childAdded`**:  *(deprecated)*
- **Event `ChildRemoved`**: Fires after a child is removed from this Instance.
- **Event `DescendantAdded`**: Fires after a descendant is added to the Instance.
- **Event `DescendantRemoving`**: Fires immediately before a descendant of the Instance is removed.
- **Event `Destroying`**: Fires immediately before (or is deferred until after) the instance is
- **Event `StyledPropertiesChanged`**: Fires whenever any style property is changed on the instance, including

### From [Object](/docs/reference/engine/classes/Object.md)

- **Property `ClassName`** (`string`): A read-only string representing the class this Object belongs to.
- **Property `className`** (`string`):  *(deprecated)*
- **Method `GetPropertyChangedSignal(property: string): RBXScriptSignal`**: Get an event that fires when a given property of the object changes.
- **Method `IsA(className: string): boolean`**: Returns true if an object's class matches or inherits from a given class.
- **Method `isA(className: string): boolean`**:  *(deprecated)*
- **Event `Changed`**: Fires immediately after a property of the object changes, with some