Getting started with parameterization

In the most simple case, a single parameter is defined, as demonstrated in the example paramterize/parameterize1.pyt:

# Copyright NTESS. See COPYRIGHT file for details.
#
# SPDX-License-Identifier: MIT

import sys

import canary

canary.directives.parameterize("a", (1, 4))


def test():
    self = canary.get_instance()
    print(f"{self.parameters.a}")
    return 0


if __name__ == "__main__":
    sys.exit(test())

The test file generates two test cases with parameters a=1 and a=4, respectively:

$ canary describe parameterize/parameterize1.pyt
--- parameterize1 ------------
File: /home/docs/checkouts/readthedocs.org/user_builds/canary-wm/checkouts/latest/src/canary/examples/parameterize/parameterize1.pyt
Keywords: 
2 test specs using on_options=:
├── parameterize1.a=1
└── parameterize1.a=4

When the test file is run, each case is executed in its own uniquely named directory:

$ canary run parameterize/parameterize1.pyt
INFO: Initializing empty canary workspace at .
INFO: Collecting generator files from parameterize
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 1 generators
INFO: Caching test specs
INFO: Created selection 'focused-lark'
INFO: Selecting test jobs based on runtime environment
INFO: Starting session 2026-06-04T20-43-20.836337
INFO: Starting process pool with max 1 workers
Job                ID        Status                                          Elapsed      Rank  
──────────────────────────────────────────────────────────────────────────────────────────────
parameterize1.a=1  76f0570   SUBMITTED                                                     1/2  
parameterize1.a=1  76f0570   STARTED                                                       1/2  
parameterize1.a=1  76f0570   PASS (SUCCESS)                                     0.7s       1/2  
parameterize1.a=4  bd89527   SUBMITTED                                                     2/2  
parameterize1.a=4  bd89527   STARTED                                                       2/2  
parameterize1.a=4  bd89527   PASS (SUCCESS)                                     0.4s       2/2  
INFO: 2/2 tests finished with status PASS
INFO: Finished session in 1.26 s. with returncode 0
INFO: Updating view at /home/docs/checkouts/readthedocs.org/user_builds/canary-wm/checkouts/latest/src/canary/examples/TestResults

$ ls -F TestResults/
VIEW.TAG
parameterize1.a=1@
parameterize1.a=4@

Test directories are generally named $family.$param_1=$value_1...$param_n=$value_n, where family is (usually) the basename of the test file.

VIEW.TAG
parameterize1.a=1@
parameterize1.a=4@