---
name: TestCase
last_updated: 2026-11-16T22:19:01Z
inherits:
  - Object
type: class
memory_category: Instances
tags:
  - NotCreatable
  - NotReplicated
summary: "A registered test, used inside its callback to check values."
---

# Class: TestCase

> A registered test, used inside its callback to check values.

## Description

A `TestCase` is a test registered with [TestService:RegisterTest()](/docs/reference/engine/classes/TestService.md) or
[TestSuite:RegisterTest()](/docs/reference/engine/classes/TestSuite.md). It's passed as the first argument to the
test's callback, where you call [Check()](/docs/reference/engine/classes/TestCase.md) and
[Require()](/docs/reference/engine/classes/TestCase.md) to compare the values your code produces
with the values you expect.

[TestService:ListTests()](/docs/reference/engine/classes/TestService.md) also returns `TestCase` objects, which you can
use to see each test's name, ID, tags, and timeout. A `TestCase` isn't an
[Instance](/docs/reference/engine/classes/Instance.md) and can't be parented.

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

TestService:RegisterTest("health starts full", function(test)
	local humanoid = Instance.new("Humanoid")
	test:Check(humanoid.Health, humanoid.MaxHealth)
	test:Check({ humanoid.Health, humanoid.MaxHealth }, { 100, 100 }, "default health")
end)
```

## Properties

### Property: TestCase.SuiteName

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

The name of the [TestSuite](/docs/reference/engine/classes/TestSuite.md) the test belongs to. Tests registered
with [TestService:RegisterTest()](/docs/reference/engine/classes/TestService.md) belong to the `Default` suite.

### Property: TestCase.TestId

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

A string that uniquely identifies the test among all registered tests.
Pass it as the `TestId` filter of [TestService:RunTestsAsync()](/docs/reference/engine/classes/TestService.md) to
run just this test, and use it to match the test with its
[TestResult](/docs/reference/engine/classes/TestResult.md).

The ID is built from the suite and test names, but its format isn't
guaranteed, so read it from this property rather than building it
yourself.

### Property: TestCase.TestName

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

The name passed to [TestService:RegisterTest()](/docs/reference/engine/classes/TestService.md) or
[TestSuite:RegisterTest()](/docs/reference/engine/classes/TestSuite.md) when the test was registered.

### Property: TestCase.TimeoutSec

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

How many seconds the test can run before it's reported as
[TestCaseStatus.TimedOut](/docs/reference/engine/enums/TestCaseStatus.md). It comes from the test's `TimeoutSec`
option, or from its suite's when the test doesn't set one, and defaults to
`30`. A value of `0` means the test has no per-test timeout.

## Methods

### Method: TestCase:Check

**Signature:** `TestCase:Check(actualValue: Variant, expectedValue: Variant, message: string): ()`

Compares `actualValue` with `expectedValue`. If they aren't equal, the
check records a [TestFailure](/docs/reference/engine/classes/TestFailure.md) and the test will fail, but the
callback keeps running, so one run can report several failed checks. To
stop the test at the first mismatch instead, use
[Require()](/docs/reference/engine/classes/TestCase.md).

Values are compared as follows:

- Values of different types are never equal, so `1` and `"1"` don't match.
- Numbers, strings, booleans, and [Vector3](/docs/reference/engine/datatypes/Vector3.md) values are compared
  by value. `NaN` is never equal to itself.
- Tables are compared by their contents: both tables must have the same
  keys, with values that are equal by these same rules. A table with an
  `__eq` metamethod is compared with `==` instead.
- [Instances](/docs/reference/engine/classes/Instance.md), functions, and threads are equal only if
  they're the same object.
- Other Roblox data types are compared with `==`.

`message` must be a string, a number, or `nil`. Checks only count while
the test is running. Checks made outside a run, such as from a thread the
test spawned that keeps going after the test finished, are ignored.

*Security: None · Thread Safety: Unsafe*

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `actualValue` | `Variant` |  | The value your code produced. |
| `expectedValue` | `Variant` |  | The value you expect. |
| `message` | `string` |  | Optional text that describes the check, shown when it fails. |

**Returns:** `()`

### Method: TestCase:GetTestTags

**Signature:** `TestCase:GetTestTags(): Array`

Returns the test's tags: the `Tags` it was registered with, plus the tags
of its [TestSuite](/docs/reference/engine/classes/TestSuite.md). The `IncludeTags` filter of
[TestService:RunTestsAsync()](/docs/reference/engine/classes/TestService.md) selects tests by these tags.

*Security: None · Thread Safety: Unsafe*

**Returns:** `Array` — An array of strings.

### Method: TestCase:Require

**Signature:** `TestCase:Require(actualValue: Variant, expectedValue: Variant, message: string): ()`

Compares `actualValue` with `expectedValue` using the same rules as
[Check()](/docs/reference/engine/classes/TestCase.md). If they aren't equal, it records a
[TestFailure](/docs/reference/engine/classes/TestFailure.md) and then throws an error that stops the test's
callback, so the rest of the test doesn't run. Use it for conditions the
rest of the test depends on, such as an object existing before you read
its properties.

The test is reported as failed with the recorded failure, and
[TestResult.UncaughtError](/docs/reference/engine/classes/TestResult.md) stays empty, since the error only stops
the test. Calling [Require()](/docs/reference/engine/classes/TestCase.md) inside
[LuaGlobals.pcall()](/docs/reference/engine/globals/LuaGlobals.md) catches the error, but the failure is still
recorded.

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

TestService:RegisterTest("shop has items", function(test)
	local shop = workspace:FindFirstChild("Shop")
	test:Require(shop ~= nil, true, "Workspace.Shop should exist")
	-- Only runs if the shop exists
	test:Check(#shop:GetChildren() > 0, true, "the shop should have items")
end)
```

*Security: None · Thread Safety: Unsafe*

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `actualValue` | `Variant` |  | The value your code produced. |
| `expectedValue` | `Variant` |  | The value you expect. |
| `message` | `string` |  | Optional text that describes the check, shown when it fails. |

**Returns:** `()`

## Inherited Members

### 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