Running the tests
nimble install -d -y # fetch dependencies pinned in nimble.lock
nimble setup # wire the dependency paths into config.nims
nimble test # headless tests
nimble test also runs para art fix's Python tests, so it needs
uv on PATH (see tools/art/README.md).
The local loop: para test --filter
The whole suite is about 10 minutes from a cold Nim cache (it compiles and
runs ~60 test files one after another), so while working run only the files
you touched. Build para once (nim c --hints:off --outdir:tmp tools/para/para.nim), then:
tmp/para test --filter test_audio # only test files whose path contains "test_audio"; the rest are not compiled
tmp/para test --filter games/ # every game test
tmp/para test --area game # the game's tests + the `para` tests that link it
tmp/para test --area art # the art pipeline's tests + pytest (tools/art)
tmp/para test # everything (what main and engine changes run)
--filter is a case-insensitive substring of the test file's path and runs
only those files (a bare --filter run skips pytest and the final para
build too); --area picks the files whose import graph reaches that part of
the repo, and combines with --filter. The first run of a file compiles it
(game tests ~8 s each); later runs reuse .nimcache/ and cost only the test's
own run time. Each test file prints one progress I/N: <file>: pass|FAIL line
on stderr as it finishes, so a long run shows how far it got; a failing golden
frame is for CI or a human to re-render, never fixed locally.
Running the checks on demand
CI runs on every push to main and every pull request (ci.yml), and by hand.
platform-check.yml is manual only. To run the full Linux CI yourself:
tmp/para test --filter <file> # locally: the narrow run for what you changed
gh workflow run ci.yml # the full Linux CI
gh workflow run ci.yml --ref <branch> # the same, on a branch (the workflow file must exist on it)
gh run watch # follow the run
A manual run takes the all row of the table below (every test). The
repository variable CI_RUNNER (JSON runs-on, e.g.
["self-hosted","linux","paraloop-ci"]) picks a self-hosted runner; unset, CI
runs on GitHub-hosted ubuntu-latest.
What CI runs for a pull request
CI runs the test job as four shards on four runners (para test --shard i/4,
one quarter of the selected files each, under one aggregate check named test) and scopes
a pull request's selection to the area it touches
(.github/scripts/ci-scope.sh buckets the changed paths, then runs
para test --area ...; run git diff --name-only origin/main... | .github/scripts/ci-scope.sh
to see what a diff triggers). A test file is in an area when the repo files it
imports (transitively) include that area's source roots
(tools/para/testplan.nim), so a change can only skip a test that cannot see it.
| Changed paths | para test --area |
Runs |
|---|---|---|
games/<name>/ code, tests, goldens |
game |
every test under games/*/tests/ plus the tests/test_para_* files that link the game (sim_cli, shot_script, dev_cli, usage) and the sim gate |
games/*/assets, games/*/art, games/*/atlas, tools/art/, tools/para/artcmd.nim, tools/para/art/{fix,lint,profile,sheet,sidecar,toml}.nim, tests/fixtures/art/, tests/test_art_* |
art |
tests/test_art_*, the para tests that import those modules, and pytest for tools/art |
src/, template/, tools/para/ (the rest, incl. art/clihelpers.nim, art/toon.nim), tools/web/, examples/, patches/, .github/, config.nims, paraloop.nimble, nimble.lock, tests/ (the rest), skills/para/ (a test reads SKILL.md), any path not listed here |
all |
everything, same as a push to main |
*.md, docs/, tools/docs/, skills/ (except skills/para/), LICENSE*, .github/ISSUE_TEMPLATE/ only |
none | the test job is skipped (reports skipped) |
Pushes to main, workflow_dispatch and any non-PR run always use all, and an
unreadable or empty diff fails open to all.
PR_FULL_TESTS=off skips the full-suite jobs on pull requests.
The docs job is not scoped: it runs on every pull request and push, docs-only ones included,
builds the documentation site with uv run tools/docs/build.py (about half a minute) and fails
on a broken link or image, missing alt text, headings out of order, or a local path, tailnet
address or email address (site.md has the full list). Run the same command locally
before pushing a docs change.
Heavy simulation tests (test_sim_replay, test_para_shot_script,
test_para_sim_cli, and a game's bot-run and driver tests) each carry a test_<name>.nims beside them that builds that
file with --stacktrace:off -O1: same assertions and every runtime check
still on, ~5-7x faster. Delete the .nims to get Nim stack traces back while
debugging an unexpected exception in one of them.
CI (.github/workflows/ci.yml) can run on a self-hosted runner instead of
GitHub-hosted runners (CI_RUNNER), and can skip the full suite on PRs
(PR_FULL_TESTS), each switched by a repository variable; see the header comment in ci.yml.