Voxta docs

Script tests

Unit tests for scenario and character scripts: .spec scripts, an interaction's Test tab, running them, and reading the results in the Tests tab.

A script test checks what a script does without playing the scenario. You write it like a Jest test. The server runs it with the same script engine a chat uses. A chat never runs it.

Where tests go

  • Scripts tab: the tests for a script are a script with the same name plus .spec. events.spec tests events. The test tube on a script's tab switches between the script and its tests. A new spec starts from a template. It is saved when you edit it or run it.
  • Events, buttons and actions: the Script effect has Script and Test tabs. The test imports the script as ./~effect. Its trigger(e) first sets the interaction's own Set flags, as a chat does before the script runs. The interaction's note, secret and other fields are not applied in a test.
import { chat } from "@voxta";
import { setFlags } from "@voxta/test";
import { openDoor } from "./events";

describe("openDoor", () => {
  it("opens the door with the key", () => {
    setFlags("has_key");
    openDoor();
    expect(chat.setFlag).toHaveBeenCalledWith("door.open");
  });
});
import { createEvent, published } from "@voxta/test";
import { trigger } from "./~effect";

it("sets the weather", () => {
  trigger(createEvent({ message: "It starts to rain" }));
  expect(published().contexts.weather.text).toBe("It rains.");
});

Running them

  • Validate runs every test with the other checks. The button shows a green check or a red cross for a few seconds after it runs.
  • ▶ beside a describe or a test runs only that test, or the tests in that describe. After a run it becomes a ✓ or ✗, which you click to run it again. A failure is underlined where it happened, in the test or in the script it tests.
  • Right-click a script's test tube, or a tab, and pick Run to run that script's tests. The test tube becomes a ✓ or ✗.
  • On an interaction's Test tab, Run runs its tests.
  • The Tests tab lists the problems first, as a table. Click a file to open it at the line. Below the table, All tests and checks lists every test and every validation check that ran, with its time. It is folded while something failed.

With a PG edition, tests touching // #if explicit blocks run again as the PG edition plays. Each result says which edition it ran as.

What a test can use

  • Jest: describe, it, test, expect, beforeEach, afterEach, jest.fn, jest.spyOn, and fake timers. They are globals. Importing them from @voxta/test works too, as from @jest/globals. Snapshots, jest.mock, beforeAll and afterAll are not available.
  • The chat: every chat method is a spy that still runs. A test checks what a script asked for: expect(chat.setFlag).toHaveBeenCalledWith("door.open"). A test replaces an answer with chat.infer.mockResolvedValue("yes").
  • Each test runs alone in a fresh chat. Module state, flags, variables and timers start again for each test. Like a new chat, it starts with the scenario's declared variables and tables.
  • Variables and tables: read what a script wrote with chat.get('gold') and chat.table('inventory').toArray(), which gives plain rows to compare: expect(chat.table('inventory').toArray()).toEqual([{ name: 'Potion', qty: 2 }]). Numbers are plain numbers, and a column left out of addRow is there with 0, '' or false. Set a start for a test in beforeEach with chat.set(...) or chat.table('inventory').addRow(...).
  • Random outcomes: write one test per outcome and pin the roll with jest.spyOn(Math, "random").mockReturnValue(0.05). Don't roll in a loop until the outcome you want comes up.
  • chat.testing is true only in a test. Use it for logging that only a test needs.
  • it.explicitOnly(...) runs only in explicit chats. The PG edition skips it.

@voxta/test gives these helpers:

HelperWhat it does
createEvent(...)The e that a trigger gets. Its character is the main character unless you give one, or null for none.
dispatch(type, e)Calls the chat.on listeners. Import ./index first.
createListenerEvent(type)A listener's e, with its spies (setActions, rewriteUserMessage).
published()What the scripts published: contexts, actions, buttons, controls, roles, roles off screen (published().offScreen.guard), and the flags once theirs land. Each context is an object: published().contexts.weather.text. Buttons are grouped by the key given to setButtons: published().buttons.dice. A context, actions, buttons or controls set to nothing are gone (undefined, not []), as in the chat.
messages({ role })The notes, secrets and other messages the scripts sent, in order. Give a role such as "secret" to get only those.
appTriggers(), takeAppTriggers()What the scripts sent to the app. An asset is sent as the urn: that assets.get returns, so match its end: expect.stringContaining("rain.png").
setFlags(...)The flags from now on. chat.hasFlag sees them, with what the scripts set afterwards over them. "!flag" removes a flag, even one a script set.
createCharacter(...), setCharacters([...])Who is in the chat.
setScenario({ ... })Scenario fields, such as assets or actions.
setExplicit(...), setChatTime(...)What chat.explicit and chat.time say.

Nothing replies or generates in a test. Mock anything a test waits for from the AI, or the test fails with "The test never finished".

Coverage and lint

The Tests tab lists the scripts and interactions with no tests yet. It warns about tests whose script does not exist anymore. Renaming a script renames its tests.

Validate also lints the scripts. It warns about code that runs but is known to be wrong:

RuleWhat it finds
no_urnA urn: written by hand. It holds the resource's id, which changes on clone or import.
no_spec_importA script that imports a spec. A chat never loads specs.
no_requirerequire(...). Scripts are ES modules.
glob_in_regexA glob such as "Avatars/*.png" given to matchFiles, oneOf or oneOrNoneOf, which take a regular expression.
pg_directiveA misspelled // #if explicit, which a chat ignores.
voxta_directiveA // voxta: comment that does not parse, such as disable coverage: reason, which turns nothing off.

Comments turn a check off:

  • // voxta:test disable coverage: this script needs no tests. For an event, button or action, put it in its Script, or in its Test tab while that has no test.
  • // voxta:test disable no_matching_source: this spec tests several scripts.
  • // voxta:lint disable no_urn: turns the rule off for this script.
  • // voxta:lint disable-next-line no_urn: turns the rule off for the next line.

A reason can follow -- (or a dash): // voxta:test disable coverage -- only sets a flag.

What's next

On this page