toil.test¶
Base testing class for Toil.
Submodules¶
Attributes¶
Classes¶
A common base class for Toil tests. |
|
A Toil test that runs a user script on a minimal cluster of appliance containers. |
Functions¶
|
Return a string representing a temporary file, that must be manually deleted. |
|
Use as a decorator before test classes or methods to run only if the given |
|
Decorate classes or methods that depend on any features from rsync version 3.0.0+. |
|
Use as a decorator before test classes or methods to run only if we are meant to talk to the Internet. |
|
Use as a decorator before test classes or methods to run only if AWS S3 is usable. |
|
Use as a decorator before test classes or methods to run only if AWS EC2 is usable. |
|
Use as a decorator before test classes or methods to run only if AWS Batch |
|
Use as a decorator before test classes or methods to run only if Google |
|
Use as a decorator before test classes or methods to run only if we have a Google Cloud project set. |
|
Use as a decorator before test classes or methods to run only if GridEngine is installed. |
|
Use as a decorator before test classes or methods to run only if PBS/Torque is installed. |
|
Use as a decorator before test classes or methods to run only if Kubernetes is installed. |
|
Use as a decorator before test classes or methods to run only if Kubernetes is installed and configured. |
|
Use as a decorator before test classes or methods to run only if Mesos is installed. |
|
Use as a decorator before test classes or methods to run only if Slurm is installed. |
|
Use a decorator before test classes or methods to run only if the HTCondor is installed. |
|
Use as a decorator before test classes or methods to only run them if LSF is installed. |
|
Use as a test decorator to run only if java is installed. |
|
Use as a decorator before test classes or methods to only run them if |
|
Use as a decorator before test classes or methods to only run them if |
|
Use as a decorator before test classes or methods to only run them if |
|
Use as a decorator before test classes or methods to only run them if |
|
Use as a decorator before test classes or methods to only run them if |
|
Use as a decorator before test classes or methods to only run them if PyNaCl is installed |
|
Use as a decorator before test classes or methods to only run them if CWLTool is installed |
|
Use as a decorator before test classes or methods to only run them if miniwdl is installed |
|
Use as a decorator before test classes or methods to only run them if Connexion is installed. |
|
Use as a decorator before test classes or methods to run only if RabbitMQ is set up to take Celery jobs. |
|
Use as a decorator before test classes or methods to run only if a WES |
|
Use as a decorator before test classes or methods to only run them if |
|
Use as a decorator before test classes or methods to only run them if |
|
Use this to decorate integration tests so as to skip them during regular builds. |
|
Use this decorator to identify tests that are slow and not critical. |
|
Use to limit the execution time of a function. |
|
This method dynamically generates test methods using the generalMethod as a template. Each |
Package Contents¶
- toil.test.logger¶
- class toil.test.ToilTest(methodName='runTest')[source]¶
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.
- classmethod setUpClass()[source]¶
Hook method for setting up class fixture before running tests in the class.
- Return type:
None
- classmethod tearDownClass()[source]¶
Hook method for deconstructing the class fixture after running all tests in the class.
- Return type:
None
- setUp()[source]¶
Hook method for setting up the test fixture before exercising it.
- Return type:
None
- toil.test.MT¶
- toil.test.get_temp_file(suffix='', rootDir=None)[source]¶
Return a string representing a temporary file, that must be manually deleted.
- toil.test.needs_env_var(var_name, comment=None)[source]¶
Use as a decorator before test classes or methods to run only if the given environment variable is set. Can include a comment saying what the variable should be set to.
- toil.test.needs_rsync3(test_item)[source]¶
Decorate classes or methods that depend on any features from rsync version 3.0.0+.
Necessary because
utilsTest.testAWSProvisionerUtils()
uses option –protect-args which is only available in rsync 3- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_online(test_item)[source]¶
Use as a decorator before test classes or methods to run only if we are meant to talk to the Internet.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_aws_s3(test_item)[source]¶
Use as a decorator before test classes or methods to run only if AWS S3 is usable.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_aws_ec2(test_item)[source]¶
Use as a decorator before test classes or methods to run only if AWS EC2 is usable.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_aws_batch(test_item)[source]¶
Use as a decorator before test classes or methods to run only if AWS Batch is usable.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_google_storage(test_item)[source]¶
Use as a decorator before test classes or methods to run only if Google Cloud is installed and we ought to be able to access public Google Storage URIs.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_google_project(test_item)[source]¶
Use as a decorator before test classes or methods to run only if we have a Google Cloud project set.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_gridengine(test_item)[source]¶
Use as a decorator before test classes or methods to run only if GridEngine is installed.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_torque(test_item)[source]¶
Use as a decorator before test classes or methods to run only if PBS/Torque is installed.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_kubernetes_installed(test_item)[source]¶
Use as a decorator before test classes or methods to run only if Kubernetes is installed.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_kubernetes(test_item)[source]¶
Use as a decorator before test classes or methods to run only if Kubernetes is installed and configured.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_mesos(test_item)[source]¶
Use as a decorator before test classes or methods to run only if Mesos is installed.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_slurm(test_item)[source]¶
Use as a decorator before test classes or methods to run only if Slurm is installed.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_htcondor(test_item)[source]¶
Use a decorator before test classes or methods to run only if the HTCondor is installed.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_lsf(test_item)[source]¶
Use as a decorator before test classes or methods to only run them if LSF is installed.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_java(test_item)[source]¶
Use as a test decorator to run only if java is installed.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_docker(test_item)[source]¶
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
- toil.test.needs_singularity(test_item)[source]¶
Use as a decorator before test classes or methods to only run them if singularity is installed.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_singularity_or_docker(test_item)[source]¶
Use as a decorator before test classes or methods to only run them if docker is installed and docker-based tests are enabled, or if Singularity is installed.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_local_cuda(test_item)[source]¶
Use as a decorator before test classes or methods to only run them if a CUDA setup legible to cwltool (i.e. providing userspace nvidia-smi) is present.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_docker_cuda(test_item)[source]¶
Use as a decorator before test classes or methods to only run them if a CUDA setup is available through Docker.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_encryption(test_item)[source]¶
Use as a decorator before test classes or methods to only run them if PyNaCl is installed and configured.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_cwl(test_item)[source]¶
Use as a decorator before test classes or methods to only run them if CWLTool is installed and configured.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_wdl(test_item)[source]¶
Use as a decorator before test classes or methods to only run them if miniwdl is installed and configured.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_server(test_item)[source]¶
Use as a decorator before test classes or methods to only run them if Connexion is installed.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_celery_broker(test_item)[source]¶
Use as a decorator before test classes or methods to run only if RabbitMQ is set up to take Celery jobs.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_wes_server(test_item)[source]¶
Use as a decorator before test classes or methods to run only if a WES server is available to run against.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_local_appliance(test_item)[source]¶
Use as a decorator before test classes or methods to only run them if the Toil appliance Docker image is downloaded.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.needs_fetchable_appliance(test_item)[source]¶
Use as a decorator before test classes or methods to only run them if the Toil appliance Docker image is able to be downloaded from the Internet.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.integrative(test_item)[source]¶
Use this to decorate integration tests so as to skip them during regular builds.
We define integration tests as A) involving other, non-Toil software components that we develop and/or B) having a higher cost (time or money).
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.slow(test_item)[source]¶
Use this decorator to identify tests that are slow and not critical. Skip if TOIL_TEST_QUICK is true.
- Parameters:
test_item (MT)
- Return type:
MT
- toil.test.methodNamePartRegex¶
- toil.test.timeLimit(seconds)[source]¶
Use to limit the execution time of a function.
Raises an exception if the execution of the function takes more than the specified amount of time. See <http://stackoverflow.com/a/601168>.
- Parameters:
seconds (int) – maximum allowable time, in seconds
- Return type:
collections.abc.Generator[None, None, None]
>>> import time >>> with timeLimit(2): ... time.sleep(1) >>> import time >>> with timeLimit(1): ... time.sleep(2) Traceback (most recent call last): ... RuntimeError: Timed out
- toil.test.make_tests(generalMethod, targetClass, **kwargs)[source]¶
This method dynamically generates test methods using the generalMethod as a template. Each generated function is the result of a unique combination of parameters applied to the generalMethod. Each of the parameters has a corresponding string that will be used to name the method. These generated functions are named in the scheme: test_[generalMethodName]___[ firstParamaterName]_[someValueName]__[secondParamaterName]_…
The arguments following the generalMethodName should be a series of one or more dictionaries of the form {str : type, …} where the key represents the name of the value. The names will be used to represent the permutation of values passed for each parameter in the generalMethod.
The generated method names will list the parameters in lexicographic order by parameter name.
- Parameters:
generalMethod – A method that will be parameterized with values passed as kwargs. Note that the generalMethod must be a regular method.
targetClass – This represents the class to which the generated test methods will be bound. If no targetClass is specified the class of the generalMethod is assumed the target.
kwargs – a series of dictionaries defining values, and their respective names where each keyword is the name of a parameter in generalMethod.
>>> class Foo: ... def has(self, num, letter): ... return num, letter ... ... def hasOne(self, num): ... return num
>>> class Bar(Foo): ... pass
>>> make_tests(Foo.has, Bar, num={'one':1, 'two':2}, letter={'a':'a', 'b':'b'})
>>> b = Bar()
Note that num comes lexicographically before letter and so appears first in the generated method names.
>>> assert b.test_has__letter_a__num_one() == b.has(1, 'a')
>>> assert b.test_has__letter_b__num_one() == b.has(1, 'b')
>>> assert b.test_has__letter_a__num_two() == b.has(2, 'a')
>>> assert b.test_has__letter_b__num_two() == b.has(2, 'b')
>>> f = Foo()
>>> hasattr(f, 'test_has__num_one__letter_a') # should be false because Foo has no test methods False
- class toil.test.ApplianceTestSupport(methodName='runTest')[source]¶
Bases:
ToilTest
A Toil test that runs a user script on a minimal cluster of appliance containers.
i.e. one leader container and one worker container.
- class Appliance(outer, mounts, cleanMounts=False)[source]¶
Bases:
toil.lib.threading.ExceptionalThread
A thread whose join() method re-raises exceptions raised during run(). While join() is idempotent, the exception is only during the first invocation of join() that successfully joined the thread. If join() times out, no exception will be re reraised even though an exception might already have occurred in run().
When subclassing this thread, override tryRun() instead of run().
>>> def f(): ... assert 0 >>> t = ExceptionalThread(target=f) >>> t.start() >>> t.join() Traceback (most recent call last): ... AssertionError
>>> class MyThread(ExceptionalThread): ... def tryRun( self ): ... assert 0 >>> t = MyThread() >>> t.start() >>> t.join() Traceback (most recent call last): ... AssertionError
- Parameters:
outer (ApplianceTestSupport)
cleanMounts (bool)
- lock¶
- outer¶
- mounts¶
- cleanMounts¶
- containerName¶
- popen: subprocess.Popen[bytes] | None = None¶
- __exit__(exc_type, exc_val, exc_tb)[source]¶
- Parameters:
exc_type (type[BaseException])
exc_val (Exception)
exc_tb (Any)
- Return type:
Literal[False]
- deployScript(path, packagePath, script)[source]¶
Deploy a Python module on the appliance.
- Parameters:
path (str) – the path (absolute or relative to the WORDIR of the appliance container) to the root of the package hierarchy where the given module should be placed. The given directory should be on the Python path.
packagePath (str) – the desired fully qualified module name (dotted form) of the module
script (str|callable) – the contents of the Python module. If a callable is given, its source code will be extracted. This is a convenience that lets you embed user scripts into test code as nested function.
- Return type:
None
- class LeaderThread(outer, mounts, cleanMounts=False)[source]¶
Bases:
Appliance
A thread whose join() method re-raises exceptions raised during run(). While join() is idempotent, the exception is only during the first invocation of join() that successfully joined the thread. If join() times out, no exception will be re reraised even though an exception might already have occurred in run().
When subclassing this thread, override tryRun() instead of run().
>>> def f(): ... assert 0 >>> t = ExceptionalThread(target=f) >>> t.start() >>> t.join() Traceback (most recent call last): ... AssertionError
>>> class MyThread(ExceptionalThread): ... def tryRun( self ): ... assert 0 >>> t = MyThread() >>> t.start() >>> t.join() Traceback (most recent call last): ... AssertionError
- Parameters:
outer (ApplianceTestSupport)
cleanMounts (bool)
- class WorkerThread(outer, mounts, numCores)[source]¶
Bases:
Appliance
A thread whose join() method re-raises exceptions raised during run(). While join() is idempotent, the exception is only during the first invocation of join() that successfully joined the thread. If join() times out, no exception will be re reraised even though an exception might already have occurred in run().
When subclassing this thread, override tryRun() instead of run().
>>> def f(): ... assert 0 >>> t = ExceptionalThread(target=f) >>> t.start() >>> t.join() Traceback (most recent call last): ... AssertionError
>>> class MyThread(ExceptionalThread): ... def tryRun( self ): ... assert 0 >>> t = MyThread() >>> t.start() >>> t.join() Traceback (most recent call last): ... AssertionError
- Parameters:
outer (ApplianceTestSupport)
numCores (int)
- numCores¶