Unit Testing

Test scripts let you write unit tests for your helper functions (see Blank Scripts) 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, helping it produce code that behaves exactly as you intend.

Creating a Test Script

Create a new script 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

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

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.

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

In the Assets panel, right-click your Test script.
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

​Creating a Test Script

​Anatomy of a Test Script

​Example

​Matchers (expectations)

​Inverting matchers with never

​Running Tests

Creating a Test Script

Anatomy of a Test Script

Example

Matchers (expectations)

Inverting matchers with never

Running Tests