buildtest.buildsystem.base
¶
BuilderBase class is an abstract class that defines common functions for any types of builders. Each type schema (script, compiler, spack) is implemented as separate Builder which extends BuilderBase class.
Module Contents¶
Classes¶
The BuilderBase is an abstract class that implements common functions used for building and running test. |
- class buildtest.buildsystem.base.BuilderBase(name, recipe, buildspec, executor, buildexecutor, testdir)[source]¶
Bases:
abc.ABC
The BuilderBase is an abstract class that implements common functions used for building and running test.
buildtest will create a builder object which resembles a test. The builder will contains metadata that is unique to each builder that is captured in the report file upon completion of test.
- job¶
Stores Job Data for batch job
- buildexecutor (obj
buildtest.executors.setup.BuildExecutor): instance of BuildExecutor class used for accessing executors
- shebang¶
used for writing shebang line in test. This can vary based on shell type or if
shebang
property is specified- Type
- shell (obj
buildtest.utils.shell.Shell): An instance of Shell class used for detecting shell type
The BuilderBase provides common functions for any builder. The builder is an instance of BuilderBase. The initializer method will setup the builder attributes based on input test by
name
parameter.- Parameters
name (str) – Name of test in buildspec recipe
recipe (str) – The loaded test section from the buildspec file
buildspec (str) – Full path to buildspec file
buildexecutor (
buildtest.executors.setup.BuildExecutor
) – An instance of BuildExecutor class used for accessing executorstestdir (str) – Test directory where tests are written. Must be full path on filesystem.
- _set_metadata_values(self)[source]¶
This method sets
self.metadata
that contains metadata for each builder object.
- _generate_unique_id(self)[source]¶
Generate a unique build id using uuid.uuid4().
- Returns
unique test id for the builder
- Return type
- get_test_extension(self)[source]¶
Return the test extension, which depends on the shell type. By default we return sh file extension for all shells except for csh which will return “csh” extension.
- Returns
str: Returns test extension name for generated test.
- _is_local_executor(self)[source]¶
Return True if current builder executor type is LocalExecutor otherwise returns False.
- Returns
returns True if builder is using executor type LocalExecutor otherwise returns False
- Return type
- is_batch_job(self)[source]¶
Return True/False if builder.job attribute is of type Job instance if not returns False. This method indicates if builder has a job submitted to queue
- start(self)[source]¶
Keep internal timer for test using class
buildtest.utils.timer.Timer
. This method will start the timer for builder which is invoked upon running test.
- build(self)[source]¶
This method is responsible for invoking setup, creating test directory and writing test. This method is called from an instance object of this class that does
builder.build()
.
- run(self)[source]¶
Run the test and record the starttime and start timer. We also return the instance object of type BuildTestCommand which is used by Executors for processing output and error
- Returns
If success, the return type is an object of type
buildtest.utils.command.BuildTestCommand
If their is a failure (non-zero) returncode we retry test and if it doesn’t pass we raise exception of
buildtest.exceptions.RuntimeFailure
- starttime(self)[source]¶
This method will record the starttime when job starts execution by using
datetime.datetime.now()
- endtime(self)[source]¶
This method is called upon termination of job, we get current time using
datetime.datetime.now()
and calculate runtime of job
- runtime(self)[source]¶
Calculate runtime of job by calculating delta between endtime and starttime. The unit of measure is seconds.
- success(self)[source]¶
This method is invoked to indicate that builder job is complete after polling job.
- failure(self)[source]¶
This method indicates that builder job is not complete after polling job either job was cancelled by scheduler or job failed to run.
- is_complete(self)[source]¶
If builder completes execution of test this method will return
True
otherwise returnsFalse
. A builder could fail due to job cancellation, failure to submit job or raise exception during the run phase. In those case, this method will returnFalse
.
- is_unknown(self)[source]¶
Returns True if builder state is unknown which is the state if job is still running
- run_command(self)[source]¶
Command used to run the build script. buildtest will change into the stage directory (self.stage_dir) before running the test.
- _build_setup(self)[source]¶
This method is the setup operation to get ready to build test which includes the following:
Creating Test directory and stage directory
Resolve full path to generated test script and build script
Copy all files from buildspec directory to stage directory
- _emit_command(self)[source]¶
This method will return a shell command used to invoke the script that is used for tests that use local executors
- Returns
a list to show generated command used to run test.
Test can be run without any argument with path to script:
/path/to/script.sh
Test can be run with shell name followed by path to script:bash /path/to/script.sh
Test can be run with shell name, shell options and path to script:bash -x /path/to/script.sh
- Return type
- _default_test_variables(self)[source]¶
Return a list of lines inserted in build script that define buildtest specific variables that can be referenced when writing tests. The buildtest variables all start with BUILDTEST_*
- _write_build_script(self)[source]¶
This method will write the content of build script that is run for when invoking the builder run method. Upon creating file we set permission of builder script to 755 so test can be run.
- _write_test(self)[source]¶
This method is responsible for invoking
generate_script
that formulates content of testscript which is implemented in each subclass. Next we write content to file and apply 755 permission on script so it has executable permission.
- sched_init(self)[source]¶
This method will resolve scheduler fields: ‘sbatch’, ‘pbs’, ‘bsub’, ‘cobalt’
- get_slurm_directives(self)[source]¶
Get #SBATCH lines based on
sbatch
property by callingbuildtest.buildsystem.batch.SlurmBatchScript
- get_lsf_directives(self)[source]¶
Get #BSUB lines based on
bsub
property by callingbuildtest.buildsystem.batch.LSFBatchScript
- get_pbs_directives(self)[source]¶
Get #PBS lines based on
pbs
property by callingbuildtest.buildsystem.batch.PBSBatchScript
- get_cobalt_directives(self)[source]¶
Get #COBALT lines based on
cobalt
property by callingbuildtest.buildsystem.batch.CobaltBatchScript
- get_job_directives(self)[source]¶
This method returns a list of lines containing the scheduler directives
- _get_burst_buffer(self, burstbuffer)[source]¶
Get Burst Buffer directives (#BB) lines specified by
BB
property
- _get_data_warp(self, datawarp)[source]¶
Get Cray Data Warp directives (#DW) lines specified by
DW
property.
- _set_execute_perm(self, fname)[source]¶
Set permission to 755 for a given file. The filepath must be an absolute path to file
- _get_environment(self, env)[source]¶
Retrieve a list of environment variables defined in buildspec and return them as list with the shell equivalent command
- Parameters
env (dict) – list of environment variables defined by
env
property in buildspec
- _get_variables(self, variables)[source]¶
Retrieve a list of variables defined in buildspec and return them as list with the shell equivalent command.
- Parameters
variables (dict) – list of variable defined by
vars
property in buildspec
- add_metrics(self)[source]¶
This method will update the metrics field stored in
self.metadata['metrics']
. Themetrics
property can be defined in the buildspdec to assign value to a metrics name based on regular expression, environment or variable assignment.
- post_run_steps(self)[source]¶
This method is called after test is complete. This method will copy files from stage directory such as output, error and test script. We will check state of test and mark job is complete.
- _check_regex(self)[source]¶
This method conducts a regular expression check using re.search with regular expression defined in Buildspec. User must specify an output stream (stdout, stderr) to select when performing regex. In buildtest, this would read the .out or .err file based on stream and run the regular expression to see if there is a match. This method will return a boolean True indicates there is a match otherwise False if
regex
object not defined orre.search
doesn’t find a match.- Returns
Returns True if their is a regex match otherwise returns False.
- Return type
- _returncode_check(self)[source]¶
Check status check of
returncode
field if specified in status property.
- _check_runtime(self)[source]¶
This method will return a boolean (True/False) based on runtime specified in buildspec and check with test runtime. User can specify both min and max, or just specify min or max.