Getting started

Install

Windows one-liner, in PowerShell:

irm https://github.com/PRMS-magnet/luau-run/releases/latest/download/install.ps1 | iex

The script installs Luau Run, adds it to your Path and runs luau-run setup, which downloads Lute. Terminals that were already open need to be opened again to access luau-run. Install lists what Luau Run needs and the other ways to install.

Create luau-run.toml

In your project’s folder:

luau-run init                                                          # asks up to three questions, then writes luau-run.toml
luau-run init --default-runtime lute --test-root tests --example-spec  # no questions, plus an example spec
luau-run init --dry-run                                                # shows the file and writes nothing

init reads the project and walks you through setting up Luau Run. Specs that require by Roblox instance path or use Roblox’s globals go to Roblox Studio, and the rest to Lute. When the two kinds sit in separate folders, such as tests/unit and tests/roblox, one kind becomes the default and the other kind’s folders get runtime rules.

It never overwrites an existing luau-run.toml. To reinitialize your project, you must delete luau-run.toml. luau-run --help lists the options of every command.

For a Lute project it writes:

# Luau Run settings for this project; luau-run doctor shows what each is set to

[test]
default-runtime = "lute"
roots = ["tests"]

For a Roblox place, it also names the Rojo project that builds the place. When that project mounts the test folders, specs run in your whole place:

[test.roblox-studio]
rojo-project = "default.project.json"
data-model = "edit"

If the project mounts none of the test folders, as in a fresh rojo init place, init offers to write a test.project.json that adds them. In that project, a relative require that leaves its test folder, such as require("../src/Thing") from tests, cannot resolve. init counts these and suggests requiring those modules by instance path.

Write your first test

tests\Example.spec.luau, the spec init --example-spec writes:

local JestGlobals = require("@jest/globals")
local describe = JestGlobals.describe
local expect = JestGlobals.expect
local it = JestGlobals.it

describe("arithmetic", function()
  it("adds", function()
    expect(1 + 1).toBe(2)
  end)

  it("compares tables", function()
    expect({ a = 1 }).toEqual({ a = 1 })
  end)
end)

Writing tests covers script tests and which files are tests.

Run it

From the project’s folder:

luau-run test

PASS  2 tests

Running tests covers workers, time limits and reading the report.

Run specs in Roblox Studio

The Studio lane runs Jest specs in a hidden Roblox Studio that Luau Run starts and ends. It needs Roblox Studio and Rojo. Roblox Studio lane says how to send specs there.

Other commands

luau-run doctor               # where each tool and setting came from, read-only
luau-run pin lute <version>   # records a Lute release Luau Run does not know in luau-run.toml
luau-run update               # updates Luau Run to the latest version
luau-run <name>               # runs a command the project declares
luau-run --help               # every command and option

When Luau Run refuses, it says why and what to do next. Refusals lists every code.