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 'mint-pine'
INFO: Selecting test jobs based on runtime environment
ERROR: no jobs 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 'certain-tide'
INFO: Selecting test jobs based on runtime environment
INFO: Starting session 2026-06-04T20-43-53.969873
INFO: Starting process pool with max 1 workers
Job     ID        Status                                          Elapsed      Rank  
───────────────────────────────────────────────────────────────────────────────────
enable  f84c784   SUBMITTED                                                     1/1  
enable  f84c784   STARTED                                                       1/1  
enable  f84c784   PASS (SUCCESS)                                     0.6s       1/1  
INFO: 1/1 tests finished with status PASS
INFO: Finished session in 0.70 s. with returncode 0
INFO: Updating view at /home/docs/checkouts/readthedocs.org/user_builds/canary-wm/checkouts/latest/src/canary/examples/TestResults