diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/module/fuzzer.md | 30 | ||||
| -rw-r--r-- | docs/module/rules.md | 5 | ||||
| -rw-r--r-- | docs/overview/architecture.md | 14 | ||||
| -rw-r--r-- | docs/server/production.md | 6 | ||||
| -rw-r--r-- | docs/server/toolbox.md | 5 |
5 files changed, 32 insertions, 28 deletions
diff --git a/docs/module/fuzzer.md b/docs/module/fuzzer.md index d69b992..d576693 100644 --- a/docs/module/fuzzer.md +++ b/docs/module/fuzzer.md @@ -1,9 +1,4 @@ -# Fuzzing the Troops! - -We use [Jazzer.js](https://github.com/CodeIntelligenceTesting/jazzer.js/) -as a coverage-guided fuzzer for automatic testing of module rules. - -## What is fuzzing? +# Fuzz the Troops! Fuzzing or fuzz testing is an automated software testing technique that involves providing invalid, unexpected, or random data as inputs to a computer @@ -16,35 +11,34 @@ The fuzzer can detect the following types of errors: * Dead-end game states where no other actions are available (besides "undo"). * A game taking an excessive number of steps. This could indicate infinite loops and other logical flaws in the rules. -Work files are written to the "fuzzer" directory. +Crash dumps are written to the "fuzzer" directory. ## Running -Start the fuzzer: - - bash tools/fuzz.sh title [ jazzer options... ] +There are two fuzzers available: -This will run jazzer until you stop it or it has found too many errors. +A fuzzer that uses the "jsfuzz" package. +With this fuzzer every title gets its own "fuzzer/corpus-title" sub-directory. +The corpus helps the fuzzer find interesting game states in future runs. -To keep an eye on the crashes, you can watch the fuzzer/log-title.txt file: + rtt fuzz TITLE - tail -f fuzzer/log-title.txt +A simple fuzzer that plays completely randomly: -Each fuzzed title gets its own "fuzzer/corpus-title" sub-directory. -The corpus helps the fuzzer find interesting game states in future runs. + rtt fuzz-rand TITLE -To create a code coverage report pass the `--cov` option to fuzz.sh. +The fuzzer will run until you stop it or it has found too many errors. ## Debug When the fuzzer finds a crash, it saves the game state and replay log to a JSON file. You can import the crashed game state like so: - node tools/import-game.js fuzzer/dump-title-*.json + rtt import fuzzer/dump-title-*.json The imported games don't have snapshots. You can recreate them with the patch-game tool. - node tools/patch-game.js game_id + rtt patch GAME ## Avoidance diff --git a/docs/module/rules.md b/docs/module/rules.md index ed99188..7f9ae2d 100644 --- a/docs/module/rules.md +++ b/docs/module/rules.md @@ -170,6 +170,11 @@ There's also a global scope for the main game data (via the G namespace). --- +The state stack is implmented as a linked list (G.L is the head of the linked +list, and G.L.L is the next state down the stack, etc.) Invoking call pushes a +new state at the top of the stack; goto replaces the current top of the stack, +and end pops the stack. + ## States The "states" where we wait for user input are kept in the S table. diff --git a/docs/overview/architecture.md b/docs/overview/architecture.md index 5865de8..7601d04 100644 --- a/docs/overview/architecture.md +++ b/docs/overview/architecture.md @@ -32,24 +32,24 @@ The following files contain the code and styling for the client display: ## Tools -The "tools" directory holds a number of other useful scripts for administrating the server and debugging modules. +The "rtt" command (in bin/rtt) is useful for administrating the server and debugging modules. - bash tools/export-game.sh game_id > file.json + rtt export game_id > file.json Export full game state to a JSON file. - node tools/import-game.js file.json + rtt import file.json Import a game from an export JSON file. - node tools/patchgame.js game_id + rtt patch game_id Patch game state for one game (by replaying the action log). - node tools/patchgame.js title_id + rtt patch title_id Patch game state for all active games of one module. - bash tools/undo.sh game_id + rtt undo game_id Undo an action by removing the last entry in the replay log and running patchgame.js - bash tools/showgame.sh game_id + rtt show-game game_id Print game state JSON object for debugging. <!-- diff --git a/docs/server/production.md b/docs/server/production.md index 4344630..a559f5e 100644 --- a/docs/server/production.md +++ b/docs/server/production.md @@ -91,13 +91,13 @@ Run the archive and purge scripts as part of the backup cron job. Copy game state data of finished games into archive database. - sqlite3 < tools/archive.sql + rtt archive-backup Delete game state data of finished games over a certain age. - sqlite3 < tools/purge.sql + rtt archive-prune Restore archived game state. - bash tools/unarchive.sh game_id + rtt archive-restore game_id diff --git a/docs/server/toolbox.md b/docs/server/toolbox.md index ebbabaf..f589901 100644 --- a/docs/server/toolbox.md +++ b/docs/server/toolbox.md @@ -15,6 +15,10 @@ Alternatively, you can edit your .profile to add the server bin directory to you PATH=$PATH:$HOME/server/bin +Check that the command works by running the command to create the database: + + rtt init + ## Commands database management @@ -34,6 +38,7 @@ module development foreach -- run a command for each module fuzz -- fuzz test a module + fuzz-rand -- fuzz test a module (random) game debugging |