Test Examples

Run Examples

Use the workspace examples as smoke tests to catch regressions that unit and integration tests may have missed.

Context

Not every example is verifiable from the CLI — many are 3D/2D Bevy windowed apps, browser-driven, or TUIs that block on stdin. This skill only exercises the ones that exit on their own (or that we can probe with curl while they run in the background).

Stream the entire output of each example into .agents/tmp/scratch.txt (overwrite for the first command, append for subsequent ones), then grep that file. This avoids reruns when checking multiple things.

Treat compile failures the same as the test-run skill: retry once, and if a mold linker error persists (RUST_MIN_STACK, "section sizes" etc) bump the workspace version = "0.0.9-dev.N" in Cargo.toml.

Long-running examples must always be wrapped in timeout (default 60s — drop it lower once you know the example exits faster). Server examples should be launched with run_in_background and killed once the probe has succeeded.

Smoke Set

The set below was chosen so that each feature gate combination is exercised by at least one example, and each crate has at least one self-terminating verifier. Most examples just need an OK exit status; a few have specific output to grep for (noted inline).

1. Action (--features=action)

Covers the action runtime end-to-end: pure handlers, async handlers, control-flow nodes, state machines, score-based selectors, and timers.

cargo run --example hello_world     --features=action       # prints "Hello, world!"
cargo run --example simple_action   --features=action       # caller-entity lookup
cargo run --example behavior_tree   --features=action       # sequence + log
cargo run --example state_machine   --features=action       # RunNext jumps
cargo run --example repeat_while    --features=action       # loop + condition
cargo run --example utility_ai      --features=action       # HighestScore
cargo run --example long_running    --features=action       # 1.3s timer chain
cargo run --example malenia         --features=action,rand  # BT + utility AI

2. Scripting (--features=quickjs)

cargo run --example scripting --features=quickjs             # JS Script<I,O>

3. Router (--features=router,markdown / plus extras)

CLI router server, persisted router, and the codegen pipeline.

cargo run --example router           --features=router,markdown
cargo run --example router           --features=router,markdown -- about
cargo run --example cli              --features=router,quickjs -- greet --name=world
# the persisted scene caches the route scripts, so regenerate it after any change
# to script authoring or to a registered type
cargo run --example router_serde     --features=router,quickjs,template_serde -- --new
cargo run --example router_serde     --features=router,quickjs,template_serde
cargo run --example router_serde     --features=router,quickjs,template_serde -- greet --name=world
# rsx_site is a crate, not a root example: generate its routes, then serve. It
# scans typed pages, markdown content and a server action from three collections.
cargo run -p rsx_site --no-default-features --features codegen   # regenerate src/codegen/
cargo run -p rsx_site                                            # http server (default)
cargo run -p rsx_site --features cli -- guide --accept=text/html # render one route to stdout

4. Todo (--features=router,json)

Round-trip the todo document: list → create → list → delete → list.

cargo run --example todo --features=router,json -- list
cargo run --example todo --features=router,json -- create --body='{"description":"smoke test","done":false}'
cargo run --example todo --features=router,json -- list
cargo run --example todo --features=router,json -- delete --body=0

5. Net (--features=net,ureq,native-tls / --features=http_server)

http_client hits example.com and asserts on the response body — skip if offline.

cargo run --example http_client --features=net,ureq,native-tls

For the server side, run in background and probe with curl:

# launch
cargo run --example http_server --features=http_server     # background
curl -s http://localhost:8337                              # expect 200 + body
curl -s http://localhost:8337?name=billy
# kill the background pid

Same pattern for templating (--features=http_server) and style (--features=http_server,style).

6. Per-crate examples

These belong to a specific crate so they need -p.

cargo run -p beet_core --example runner                    # custom test runner
cargo run -p beet_core --example tracing                   # PrettyTracing init
cargo run -p beet_ui   --example render_simple             # oneshot terminal render
cargo run -p beet_ui   --example inline_formatting         # block + inline runs
cargo run -p beet_ui   --example reactive                  # prints "success"
cargo run -p beet_ui   --example build_css   --features=style       # writes target/examples/style/*
cargo run -p beet_ml   --example hello_ml_basic                     # downloads bert (~90MB, slow first run)
cargo run -p beet_ml   --example hello_rl_basic --features=bevy_default

7. Workspace ML (--features=examples,ml)

The examples,ml feature only gates windowed scene code (now scene modules in beet_extra, not runnable --example targets), so there is no self-terminating CLI smoke here. The runtime ML smoke lives in the crate (hello_ml_basic, section 6); this feature's compilation is covered by the skip-set check below (and is the only coverage, since beet_extra is excluded from the test crates).

8. BSX scenes (beet --main=<file>.bsx)

The no-code .bsx scenes run through the installed beet CLI (when editing rust, cargo run -p beet-cli --features=.. -- <args> instead, so the scenes run against the working tree). Each entry documents its own beet --main=.. command in its header, and an entry that declares its hard requirements with <RequireCfg> fails fast on a leaner binary, naming what is missing. The self-terminating ones render and exit:

A documented command never carries --features: that is the entry's own <RequireCfg>'s job. The binary still has to link the capability though, and the demo scenes name actions from beet_extra, which is the extra cargo feature. Build the CLI once with what the set needs and run everything against it:

cargo build -p beet-cli --features=extra        # every scene below except the ml one
cargo build -p beet-cli --features=extra,ml     # adds `hello_ml.bsx`

A binary without extra does not fail fast on these entries the way hello_ml.bsx does: none of them declare <RequireCfg cfg="feature:extra"/>, so instead of a named missing capability you get a spread warning (skipping spread 'SayHello') and then No Action<(), ()>. Worth fixing in the entries; until then, read that pair of messages as "rebuild with extra".

Beware the ml build specifically: it pulls winit and bevy_render, so every scene brings up a wgpu device and compiles compute pipelines whether or not it needs a GPU. On an NVIDIA host that intermittently segfaults inside libnvidia-glcore during create_compute_pipeline, on bevy's async compute thread, which has nothing to do with the scene. Use the extra-only binary for everything but the ml scene.

beet --main=examples/hello                                       # prints "hello world"
beet --main=examples/action/behavior_tree.bsx                    # sequence + log
beet --main=examples/ml/hello_ml.bsx                             # logs "NearestSentence chose: ..."
beet --main=examples/calculator/main.bsx --server=cli add --a=3 --b=4   # result: 7

The rest of examples/action/*.bsx (hello_world, simple_action, long_running, repeat_while, state_machine, utility_ai, scripting, world_script) are also self-terminating and worth a sweep.

Skip: examples/spatial/*.bsx and examples/ml/frozen_lake_*.bsx (windowed), examples/thread/*.bsx (need an LLM key), examples/bsx_site/main.bsx (HTTP server; verify with beet --main=examples/bsx_site --server=cli instead).

Every scene in examples/action/ exits 0. A () -> Outcome load exits zero once it resolves whatever the outcome (an outcome is a branch, not an error), so malenia.bsx and repeat_while.bsx, whose <Repeat> ends by returning its body's fail, report a completed run. Only a scene carrying {OutcomeOverload{error_on_fail:true}} turns a Fail into a nonzero exit.