Controlling test execution based on dependency results#

By default, a test case will not run unless all of its dependencies complete successfully. This behavior can be modified by passing the result argument to depends_on().

Example#

Run a test case only when its dependency fails:

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

import sys

import canary

canary.directives.depends_on({"job": "willfail", "when": "on_failure"})


def depends_on_willfail() -> int:
    instance = canary.get_instance()
    assert instance.dependencies[0].name == "willfail"
    assert instance.dependencies[0].status.category.name == "FAIL"
    return 0


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

depends_on_willfail will run only if the result of willfail is failed:

$ canary run ./depends_on/result
INFO: Initializing empty canary workspace at .
INFO: Collecting generator files from depends_on/result
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
INFO: Created selection 'tranquil-eagle'
INFO: Selecting test jobs based on runtime environment
INFO: Starting session 2026-06-04T20-43-18.271770
INFO: Starting process pool with max 1 workers
Job                  ID        Status                                          Elapsed      Rank  
────────────────────────────────────────────────────────────────────────────────────────────────
willfail             cd68ac3   SUBMITTED                                                     1/2  
willfail             cd68ac3   STARTED                                                       1/2  
willfail             cd68ac3   FAIL (FAILED)                                      0.4s       1/2  
depends_on_willfail  d51f3e7   SUBMITTED                                                     2/2  
depends_on_willfail  d51f3e7   STARTED                                                       2/2  
depends_on_willfail  d51f3e7   PASS (SUCCESS)                                     0.4s       2/2  
┌──────────┬─────────┬───────────────┬─────────┬────────────────────────────────┐
│ Job      │ ID      │ Status        │ Elapsed │ Details                        │
├──────────┼─────────┼───────────────┼─────────┼────────────────────────────────┤
│ willfail │ cd68ac3 │ FAIL (FAILED) │    0.1s │ Test exited with exit code = 1 │
└──────────┴─────────┴───────────────┴─────────┴────────────────────────────────┘
 2/2 COMPLETE, 1 SUCCESS, 1 FAILED, in 00:00:00.91                                                                      
INFO: Finished session in 0.97 s. with returncode 8
INFO: Updating view at /home/docs/checkouts/readthedocs.org/user_builds/canary-wm/checkouts/latest/src/canary/examples/TestResults

Note

To execute a test regardless of the results of its dependencies, use result="*".

On this page