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.spectestsevents. 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. Itstrigger(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
describeor a test runs only that test, or the tests in thatdescribe. 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/testworks too, as from@jest/globals. Snapshots,jest.mock,beforeAllandafterAllare not available. - The chat: every
chatmethod 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 withchat.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')andchat.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 ofaddRowis there with0,''orfalse. Set a start for a test inbeforeEachwithchat.set(...)orchat.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.testingis 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:
| Helper | What 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:
| Rule | What it finds |
|---|---|
no_urn | A urn: written by hand. It holds the resource's id, which changes on clone or import. |
no_spec_import | A script that imports a spec. A chat never loads specs. |
no_require | require(...). Scripts are ES modules. |
glob_in_regex | A glob such as "Avatars/*.png" given to matchFiles, oneOf or oneOrNoneOf, which take a regular expression. |
pg_directive | A misspelled // #if explicit, which a chat ignores. |
voxta_directive | A // 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.