canary dist

Manage testing across a distributed pool of machines

canary dist [-h]  ...

Optional arguments

-h, --help

Show this help message and exit.

Subcommands

dist status

dist run

dist exec

canary dist status

canary dist status [-h] [--server-url URL]

Optional arguments

-h, --help

show this help message and exit

--server-url URL

Distributed pool server location (URL). Defaults to CANARY_DIST_SERVER_URL environment variable, if defined.

canary dist run

Batch jobs and run batches remotely across a distributed pool of machines.

canary dist run [-h] [-w] [-f file] [-o option] [-k expression] [--owner OWNERS] [-p expression] [--regex regex]
            [--tag TAG] [--only {changed,not_pass,failed,not_run,all}] [--fail-fast] [-P {permissive,pedantic}]
            [--copy-all-resources] [--empty-ok] [-s CONSOLE_STYLE] [--view key=value] [--workers N]
            [--timeout type=T] [--no-incremental] [--server-url URL] [--tags TAGS] [--batch-width N]
            [--batch-count N] [--batch-duration T] [-E <variables>|ALL]
            ...

Positional arguments

pathspec [–] [user args…]

Test file[s] or directories to search. See ‘canary help –pathspec’ for help on the path specification

Optional arguments

-h, --help

show this help message and exit

-w

Remove test execution directory, if it exists [default: None]

-f file

Read test paths from a json or yaml file. See ‘canary help –pathfile’ for help on the file schema

-o option

Turn option(s) on, such as ‘-o dbg’ or ‘-o intel’

-k expression

Restrict selection to tests matching expression. For example: -k ‘key1 and not key2’. The keyword :all: matches all tests

--owner OWNERS

Restrict selection to tests owned by ‘owner’

-p expression

Restrict selection to tests matching the paramter expression. For example: ‘-p cpus=8’ or ‘-p cpus<8’

--regex regex

Restrict selection to tests containing the regular expression regex in at least 1 of its file assets. regex is a python regular expression, see https://docs.python.org/3/library/re.html

--tag TAG

Name this selection ‘tag’

--only {changed,not_pass,failed,not_run,all}

Which tests to run after selection

all - run all selected tests, even if already passing failed - run only previously failing tests not_run - run tests that have never been executed changed - run tests that whose specs have newer modification time not_pass - run tests whose status is not ‘SUCCESS’ (default)

--fail-fast

Stop after first failed test [default: None]

-P {permissive,pedantic}, --parsing-policy {permissive,pedantic}

If pedantic (default), stop if file parsing errors occur, else ignore parsing errors

--copy-all-resources

Do not link resources to the test directory, only copy [default: None]

--empty-ok

Exit normally when the test set is empty. By default, an empty test set is an error (exit code 7)

-s CONSOLE_STYLE, --style CONSOLE_STYLE

Configure live console display style. Given as key=value pairs: live={yes,no}[yes]: live console updating name={short,long}[short]: print short (default) names or long

--view key=value

Configure the results view. Given as comma separated key=value pairs: • mode={symlink,hardlink,copy,none}[symlink]: how to create the view • only={all,failed,not_pass,passed}[all]: which tests to include • when={on_success,on_failure,always,never}[always]: when to create the view

--workers N

Execute the test session asynchronously using a pool of at most N workers

--timeout type=T

Set the timeout for type (accepts Go’s duration format, eg, 40s, 1h20m, 2h, 4h30m30s). • type=**session**, the timeout T is applied to the entire test session. • type=**multiplier**, the multiplier T is applied to each test’s timeout. • type=**all**, the timeout T is applied to all jobs. • type=**batch**, choices for T are ‘conservative’ to use a conservative estimate for batch timeouts (queue times) or ‘aggressive’. Otherwise, a timeout of T is applied to tests having keyword type. For example, –timeout fast=2 would apply a timeout of 2 seconds to all tests having the ‘fast’ keyword; common types are fast, long, default, and ctest.

--no-incremental

Don’t use the .canary_cache to infer job runtimes

--server-url URL

Distributed pool server location (URL). Defaults to CANARY_DIST_SERVER_URL environment variable, if defined.

--tags TAGS

Only run on machines matching all tags (comma separated list of tags)

--batch-width N

Width of job batches (in CPUs) [default: 8]

--batch-count N

Number of job batches [default: auto]

--batch-duration T

Approximate test batch duration in seconds [default: 10m]

-E <variables>|ALL, --export <variables>|ALL

Identify which environment variables from the submission environment are propagated to the remote host. By default, no variables are propagated. –export=ALL: All environment variables will be propagated. –export=<variables>: Comma separated list of variables to propagate. Environment variable names may be specified to propagate the current value (e.g. ‘–export=SPAM’) or specific values may be exported (e.g. ‘–export=SPAM=eggs’). If the variable LOADEDMODULES is exported, the the modules will be explicitly loaded on the remote host.

canary dist exec

canary dist exec [-h] [--workers WORKERS] --workspace DIST_WORKSPACE

Optional arguments

-h, --help

show this help message and exit

--workers WORKERS

Run tests in batch using this many workers

--workspace DIST_WORKSPACE

The batch’s workspace