Testing scripts
Test every script before a game needs it. To test one, open the Test tab under the code, fill in the input and press Run (⌘/Ctrl+Enter). Run the normal case and each edge case (an empty inventory, a name that isn't there, too little gold, a roll that exactly ties), and check that the result says what the GM needs to tell the story. Reach an edge case through the test's setup (its input, the scene below, a person's test values), never by editing the world's files, and note each test's setup and result.
What a test run does
A test run runs the script as the GM would, against this world's files (a game's own, when you test in a game), with three differences:
- Nothing is saved. A script saves only when the GM runs it in a game, and then only to that game's files. A test is a dry run: what the script would create or change, in files and in the current state, is listed instead, and each roll, effect and reaction as a line ("Roll: Goblin 1 1d20+4 = 17 vs AC 15 at Riven (Scimitar attack)").
- The scene is the one you give it. A test has no game to take a
current state from, so it reads the scene you set up (below). With none,
the current state is empty but for the character you test as: a script
that reads who is there finds no one else, and a roll, effect, reaction or
change that names anyone else (
by,at) throwsNOT_IN_CURRENT_STATE. - No player is asked to roll.
game.askPlayerToRoll()rolls the dice for them.
Math.random() gives a different answer each run: run a table a few times
to see its rows come up.
A scene
A scene is the current state a test run reads, written as
game.currentState.get() returns it, every part optional:
{
"place": { "file": "Goblin Barracks" },
"time": "Night, the second bell",
"purpose": "Fight the barracks guard",
"grid": { "columns": 10, "rows": 8 },
"people": [
{ "file": "Brannoch Ironvale", "side": "ally", "square": "E3", "fields": { "hp": 4 } },
{ "name": "Goblin 1", "of": "Goblin Warrior", "side": "enemy", "square": "D4", "details": { "HP": 7 } },
{ "name": "Ogre", "what": "a hill ogre", "side": "enemy", "square": "F5–G6" }
],
"trackers": [
{ "name": "Combat", "fields": [{ "kind": "order", "entries": [{ "name": "Brannoch Ironvale", "score": 17 }, { "name": "Goblin 1", "score": 12 }], "current": "Brannoch Ironvale", "round": 2 }] }
]
}
- Files (a person's own, the kind an extra is
of, the place) are named by name, slug or id. - Someone with a file is in the scene by their file's name, and their
state stays in their file: give them test values in
fields, which the run reads in place of the file's own (nothing is saved). An extra keeps its owndetails. gridis a mock map:columnsandrows(up to 200),squareSize(5),unit("ft") andmeasurement(chebyshev, diagonals count 1, as in 5e;alternating-diagonal, as in PF2e;euclidean;manhattan). People stand on it bysquare("C4", or "F5–G6" for a creature two squares across), and each person'ssquareanddistancesare worked out from them as the map works them out in play.- The character you test as is always there, as the player
(
isPlayer). - A card's buttons read the scene as the run left it, as in play, where the run's changes land before anyone presses. A button that changes the current state fails, as it does in play.
When a scene has a problem (a name that matches no file, or several; a square off the grid; two people with one name), the run doesn't start and every problem is listed.
What comes back
- The result, as the GM would get it.
- What it would change: one line per change.
- Logs: what
console.logprinted. - An error: a thrown message, with the script's name and about which line ("No slots left (castSpell, near line 5)"). The line points near the throw, not always at it.
- Lookups that missed, with the closest names the world has, when a
get()found nothing and the run failed. - Why the card couldn't be drawn, when
card()returned something that can't be shown; players would get no card. - How close the card came to its limits, when it was drawn: its size and elements against the most a card can have. Both grow with the run's data, so test the largest case.
In the script editor
The script editor's test form is built from the script's input fields, and
it runs the source as it is in the editor, saved or not. Its "Test as"
choice picks the character game.playerCharacter() returns. Under it,
Scene sets up the current state: pick a place, add people with a file
or extras of a kind, set their side, details or test values, turn on the
mock map to put them on squares (it shows the distances a script will
read), and add the world's trackers (a fight's turn order, a clock),
edited as you edit them in play. The same scene can be written as JSON;
switch between the two at any time. In a game, Use this game's current
state loads the game's own scene, battle map included, to start from.
Your browser keeps each script's scene and input, who you test as, and
whether the console was open. A player script's card
shows as players will see it, and pressing its buttons runs the actions as
dry runs too. This is the only place to test a card's buttons.
When a test run won't start
- The script has problems. Fix what the check lists first. A script that calls an invalid script, or one that doesn't exist, can't run either.
- Too many scripts are running in this world right now: wait a moment and run again.
- The script ran too long: it went past its 3 seconds, usually a loop that never ends or too many lookups in a row.
Testing in a game
Some things only happen in play: the GM choosing to run the script from its
beforeNarrationTrigger, afterNarrationTrigger firing at the end of a turn, rolls and effects on the map,
what the script's changes do to the current state once they land, and a
player's own roll. Start a game from the world,
play to the moment, and check that the GM ran the script and told its result
truthfully. A script's card and what it changed show in the story where it
ran.