Canary basics: the Canary workspace#
The Canary workspace is a folder in which all inputs, intermediate files, and outputs are contained.
Creating the workspace#
At the command line, type:
$ canary init .
INFO: Initializing empty canary workspace at .
This creates a new folder named .canary that contains all of the necessary workspace files.
The workspace can be inspected via canary info:
$ canary info
┌────────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Workspace │ /home/docs/checkouts/readthedocs.org/user_builds/canary-wm/checkouts/release-26.4.16/src/canary/exampl… │
│ Version │ 26.4.16 │
│ Specs │ 0 │
│ Test roots │ │
│ Sessions │ 0 │
│ Latest │ │
│ Tags │ │
└────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────┘
At this point, the workspace is empty. Tests are added to the workspace by collecting test case generators and creating a “selection”:
$ canary collect -r ./basic
INFO: Collecting generator files from basic
INFO: Instantiating generators from collected files
INFO: Generating test specs from generators
INFO: Searching for duplicated tests
INFO: Resolving test spec dependencies
INFO: Generated 2 test specs from 2 generators
INFO: Caching test specs
$ canary select basic
INFO: To run this selection execute 'canary run basic'
Running canary info now reports the addition of this tag:
$ canary info
┌────────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Workspace │ /home/docs/checkouts/readthedocs.org/user_builds/canary-wm/checkouts/release-26.4.16/src/canary/exampl… │
│ Version │ 26.4.16 │
│ Specs │ 0 │
│ Test roots │ │
│ Sessions │ 0 │
│ Latest │ │
│ Tags │ │
└────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Running tests#
A tagged selection is run by canary run TAGNAME. To run the previously tagged “basic” selection, execute:
$ canary run basic
INFO: Running tests in tag basic
INFO: Selecting test cases based on runtime environment
INFO: Starting session 2026-04-21T15-34-38.475755
INFO: Starting process pool with max 2 workers
Job ID Status Queued Elapsed Rank
─────────────────────────────────────────────────────────────────────────────────────────────
second 57a9775 SUBMITTED 2/2
second 57a9775 STARTED 0.2s 2/2
first 260b4b0 SUBMITTED 1/2
first 260b4b0 STARTED 0.3s 1/2
first 260b4b0 PASS (SUCCESS) 0.2s 0.5s 1/2
second 57a9775 PASS (SUCCESS) 0.2s 0.6s 2/2
INFO: 2/2 tests finished with status PASS
INFO: Finished session in 0.64 s. with returncode 0
INFO: Updating view at /home/docs/checkouts/readthedocs.org/user_builds/canary-wm/checkouts/release-26.4.16/src/canary/examples/TestResults
Status#
To get the status of tests in the workspace, type:
$ canary status -rA
┌────────────┬──────────┬───────────────────────────────────┬──────────────┬────────────┬───────────────────┬──────────┐
│ ID │ Name │ Session │ Exit Code │ Duration │ Status │ Details │
├────────────┼──────────┼───────────────────────────────────┼──────────────┼────────────┼───────────────────┼──────────┤
│ 260b4b0 │ first │ 2026-04-21T15-34-38.475755 │ 0 │ 0.21 │ PASS (SUCCESS) │ │
│ 57a9775 │ second │ 2026-04-21T15-34-38.475755 │ 0 │ 0.31 │ PASS (SUCCESS) │ │
└────────────┴──────────┴───────────────────────────────────┴──────────────┴────────────┴───────────────────┴──────────┘
canary status tells you the ID and name of the test, which session that test was run in, exit code, duration, and status.
The workspace view#
On completion of canary run, a “view” of the latest test results is created in a folder named TestResults. The view is a directory structure mirroring the test source tree. After running the basic tag, the view contains entries for the basic/first and basic/second tests:
$ ls -F TestResults
VIEW.TAG
first/
second/