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/latest/src/canary/examples/.canary │
│ Version │ 26.4.16.dev0 │
│ 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/latest/src/canary/examples/.canary │
│ Version │ 26.4.16.dev0 │
│ 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 jobs based on runtime environment
INFO: Starting session 2026-06-04T20-43-29.933666
INFO: Starting process pool with max 1 workers
Job ID Status Elapsed Rank
───────────────────────────────────────────────────────────────────────────────────
first 4b172fc SUBMITTED 1/2
first 4b172fc STARTED 1/2
first 4b172fc PASS (SUCCESS) 0.7s 1/2
second b1f18b4 SUBMITTED 2/2
second b1f18b4 STARTED 2/2
second b1f18b4 PASS (SUCCESS) 0.3s 2/2
INFO: 2/2 tests finished with status PASS
INFO: Finished session in 1.08 s. with returncode 0
INFO: Updating view at /home/docs/checkouts/readthedocs.org/user_builds/canary-wm/checkouts/latest/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 │
├────────────┼──────────┼───────────────────────────────────┼──────────────┼────────────┼───────────────────┼──────────┤
│ b1f18b4 │ second │ 2026-06-04T20-43-29.933666 │ 0 │ 0.31 │ PASS (SUCCESS) │ │
│ 4b172fc │ first │ 2026-06-04T20-43-29.933666 │ 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/