toil.test.src.dockerCheckTest

Classes

ToilTest	A common base class for Toil tests.
DockerCheckTest	Tests checking whether a docker image exists or not.

Functions

checkDockerImageExists(appliance)	Attempt to check a url registryName for the existence of a docker image with a given tag.
parseDockerAppliance(appliance)	Derive parsed registry, image reference, and tag from a docker image string.
retry([intervals, infinite_retries, errors, ...])	Retry a function if it fails with any Exception defined in "errors".
needs_docker(test_item)	Use as a decorator before test classes or methods to only run them if

Module Contents

toil.test.src.dockerCheckTest.checkDockerImageExists(appliance)

Attempt to check a url registryName for the existence of a docker image with a given tag.

Parameters:

appliance (str) – The url of a docker image’s registry (with a tag) of the form: ‘quay.io/<repo_path>:<tag>’ or ‘<repo_path>:<tag>’. Examples: ‘quay.io/ucsc_cgl/toil:latest’, ‘ubuntu:latest’, or ‘broadinstitute/genomes-in-the-cloud:2.0.0’.

Returns:

Raises an exception if the docker image cannot be found or is invalid. Otherwise, it will return the appliance string.

Return type:

str

toil.test.src.dockerCheckTest.parseDockerAppliance(appliance)

Derive parsed registry, image reference, and tag from a docker image string.

Example: “quay.io/ucsc_cgl/toil:latest” Should return: “quay.io”, “ucsc_cgl/toil”, “latest”

If a registry is not defined, the default is: “docker.io” If a tag is not defined, the default is: “latest”

Parameters:

appliance (str) – The full url of the docker image originally specified by the user (or the default). e.g. “quay.io/ucsc_cgl/toil:latest”

Returns:

registryName, imageName, tag

Return type:

Tuple[str, str, str]

toil.test.src.dockerCheckTest.retry(intervals=None, infinite_retries=False, errors=None, log_message=None, prepare=None)

Retry a function if it fails with any Exception defined in “errors”.

Does so every x seconds, where x is defined by a list of numbers (ints or floats) in “intervals”. Also accepts ErrorCondition events for more detailed retry attempts.

Parameters:

• intervals (Optional[List]) – A list of times in seconds we keep retrying until returning failure. Defaults to retrying with the following exponential back-off before failing: 1s, 1s, 2s, 4s, 8s, 16s

• infinite_retries (bool) – If this is True, reset the intervals when they run out. Defaults to: False.

• errors (Optional[Sequence[Union[ErrorCondition, Type[Exception]]]]) –

  A list of exceptions OR ErrorCondition objects to catch and retry on. ErrorCondition objects describe more detailed error event conditions than a plain error. An ErrorCondition specifies: - Exception (required) - Error codes that must match to be retried (optional; defaults to not checking) - A string that must be in the error message to be retried (optional; defaults to not checking) - A bool that can be set to False to always error on this condition.

  If not specified, this will default to a generic Exception.

• log_message (Optional[Tuple[Callable, str]]) – Optional tuple of (“log/print function()”, “message string”) that will precede each attempt.

• prepare (Optional[List[Callable]]) – Optional list of functions to call, with the function’s arguments, between retries, to reset state.

Returns:

The result of the wrapped function or raise.

Return type:

Callable[[Callable[Ellipsis, RT]], Callable[Ellipsis, RT]]

class toil.test.src.dockerCheckTest.ToilTest(methodName='runTest')

Bases: unittest.TestCase

A common base class for Toil tests.

Please have every test case directly or indirectly inherit this one.

When running tests you may optionally set the TOIL_TEST_TEMP environment variable to the path of a directory where you want temporary test files be placed. The directory will be created if it doesn’t exist. The path may be relative in which case it will be assumed to be relative to the project root. If TOIL_TEST_TEMP is not defined, temporary files and directories will be created in the system’s default location for such files and any temporary files or directories left over from tests will be removed automatically removed during tear down. Otherwise, left-over files will not be removed.

setup_method(method)

Parameters:

method (Any)

Return type:

None

classmethod setUpClass()

Hook method for setting up class fixture before running tests in the class.

Return type:

None

classmethod tearDownClass()

Hook method for deconstructing the class fixture after running all tests in the class.

Return type:

None

setUp()

Hook method for setting up the test fixture before exercising it.

Return type:

None

tearDown()

Hook method for deconstructing the test fixture after testing it.

Return type:

None

classmethod awsRegion()

Pick an appropriate AWS region.

Use us-west-2 unless running on EC2, in which case use the region in which the instance is located

Return type:

str

toil.test.src.dockerCheckTest.needs_docker(test_item)

Use as a decorator before test classes or methods to only run them if docker is installed and docker-based tests are enabled.

Parameters:

test_item (MT)

Return type:

MT

class toil.test.src.dockerCheckTest.DockerCheckTest(methodName='runTest')

Bases: toil.test.ToilTest

Tests checking whether a docker image exists or not.

testOfficialUbuntuRepo()

Image exists. This should pass.

testBroadDockerRepo()

Image exists. This should pass.

testBroadDockerRepoBadTag()

Bad tag. This should raise.

testNonexistentRepo()

Bad image. This should raise.

testToilQuayRepo()

Image exists. Should pass.

testBadQuayRepoNTag()

Bad repo and tag. This should raise.

testBadQuayRepo()

Bad repo. This should raise.

testBadQuayTag()

Bad tag. This should raise.

testGoogleRepo()

Image exists. Should pass.

testBadGoogleRepo()

Bad repo and tag. This should raise.

testApplianceParser()

Test that a specified appliance is parsed correctly.