> ## Documentation Index
> Fetch the complete documentation index at: https://rive.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Unit Testing

> Write and run unit tests for your helper functions using Test scripts.

Test scripts let you write unit tests for your helper functions (see [Blank Scripts](https://rive.app/docs/scripting/protocols/util-scripts.md)) and run them directly in the Rive editor.
Use them to verify math helpers, string utilities, or any other pure logic your scripts depend on.

Beyond validating your code, tests also serve as precise instructions for the [AI Agent](https://rive.app/docs/editor/ai-agent), helping it produce code that behaves exactly as you intend.

## Creating a Test Script

[Create a new script](https://rive.app/docs/scripting/creating-scripts.md) and select **Test** as the type.

### Anatomy of a Test Script

A Test script exposes a single `setup(test: Tester)` function. The `Tester` object gives you helpers to define and group tests:

* `test.case(name, fn)` – define a single test case.
* `test.group(name, fn)` – group related tests. Groups can be nested.
* `expect(value)` – create an expectation object to assert on a value.

Inside a case, the `expect` function is passed as an argument to your test callback.

### Example

```lua theme={null}
-- Load the script that you want to create tests for
local MyUtil = require('MyUtil')

function setup(test: Tester)
  local case = test.case
  local group = test.group

  -- Create a single case with multiple tests
  case('Addition', function(expect)
    local result = MyUtil.add(2, 3)
    expect(result).is(5)
    expect(result).greaterThanOrEqual(5)
  end)

  -- Organize your tests with groups
  group('Math', function()
    case('Subtraction', function(expect)
      local result = MyUtil.subtract(2, 3)
      expect(result).is(-1)
    end)

    case('Multiplication', function(expect)
      local result = MyUtil.multiply(2, 3)
      expect(result).greaterThanOrEqual(6)
    end)

    group('Trigonometry', function()

      case('Degrees to Radians', function(expect)
        local result = MyUtil.deg2rad(180)
        expect(result).is(math.pi)
      end)
    end)
  end)
end

```

> [!TIP]
>
> Tip: Use descriptive names for your groups and cases. They show up in the test results panel and make it easier to see what failed.

### Matchers (expectations)

The `expect` helper returns an object with matcher methods you can use in your tests, for example:

```lua theme={null}
expect(value).is(expected)
expect(value).greaterThan(number)
expect(value).greaterThanOrEqual(number)
expect(value).lessThan(number)
expect(value).lessThanOrEqual(number)
```

For a complete list of matchers and test utilities, see Test API Reference (TODO: link).

### Inverting matchers with never

You can invert any matcher by chaining .never before it.
This means: the test passes only if the matcher would normally fail.

```lua theme={null}
case('never examples', function(expect)
  -- This passes because 2 + 2 is NOT 3
  expect(2 + 2).never.is(3)

  -- This passes because 4 is NOT >= 6
  expect(4).never.greaterThanOrEqual(6)
end)
```

## Running tests

1. In the Assets panel, right-click your Test script.
2. Select Run Tests.

Test results are shown:

* Passing and failing cases are listed under the script in the Assets Panel
* Passing and failing cases are highlighted in the script editor

![Problems panel](https://mintcdn.com/rive/PNFYxEcCteEOymSI/images/scripting/debugging/test-results.png?fit=max\&auto=format\&n=PNFYxEcCteEOymSI\&q=85\&s=62b4b7ff66e47fd13c68d0867bb9bcbc)