Enabling/disabling tests

Tests can be enabled and/or disabled using the enable directive. The following test will be run when the option -o enable is passed to canary run, otherwise it will be skipped:

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

import sys

import canary

canary.directives.enable(when="options=enable")


def test():
    pass


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

$ canary run ./enable
INFO: Initializing empty canary workspace at .
INFO: Collecting generator files from enable
INFO: Instantiating generators from collected files
INFO: Generating test specs from generators
INFO: Searching for duplicated tests
INFO: Resolving test spec dependencies
INFO: Generated 1 test specs from 1 generators
INFO: Excluded 1 test spec during generation
                                                            
  Reason                                             Count  
 ────────────────────────────────────────────────────────── 
  options=enable evaluated to False for options=[]       1  
                                                            
INFO: Caching test specs
INFO: Created selection 'robust-shadow'
INFO: Selecting test cases based on runtime environment
ERROR: no cases to run

$ canary run -o enable ./enable
INFO: Initializing empty canary workspace at .
INFO: Collecting generator files from enable
INFO: Instantiating generators from collected files
INFO: Generating test specs from generators
INFO: Searching for duplicated tests
INFO: Resolving test spec dependencies
INFO: Generated 1 test specs from 1 generators
INFO: Caching test specs
INFO: Created selection 'white-glacier'
INFO: Selecting test cases based on runtime environment
INFO: Starting session 2026-04-21T15-34-56.607986
INFO: Starting process pool with max 2 workers
Job     ID        Status                                           Queued   Elapsed      Rank  
─────────────────────────────────────────────────────────────────────────────────────────────
enable  11f3e76   SUBMITTED                                                               1/1  
enable  11f3e76   STARTED                                            0.3s                 1/1  
enable  11f3e76   PASS (SUCCESS)                                     0.3s      0.5s       1/1  
INFO: 1/1 tests finished with status PASS
INFO: Finished session in 0.54 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