jess test · jess Docs

jess test [--shared] [--capability NAME]... <MODULES>...

Runs Luau test modules. Each is a file that returns a suite made with @jess/test; jess loads it with the whole API, runs the suite, and prints every case. The exit status is non-zero when any case failed or any module didn't run.

Argument / option	Does
`<MODULES>...`	The test modules, as filesystem paths, `.jsl` files. Each gets a fresh VM; one that isn't a `.jsl` file is reported as a module that didn't run.
`--shared`	One VM for every module, so they share the module cache and whatever state a module keeps. Faster for many small modules; isolation is the default because a test that depends on another module having run first is a bug.
`--capability NAME`	Grant the modules a capability they don't hold by default (repeatable), as `jess run` does: test modules hold the terminal and the input devices, and everything else, such as `filesystem.read` for a suite that reads files, is a flag away.

Plus the global options. Like jess run, a test module holds its terminal and the input devices and nothing else until a flag says otherwise.

-- numbers.jsl
local test = require '@jess/test'
local log = require '@jess/log'
local expect = test.expect
local suite = test.new()

suite.describe('numbers', function()
  suite.it('add', function()
    log.info('adding', { left = 1 })
    expect(1 + 1).toBe(2)
  end)

  suite.it('compare', function() expect({ 1 }).toEqual { 2 } end)
end)

return suite

jess test numbers.jsl

passed: 1
failed: 1
modules:
- input: numbers.jsl
  report:
    passed: 1
    failed: 1
    tests:
    - name: numbers / add
      passed: true
      error: null
      logs:
      - level: info
        target: jess
        message: adding
        fields:
          left: 1
    - name: numbers / compare
      passed: false
      error: |-
        expected { 1 } to equal { 2 }
        numbers.jsl:13
      logs: []
  error: null
  logs: []

A case's logs are what it wrote through @jess/log, captured instead of printed. A module that doesn't return a suite, or fails while loading, gets error set and report: null, counts as one failure, and doesn't stop the modules after it; what it logged while loading is in its logs.

--format json prints the same document on one line, for a script or a CI step to read.