Command-Line Testing with dgbuild

dgbuild is a command-line tool that ships inside the dialog-ide npm package. It is named to sit with the rest of the toolchain — dgdebug, dialogc, aambundle — rather than after the extension.

Install it globally:

or run it without installing:

The npm package contains no binaries. dgbuild needs the Dialog toolchain — at least dgdebug — on your PATH, or a binDir set in dialog.json. Run it from the project root, or point it elsewhere with -p <dir> / --project <dir>.

Runs the project’s unit tests, by invoking dgdebug --unit-test, and exits with dgdebug 's own exit code. It exits non-zero on any test failure — and also if dialog.json declares no test sources at all, since having nothing to run is treated as a failure rather than a silent pass.

--no-debug leaves the debug sources out of the run (they are included by default, matching the extension’s Run Tests). Anything after the options is passed straight through to dgdebug.

Writing the tests themselves — the (test $) and (assert $) objects — is covered in the "Testing and Debugging" chapter of the Dialog manual, not here.

Replays one or more saved skeins against a fresh dgdebug process each, comparing every knot’s live response to its blessed response. With no arguments it replays default.

For each skein it prints a summary line — name: valid/new/error (valid/new/error) — and, when you pass more than one skein, a total: line as well. Any knots that came out in error are listed above the summary.

It exits non-zero only if some knot is in error. Unblessed new knots do not fail the run, so if you want continuous integration to require every knot be blessed, bless them first. -v / --verbose adds the underlying dgdebug lifecycle logging, which is quiet by default.

This is the command-line equivalent of the panel’s Replay All.

These run the full interactive Skein UI — the same transcript, navigation graph, trace panel and keyboard shortcuts the extension’s Skein panel provides — served as a local web page, with no editor involved. dgbuild starts an HTTP server on localhost, prints its URL, and opens your default browser at it (pass --no-open to just print the URL, e.g. on a headless box).

new-skein [name] creates a new skein file (default default.skein) and refuses to overwrite an existing one. open-skein [name] opens an existing one, refuses a missing file, and replays every branch on load so live source edits are picked up — exactly as the extension does when it opens a skein. Only dgdebug skeins are supported for now.

Options: --seed <n> (new-skein only; default a random seed), --port <n> (default an OS-assigned free port), --theme <light|dark>, --no-open, -p / --project, and -v / --verbose.

Stopping it. The navigation bar carries a Quit button. If the skein has unsaved changes it opens a confirmation dialog offering Save and Quit, Quit Without Saving, or Cancel; a clean skein quits immediately. Either way the browser tab is left showing a "you may close this window" screen while dgbuild shuts the server and the dgdebug process down and exits. Pressing Ctrl+C in the terminal also shuts down cleanly, but cannot save — it warns if there are unsaved changes.

Tracing. Choosing Trace on a knot opens the trace in a second browser tab (the extension shows it in a docked panel instead). Hovering a trace row still previews the source; clicking it does nothing here, since there is no editor to open.

Prints the project’s fully expanded source list — exactly the files the compiler would receive. -d / --debug and -t / --test add those categories; -T <suffix> / --target <suffix> filters by target suffix; -1 / --single-line prints the paths colon-joined on one line, for feeding into another command.

Builds a complete web page for one of dialog.json 's named export configurations into out/web/, plus a zip at out/<name>-<release>.zip — the command-line equivalent of the extension’s Export Web Page…​. The page carries the downloadable story file (compiled with that configuration’s own format, debug and dialogc-option settings), an in-browser AAmachine player, the cover thumbnail, the project’s configured feelies, and — if default.skein has a knot labeled WALKTHROUGH — a walkthrough transcript. Title, author, blurb, release and IFID come from the project’s own (story …​) directives, queried live via dgdebug.

Name the configuration to build, or omit the name when dialog.json defines exactly one:

Unlike the other commands, bundle needs all three of dialogc, dgdebug and aambundle available. -v / --verbose adds the underlying dgdebug lifecycle logging. It exits non-zero if no matching export configuration is found, a required binary is missing, or any build step fails.

A minimal release gate in a GitHub Actions workflow:

To build and publish the web page once the checks pass — here to GitHub Pages:

The runner also needs the Dialog toolchain available — install dgdebug onto its PATH, or point dialog.json 's binDir at a copy you provide. dgbuild bundle additionally needs dialogc and aambundle.

Troubleshooting and Known Limitations — known limitations and the common reasons a project will not run.