hookspec

canary_addhooks(pluginmanager: CanaryPluginManager) → None

Called at plugin registration time to allow adding new hooks via a call to pluginmanager.add_hookspecs(module_or_class, prefix).

Parameters:

pluginmanager – The canary plugin manager.

Note

This hook is incompatible with hookwrapper=True.

canary_addoption(parser: Parser) → None

Register argparse options, called once at the beginning of a test run.

Parameters:

parser – To add command line options, call parser.add_argument(...).

Options can later be accessed through the config object:

• config.getoption(name) to retrieve the value of a command line option.

Note

This hook is incompatible with hookwrapper=True.

canary_addcommand(parser: Parser) → None

Add a subcommand to Canary

Parameters:

parser – To add a command, call parser.add_command(...).

Note

The command should be a subclass of canary.CanarySubcommand

Example:

import argparse
import canary

class MyCommand(canary.CanarySubcommand):
    name = "my-command"
    description = "my-command description"

    def setup_parser(parser: canary.Parser) -> None:
        parser.add_argument("--flag")

    def execute(args: argparse.Namespace) -> int:
        ...

@plugins.hookimpl
def canary_addcommand(parser: canary.Parser):
    parser.add_command(MyCommand())

canary_cmdline_parse(parser: Parser, args: list[str]) → Namespace

canary_cmdline_modifyargs(parser: Parser, args: Namespace) → None

canary_subcommand() → CanarySubcommand

DEPRECATED: use canary_addcommand

canary_addconfig(config: CanaryConfig) → None

canary_configure(config: CanaryConfig) → None

Allow plugins to perform initial configuration.

This hook is called for every plugin and after command line options have been parsed.

Note

This hook is incompatible with hookwrapper=True.

Parameters:

config – The canary config object.

canary_sessionstart(session: Session) → None

canary_sessionfinish(session: Session) → None

canary_collectstart(collector: Collector) → None

Start collection.

Parameters:

collector – Add files and directories to the collector.

Notes

To add generators to the collector call collector.add_generator(...). To add directory names to skip call collector.add_skip_dirs(...).

canary_collect_modifyitems(collector: Collector) → None

Called after collection of test files is complete. May filter or re-order items in place

canary_collect_report(collector: Collector) → None

Write a report to the console for collected items

canary_testcase_generator(root: str, path: str | None) → AbstractTestGenerator | Type[AbstractTestGenerator]

Returns an implementation of AbstractTestGenerator

canary_generator(root: str, path: str | None) → AbstractTestGenerator

DEPRECATED: Use canary_testcase_generator

canary_generatestart(generator: Generator) → None

Starts the generate process.

Parameters:

generator – The generator to start.

canary_generate_modifyitems(generator: Generator) → None

Modifies the generate items.

Parameters:

generator – The generator to modify.

canary_generate_report(generator: Generator) → None

Reports the generation results.

Parameters:

generator – The generator to report on.

canary_selectstart(selector: Selector) → None

Starts the selection process.

Parameters:

selector – The selector to start.

canary_select_modifyitems(selector: Selector) → None

Modifies the selection items.

Parameters:

selector – The selector to modify.

canary_select_report(selector: Selector) → None

Reports the selection results.

Parameters:

selector – The selector to report on.

canary_rtselectstart(selector: RuntimeSelector) → None

Starts the selection process.

Parameters:

selector – The selector to start.

canary_rtselect_modifyitems(selector: RuntimeSelector) → None

Modifies the selection items.

Parameters:

selector – The selector to modify.

canary_rtselect_report(selector: RuntimeSelector) → None

Reports the selection results.

Parameters:

selector – The selector to report on.

canary_runtests_start(runner: Runner) → bool

Called at the beginning of canary run

canary_runtests(runner: Runner) → None

Runs the tests.

Parameters:

runner – The runner to run.

canary_runtests_report(runner: Runner) → None

Reports the test results.

Parameters:

runner – The runner to report on.

canary_runtest_launcher(case: Job) → Launcher

Returns the launcher for a test case.

Parameters:

case – The test case.

Returns:

The launcher.

Note:

canary_runteststart(case: Job) → bool

Called to perform the setup phase for a test case.

The default implementation runs case.setup().

Parameters:

case. (The test)

Note

This function is called inside the test case’s working directory

canary_runtest(case: Job) → bool

Called to run the test case

Parameters:

case. (The test)

Note

This function is called inside the test case’s working directory

canary_runtest_finish(case: Job) → bool

Called to perform the finishing tasks for the test case

The default implementation runs case.finish()

Parameters:

case. (The test)

Note

This function is called inside the test case’s working directory

canary_resource_pool_fill(config: CanaryConfig, pool: dict[str, dict[str, Any]]) → None

Fill resources with available resources.

canary_resource_pool_accommodates(case: Job) → Outcome

Determine if there are sufficient resource to run job.

canary_resource_pool_count(type: str) → int

Return the number resources available of type type

canary_resource_pool_count_per_node(type: str) → int

Return the number resources available of type type per node

canary_resource_pool_types() → list[str]

Return the names of available resources

canary_resource_pool_describe() → str

Return a string describing the resource pool