Buildspec Overview¶
What is a buildspec?¶
In buildtest, we refer to buildspec as a YAML file that defines your test that buildtest will parse using the provided schemas and build a shell script from the buildspec file. Every buildspec is validated with a global schema which you can find more if you click here.
Example¶
Let’s start off with a simple example that declares two variables X and Y and prints the sum of X+Y.
version: "1.0"
buildspecs:
add_numbers:
type: script
executor: generic.local.bash
description: Add X+Y
tags: [tutorials]
vars:
X: 1
Y: 2
run: echo "$X+$Y=" $(($X+$Y))
buildtest will validate the entire file with global.schema.json, the schema
requires version and buildspec in order to validate file. The buildspec
is where you define each test. The name of the test is add_numbers.
The test requires a type field which is the sub-schema used to validate the
test section. In this example type: script informs buildtest to use the Script Schema
when validating test section.
Each subschema has a list of field attributes that are supported, for example the
fields: type, executor, vars and run are all valid fields supported
by the script schema. The version field informs which version of subschema to use.
Currently all sub-schemas are at version 1.0 where buildtest will validate
with a schema script-v1.0.schema.json. In future, we can support multiple versions
of subschema for backwards compatibility.
Let’s look at a more interesting example, shown below is a multi line run example using the script schema with test name called systemd_default_target, shown below is the content of test:
version: "1.0"
buildspecs:
systemd_default_target:
executor: generic.local.bash
type: script
tags: [system]
description: check if default target is multi-user.target
run: |
if [ "multi-user.target" == `systemctl get-default` ]; then
echo "multi-user is the default target";
exit 0
fi
echo "multi-user is not the default target";
exit 1
The test name systemd_default_target defined in buildspec section is
validated with the following pattern "^[A-Za-z_][A-Za-z0-9_]*$". This test
will use the executor generic.local.bash which means it will use the Local Executor
with an executor name bash defined in the buildtest settings. The default
buildtest settings will provide a bash executor as follows:
system:
generic:
hostnames: ["localhost"]
executors:
local:
bash:
description: submit jobs on local machine using bash shell
shell: bash
The shell: bash indicates this executor will use bash to run the test scripts.
To reference this executor use the format <system>.<type>.<name> in this case generic.local.bash
refers to bash executor.
The description field is an optional key that can be used to provide a brief
summary of the test. In this example we can a full multi-line run section, this
is achieved in YAML using run: | followed by content of run section tab indented
2 spaces.
Script Schema¶
The script schema is used for writing simple scripts (bash, sh, python) in Buildspec.
To use this schema you must set type: script. The run field is responsible
for writing the content of test.
Shown below is schema header for script-v1.0.schema.json.
{
"$id": "script-v1.0.schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "script schema version 1.0",
"description": "The script schema is of ``type: script`` in sub-schema which is used for running shell scripts",
"type": "object",
"required": ["type", "run", "executor"],
"additionalProperties": false,
The "type": "object" means sub-schema is a JSON object
where we define a list of key/value pair. The "required" field specifies a list of
fields that must be specified in order to validate the Buildspec. In this example, type, run, and executor
are required fields. The additionalProperties: false informs schema to reject
any extra properties not defined in the schema.
The executor key is required for all sub-schemas which instructs buildtest
which executor to use when running the test. The executors are defined in
Configuring buildtest. In our first example we define variables using the
vars property which is a Key/Value pair for variable assignment.
The run section is required for script schema which defines the content of
the test script.
For more details on script schema see schema docs at https://buildtesters.github.io/buildtest/
Declaring Environment Variables¶
You can define environment variables using the env property, this is compatible
with shells: bash, sh, zsh, csh and tcsh. It does not work with
shell: python. In example below we declare three tests using environment
variable with default shell (bash), csh, and tcsh
version: "1.0"
buildspecs:
bash_env_variables:
executor: generic.local.bash
description: Declare environment variables in default shell (bash)
type: script
env:
FIRST_NAME: avocado
LAST_NAME: dinosaur
tags: [tutorials]
run: |
hostname
whoami
echo $USER
printf "${FIRST_NAME} ${LAST_NAME}\n"
csh_env_declaration:
executor: generic.local.csh
type: script
description: "csh shell example to declare environment variables"
shell: /bin/csh
tags: [tutorials]
env:
SHELL_NAME: "csh"
run: echo "This is running $SHELL_NAME"
tcsh_env_declaration:
executor: generic.local.csh
type: script
description: "tcsh shell example to declare environment variables"
shell: /bin/tcsh
tags: [tutorials]
env:
path: "/usr/local/bin:$PATH"
run: echo $path
This test can be run by issuing the following command: buildtest build -b tutorials/environment.yml.
If we inspect one of the test script we will see that buildtest generates a build script that invokes the test using the
shell wrapper /bin/csh for the csh test and gets the returncode.
#!/bin/bash
############# START VARIABLE DECLARATION ########################
export BUILDTEST_TEST_NAME=csh_env_declaration
export BUILDTEST_TEST_ROOT=/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.csh/environment/csh_env_declaration/0
export BUILDTEST_BUILDSPEC_DIR=/Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials
export BUILDTEST_STAGE_DIR=/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.csh/environment/csh_env_declaration/0/stage
export BUILDTEST_TEST_ID=501ec5d3-e614-4ae8-9c1e-4849ce340c76
############# END VARIABLE DECLARATION ########################
# source executor startup script
source /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/executor/generic.local.csh/before_script.sh
# Run generated script
/bin/csh /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.csh/environment/csh_env_declaration/0/stage/csh_env_declaration.csh
# Get return code
returncode=$?
# Exit with return code
exit $returncode
This generated test looks something like this
#!/bin/csh
# Declare environment variables
setenv SHELL_NAME csh
# Content of run section
echo "This is running $SHELL_NAME"
Environment variables are defined using export in bash, sh, zsh while csh and
tcsh use setenv.
Declaring Variables¶
Variables can be defined using vars property, this is compatible with all shells
except for python. The variables are defined slightly different in csh, tcsh as pose
to bash, sh, and zsh. In example below we define tests with bash and csh.
In YAML strings can be specified with or without quotes however in bash, variables
need to be enclosed in quotes " if you are defining a multi word string (name="First Last").
If you need define a literal string it is recommended
to use the literal block | that is a special character in YAML.
If you want to specify " or ' in string you can use the escape character
\ followed by any of the special character. In example below we define
several variables such as X, Y that contain numbers, variable literalstring
is a literal string processed by YAML. The variable singlequote and doublequote
defines a variable with the special character ' and ". The variables
current_user and num_files store result of a shell command. This can
be done using var=$(<command>) or var=`<command>` where <command> is
a Linux command.
version: "1.0"
buildspecs:
variables_bash:
type: script
executor: generic.local.bash
description: Declare shell variables in bash
tags: [tutorials]
vars:
X: 1
Y: 2
literalstring: |
"this is a literal string ':' "
singlequote: \'singlequote\'
doublequote: \"doublequote\"
current_user: "$(whoami)"
num_files: "`find $HOME -type f -maxdepth 1 | wc -l`"
run: |
echo "$X+$Y="$(($X+$Y))
echo $literalstring
echo $singlequote
echo $doublequote
echo "current user:" $current_user
echo "number of files:" $num_files
Next we build this test by running buildtest build -b $BUILDTEST_ROOT/tutorials/vars.yml.
$ buildtest build -b $BUILDTEST_ROOT/tutorials/vars.yml
User: docs
Hostname: build-14673784-project-280831-buildtest
Platform: Linux
Current Time: 2021/09/09 15:54:50
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest
buildtest version: 0.11.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.11.0/bin/python
python version: 3.7.9
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest build -b /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/vars.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+-------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+=================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/vars.yml |
+-------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/vars.yml: VALID
Total builder objects created: 1
builders: [variables_bash/98b07db8]
name id description buildspecs
-------------- -------- ------------------------------- -----------------------------------------------------------------------------------------------
variables_bash 98b07db8 Declare shell variables in bash /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/vars.yml
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
----------------+----------+--------+--------------------+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------
variables_bash | 98b07db8 | script | generic.local.bash | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/98b07db8/variables_bash_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
variables_bash/98b07db8: completed with returncode: 0
variables_bash/98b07db8: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/98b07db8/variables_bash.out
variables_bash/98b07db8: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/98b07db8/variables_bash.err
______________________________
Launching test: variables_bash
Test ID: 98b07db8-9b3e-4ff0-b526-1ebcebbc3a1e
Executor Name: generic.local.bash
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/98b07db8/variables_bash_build.sh
+----------------------+
| Stage: Test Summary |
+----------------------+
name | id | executor | status | returncode_match | regex_match | runtime_match | returncode | runtime
----------------+----------+--------------------+----------+--------------------+---------------+-----------------+--------------+-----------
variables_bash | 98b07db8 | generic.local.bash | PASS | N/A | N/A | N/A | 0 | 0.012987
Passed Tests: 1/1 Percentage: 100.000%
Failed Tests: 0/1 Percentage: 0.000%
Writing Logfile to: /tmp/buildtest_8xn_louq.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest.log
Let’s check the generated script from the previous build, you can run buildtest inspect query -o variables_bash where
-o refers to output file for testname variables_bash. Take note of the output file we
$ buildtest inspect query -o variables_bash
______________________________ variables_bash (ID: 98b07db8-9b3e-4ff0-b526-1ebcebbc3a1e) ______________________________
executor: generic.local.bash
description: Declare shell variables in bash
state: PASS
returncode: 0
runtime: 0.012987
starttime: 2021/09/09 15:54:50
endtime: 2021/09/09 15:54:50
************************* Start of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/98b07db8/variables_bash.out *************************
1+2=3
this is a literal string ':'
'singlequote'
"doublequote"
current user: docs
number of files: 4
************************* End of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/98b07db8/variables_bash.out *************************
Test Status¶
buildtest will record state of each test which can be PASS or FAIL. By default a 0 exit code is
PASS and everything else is a FAIL. The status property can be used to determine how test will report its state.
Currently, we can match state based on returncode, runtime, or
regular expression.
Return Code Matching¶
buildtest can report PASS/FAIL based on returncode, by default a 0 exit code is PASS
and everything else is FAIL. The returncode can be a list of exit codes to match.
In this example we have four tests called exit1_fail, exit1_pass,
returncode_list_mismatch and returncode_int_match. We expect exit1_fail and
returncode_mismatch to FAIL while exit1_pass and returncode_int_match
will PASS.
version: "1.0"
buildspecs:
exit1_fail:
executor: generic.local.sh
type: script
description: exit 1 by default is FAIL
tags: [tutorials, fail]
run: exit 1
exit1_pass:
executor: generic.local.sh
type: script
description: report exit 1 as PASS
run: exit 1
tags: [tutorials, pass]
status:
returncode: [1]
returncode_list_mismatch:
executor: generic.local.sh
type: script
description: exit 2 failed since it failed to match returncode 1
run: exit 2
tags: [tutorials, fail]
status:
returncode: [1, 3]
returncode_int_match:
executor: generic.local.sh
type: script
description: exit 128 matches returncode 128
run: exit 128
tags: [tutorials, pass]
status:
returncode: 128
Let’s build this test and pay close attention to the status column in output.
$ buildtest build -b tutorials/pass_returncode.yml
User: docs
Hostname: build-14673784-project-280831-buildtest
Platform: Linux
Current Time: 2021/09/09 15:54:51
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest
buildtest version: 0.11.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.11.0/bin/python
python version: 3.7.9
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest build -b tutorials/pass_returncode.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+============================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml |
+------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml: VALID
Total builder objects created: 4
builders: [exit1_fail/53c2663d, exit1_pass/97c4d576, returncode_list_mismatch/31d04ee2, returncode_int_match/278c66df]
name id description buildspecs
------------------------ -------- --------------------------------------------------- ----------------------------------------------------------------------------------------------------------
exit1_fail 53c2663d exit 1 by default is FAIL /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml
exit1_pass 97c4d576 report exit 1 as PASS /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml
returncode_list_mismatch 31d04ee2 exit 2 failed since it failed to match returncode 1 /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml
returncode_int_match 278c66df exit 128 matches returncode 128 /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
--------------------------+----------+--------+------------------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
exit1_fail | 53c2663d | script | generic.local.sh | ['tutorials', 'fail'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/exit1_fail/53c2663d/exit1_fail_build.sh
exit1_pass | 97c4d576 | script | generic.local.sh | ['tutorials', 'pass'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/exit1_pass/97c4d576/exit1_pass_build.sh
returncode_list_mismatch | 31d04ee2 | script | generic.local.sh | ['tutorials', 'fail'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/returncode_list_mismatch/31d04ee2/returncode_list_mismatch_build.sh
returncode_int_match | 278c66df | script | generic.local.sh | ['tutorials', 'pass'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/returncode_int_match/278c66df/returncode_int_match_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
exit1_pass/97c4d576: completed with returncode: 1
exit1_pass/97c4d576: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/exit1_pass/97c4d576/exit1_pass.out
exit1_pass/97c4d576: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/exit1_pass/97c4d576/exit1_pass.err
exit1_pass/97c4d576: Checking returncode - 1 is matched in list [1]
returncode_list_mismatch/31d04ee2: completed with returncode: 2
returncode_list_mismatch/31d04ee2: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/returncode_list_mismatch/31d04ee2/returncode_list_mismatch.out
returncode_list_mismatch/31d04ee2: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/returncode_list_mismatch/31d04ee2/returncode_list_mismatch.err
returncode_list_mismatch/31d04ee2: Checking returncode - 2 is matched in list [1, 3]
exit1_fail/53c2663d: completed with returncode: 1
exit1_fail/53c2663d: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/exit1_fail/53c2663d/exit1_fail.out
exit1_fail/53c2663d: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/exit1_fail/53c2663d/exit1_fail.err
returncode_int_match/278c66df: completed with returncode: 128
returncode_int_match/278c66df: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/returncode_int_match/278c66df/returncode_int_match.out
returncode_int_match/278c66df: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/returncode_int_match/278c66df/returncode_int_match.err
returncode_int_match/278c66df: Checking returncode - 128 is matched in list [128]
______________________________
Launching test: exit1_fail
Test ID: 53c2663d-6290-4715-bb97-eb2f8b99ff86
Executor Name: generic.local.sh
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/exit1_fail/53c2663d/exit1_fail_build.sh
______________________________
Launching test: exit1_pass
Test ID: 97c4d576-0e99-4f02-abdc-aa8b54802834
Executor Name: generic.local.sh
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/exit1_pass/97c4d576/exit1_pass_build.sh
______________________________
Launching test: returncode_list_mismatch
Test ID: 31d04ee2-707e-441a-ad5e-a3cdb862860e
Executor Name: generic.local.sh
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/returncode_list_mismatch/31d04ee2/returncode_list_mismatch_build.sh
______________________________
Launching test: returncode_int_match
Test ID: 278c66df-fc80-4a90-9968-fc74811c5f7f
Executor Name: generic.local.sh
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/pass_returncode/returncode_int_match/278c66df/returncode_int_match_build.sh
+----------------------+
| Stage: Test Summary |
+----------------------+
name | id | executor | status | returncode_match | regex_match | runtime_match | returncode | runtime
--------------------------+----------+------------------+----------+--------------------+---------------+-----------------+--------------+-----------
exit1_fail | 53c2663d | generic.local.sh | FAIL | N/A | N/A | N/A | 1 | 0.023217
exit1_pass | 97c4d576 | generic.local.sh | PASS | True | False | False | 1 | 0.020955
returncode_list_mismatch | 31d04ee2 | generic.local.sh | FAIL | False | False | False | 2 | 0.019587
returncode_int_match | 278c66df | generic.local.sh | PASS | True | False | False | 128 | 0.019961
Passed Tests: 2/4 Percentage: 50.000%
Failed Tests: 2/4 Percentage: 50.000%
Writing Logfile to: /tmp/buildtest_s4hf3x_d.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest.log
The returncode field can be an integer or list of integers but it may not accept
duplicate values. If you specify a list of exit codes, buildtest will check actual returncode
with list of expected returncodes specified by returncode field.
Shown below are examples of invalid returncodes:
# empty list is not allowed
returncode: []
# floating point is not accepted in list
returncode: [1, 1.5]
# floating point not accepted
returncode: 1.5
# duplicates are not allowed
returncode: [1, 2, 5, 5]
Passing Test based on regular expression¶
buildtest can configure PASS/FAIL of test based on regular expression on output or error file. This can be useful if you are expecting a certain output from the test as pose to returncode check.
In this example we introduce, the regex field which is part of status that expects
a regular expression via exp. The stream property must be stdout or stderr which indicates
buildtest will read output or error file and apply regular expression. If there is a match, buildtest will record the
test state as PASS otherwise it will be a FAIL. In this example, we have two tests that will apply regular expression
on output file.
version: "1.0"
buildspecs:
status_regex_pass:
executor: generic.local.bash
type: script
tags: [system]
description: Pass test based on regular expression
run: echo "PASS"
status:
regex:
stream: stdout
exp: "^(PASS)$"
status_regex_fail:
executor: generic.local.bash
type: script
tags: [system]
description: Pass test based on regular expression
run: echo "FAIL"
status:
regex:
stream: stdout
exp: "^(123FAIL)$"
Now if we run this test, we will see first test will pass while second one will fail even though the returncode is a 0. Take a close look at the status property
$ buildtest build -b tutorials/status_regex.yml
User: docs
Hostname: build-14673784-project-280831-buildtest
Platform: Linux
Current Time: 2021/09/09 15:54:51
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest
buildtest version: 0.11.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.11.0/bin/python
python version: 3.7.9
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest build -b tutorials/status_regex.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+---------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+=========================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/status_regex.yml |
+---------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/status_regex.yml: VALID
Total builder objects created: 2
builders: [status_regex_pass/572fadd5, status_regex_fail/099fdf40]
name id description buildspecs
----------------- -------- ------------------------------------- -------------------------------------------------------------------------------------------------------
status_regex_pass 572fadd5 Pass test based on regular expression /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/status_regex.yml
status_regex_fail 099fdf40 Pass test based on regular expression /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/status_regex.yml
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
-------------------+----------+--------+--------------------+------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
status_regex_pass | 572fadd5 | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_pass/572fadd5/status_regex_pass_build.sh
status_regex_fail | 099fdf40 | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_fail/099fdf40/status_regex_fail_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
status_regex_fail/099fdf40: completed with returncode: 0
status_regex_fail/099fdf40: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_fail/099fdf40/status_regex_fail.out
status_regex_fail/099fdf40: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_fail/099fdf40/status_regex_fail.err
status_regex_fail/099fdf40: performing regular expression - '^(123FAIL)$' on file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_fail/099fdf40/status_regex_fail.out with regular expression
status_regex_fail/099fdf40: Regular Expression Match - Failed!
status_regex_pass/572fadd5: completed with returncode: 0
status_regex_pass/572fadd5: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_pass/572fadd5/status_regex_pass.out
status_regex_pass/572fadd5: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_pass/572fadd5/status_regex_pass.err
status_regex_pass/572fadd5: performing regular expression - '^(PASS)$' on file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_pass/572fadd5/status_regex_pass.out with regular expression
status_regex_pass/572fadd5: Regular Expression Match - Success!
______________________________
Launching test: status_regex_pass
Test ID: 572fadd5-b0eb-4df3-aa2f-d878aeb2522d
Executor Name: generic.local.bash
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_pass/572fadd5/status_regex_pass_build.sh
______________________________
Launching test: status_regex_fail
Test ID: 099fdf40-fac6-4581-ab96-780328380d58
Executor Name: generic.local.bash
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_fail/099fdf40/status_regex_fail_build.sh
+----------------------+
| Stage: Test Summary |
+----------------------+
name | id | executor | status | returncode_match | regex_match | runtime_match | returncode | runtime
-------------------+----------+--------------------+----------+--------------------+---------------+-----------------+--------------+-----------
status_regex_pass | 572fadd5 | generic.local.bash | PASS | False | True | False | 0 | 0.025703
status_regex_fail | 099fdf40 | generic.local.bash | FAIL | False | False | False | 0 | 0.025702
Passed Tests: 1/2 Percentage: 50.000%
Failed Tests: 1/2 Percentage: 50.000%
Writing Logfile to: /tmp/buildtest_veh1ta6l.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest.log
Passing Test based on runtime¶
buildtest can determine state of test based on runtime property which is part of
status object. This can be used if you want to control how test PASS or FAIL based on
execution time of test. In example below we have five tests that make use of runtime property
for passing a test. The runtime property support min and max property that can mark test
pass based on minimum and maximum runtime. A test will pass if it’s execution time is greater than min
time and less than max time. If min is specified without max property the upperbound is not set, likewise
max without min will pass if test is less than max time. The lower bound is not set, but test runtime
will be greater than 0 sec.
In test timelimit_min, we sleep for 2 seconds and it will pass because minimum runtime is 1.0 seconds. Similarly, timelimit_max will pass because we sleep for 2 seconds with a max time of 5.0.
version: "1.0"
buildspecs:
timelimit_min_max:
type: script
executor: generic.local.sh
description: "Run a sleep job for 2 seconds and test pass if its within 1.0-3.0sec"
tags: ["tutorials"]
run: sleep 2
status:
runtime:
min: 1.0
max: 3.0
timelimit_min:
type: script
executor: generic.local.sh
description: "Run a sleep job for 2 seconds and test pass if its exceeds min time of 1.0 sec"
tags: ["tutorials"]
run: sleep 2
status:
runtime:
min: 1.0
timelimit_max:
type: script
executor: generic.local.sh
description: "Run a sleep job for 2 seconds and test pass if it's within max time: 5.0 sec"
tags: ["tutorials"]
run: sleep 2
status:
runtime:
max: 5.0
timelimit_min_fail:
type: script
executor: generic.local.sh
description: "This test fails because it runs less than mintime of 10 second"
tags: ["tutorials"]
run: sleep 2
status:
runtime:
min: 10.0
timelimit_max_fail:
type: script
executor: generic.local.sh
description: "This test fails because it exceeds maxtime of 1.0 second"
tags: ["tutorials"]
run: sleep 3
status:
runtime:
max: 1.0
$ buildtest build -b tutorials/runtime_status_test.yml
User: docs
Hostname: build-14673784-project-280831-buildtest
Platform: Linux
Current Time: 2021/09/09 15:54:52
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest
buildtest version: 0.11.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.11.0/bin/python
python version: 3.7.9
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest build -b tutorials/runtime_status_test.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+----------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+================================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/runtime_status_test.yml |
+----------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/runtime_status_test.yml: VALID
Total builder objects created: 5
builders: [timelimit_min_max/bf6aaa60, timelimit_min/810cab9e, timelimit_max/8385a7e5, timelimit_min_fail/5352acc1, timelimit_max_fail/40bee7c5]
name id description buildspecs
------------------ -------- ------------------------------------------------------------------------------ --------------------------------------------------------------------------------------------------------------
timelimit_min_max bf6aaa60 Run a sleep job for 2 seconds and test pass if its within 1.0-3.0sec /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/runtime_status_test.yml
timelimit_min 810cab9e Run a sleep job for 2 seconds and test pass if its exceeds min time of 1.0 sec /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/runtime_status_test.yml
timelimit_max 8385a7e5 Run a sleep job for 2 seconds and test pass if it's within max time: 5.0 sec /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/runtime_status_test.yml
timelimit_min_fail 5352acc1 This test fails because it runs less than mintime of 10 second /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/runtime_status_test.yml
timelimit_max_fail 40bee7c5 This test fails because it exceeds maxtime of 1.0 second /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/runtime_status_test.yml
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
--------------------+----------+--------+------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
timelimit_min_max | bf6aaa60 | script | generic.local.sh | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_max/bf6aaa60/timelimit_min_max_build.sh
timelimit_min | 810cab9e | script | generic.local.sh | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min/810cab9e/timelimit_min_build.sh
timelimit_max | 8385a7e5 | script | generic.local.sh | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max/8385a7e5/timelimit_max_build.sh
timelimit_min_fail | 5352acc1 | script | generic.local.sh | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_fail/5352acc1/timelimit_min_fail_build.sh
timelimit_max_fail | 40bee7c5 | script | generic.local.sh | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max_fail/40bee7c5/timelimit_max_fail_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
timelimit_min_max/bf6aaa60: completed with returncode: 0
timelimit_min_max/bf6aaa60: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_max/bf6aaa60/timelimit_min_max.out
timelimit_min_max/bf6aaa60: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_max/bf6aaa60/timelimit_min_max.err
timelimit_min_fail/5352acc1: completed with returncode: 0
timelimit_min_fail/5352acc1: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_fail/5352acc1/timelimit_min_fail.out
timelimit_min_fail/5352acc1: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_fail/5352acc1/timelimit_min_fail.err
timelimit_min/810cab9e: completed with returncode: 0
timelimit_min/810cab9e: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min/810cab9e/timelimit_min.out
timelimit_min/810cab9e: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min/810cab9e/timelimit_min.err
timelimit_max/8385a7e5: completed with returncode: 0
timelimit_max/8385a7e5: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max/8385a7e5/timelimit_max.out
timelimit_max/8385a7e5: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max/8385a7e5/timelimit_max.err
timelimit_max_fail/40bee7c5: completed with returncode: 0
timelimit_max_fail/40bee7c5: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max_fail/40bee7c5/timelimit_max_fail.out
timelimit_max_fail/40bee7c5: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max_fail/40bee7c5/timelimit_max_fail.err
______________________________
Launching test: timelimit_min_max
Test ID: bf6aaa60-4a8b-4249-9637-56b687aa201f
Executor Name: generic.local.sh
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_max/bf6aaa60/timelimit_min_max_build.sh
______________________________
Launching test: timelimit_min
Test ID: 810cab9e-06db-42d8-8516-3a56fa1b97cb
Executor Name: generic.local.sh
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min/810cab9e/timelimit_min_build.sh
______________________________
Launching test: timelimit_max
Test ID: 8385a7e5-a8d8-4c1e-8999-ab8ebfb7430c
Executor Name: generic.local.sh
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max/8385a7e5/timelimit_max_build.sh
______________________________
Launching test: timelimit_min_fail
Test ID: 5352acc1-0dbc-44ba-985f-a7a9d585974b
Executor Name: generic.local.sh
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_fail/5352acc1/timelimit_min_fail_build.sh
______________________________
Launching test: timelimit_max_fail
Test ID: 40bee7c5-9879-448b-a5e2-e055cf41f5fd
Executor Name: generic.local.sh
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max_fail/40bee7c5/timelimit_max_fail_build.sh
+----------------------+
| Stage: Test Summary |
+----------------------+
name | id | executor | status | returncode_match | regex_match | runtime_match | returncode | runtime
--------------------+----------+------------------+----------+--------------------+---------------+-----------------+--------------+-----------
timelimit_min_max | bf6aaa60 | generic.local.sh | PASS | False | False | True | 0 | 2.04555
timelimit_min | 810cab9e | generic.local.sh | PASS | False | False | True | 0 | 2.03131
timelimit_max | 8385a7e5 | generic.local.sh | PASS | False | False | True | 0 | 2.01983
timelimit_min_fail | 5352acc1 | generic.local.sh | FAIL | False | False | False | 0 | 2.03991
timelimit_max_fail | 40bee7c5 | generic.local.sh | FAIL | False | False | False | 0 | 3.03514
Passed Tests: 3/5 Percentage: 60.000%
Failed Tests: 2/5 Percentage: 40.000%
Writing Logfile to: /tmp/buildtest_qswjdps6.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest.log
If we look at the test results, we expect the first three tests timelimit_min, timelimit_max, timelimit_min_max will pass while the last two tests fail because it fails to comply with runtime property.
$ buildtest report --filter buildspec=tutorials/runtime_status_test.yml --format name,id,state,runtime --latest
Reading report file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/report.json
+--------------------+----------+---------+-----------+
| name | id | state | runtime |
+====================+==========+=========+===========+
| timelimit_min_max | bf6aaa60 | PASS | 2.04555 |
+--------------------+----------+---------+-----------+
| timelimit_min | 810cab9e | PASS | 2.03131 |
+--------------------+----------+---------+-----------+
| timelimit_max | 8385a7e5 | PASS | 2.01983 |
+--------------------+----------+---------+-----------+
| timelimit_min_fail | 5352acc1 | FAIL | 2.03991 |
+--------------------+----------+---------+-----------+
| timelimit_max_fail | 40bee7c5 | FAIL | 3.03514 |
+--------------------+----------+---------+-----------+
Defining Tags¶
The tags field can be used to classify tests which can be used to organize tests
or if you want to Building By Tags (buildtest build --tags <TAGNAME>).
Tags can be defined as a string or list of strings. In this example, the test
string_tag defines a tag name network while test list_of_strings_tags
define a list of tags named network and ping.
version: "1.0"
buildspecs:
string_tag:
type: script
executor: generic.local.bash
description: tags can be a string
tags: network
run: hostname
list_of_strings_tags:
type: script
executor: generic.local.bash
description: tags can be a list of strings
tags: [network, ping]
run: ping -c 4 www.google.com
Each item in tags must be a string and no duplicates are allowed, for example in this test, we define a duplicate tag network which is not allowed.
version: "1.0"
buildspecs:
duplicate_string_tags:
type: script
executor: generic.local.bash
description: duplicate strings in tags list is not allowed
tags: [network, network]
run: hostname
If we run this test and inspect the logs we will see an error message in schema validation:
2020-09-29 10:56:43,175 [parser.py:179 - _validate() ] - [INFO] Validating test - 'duplicate_string_tags' with schemafile: script-v1.0.schema.json
2020-09-29 10:56:43,175 [buildspec.py:397 - parse_buildspecs() ] - [ERROR] ['network', 'network'] is not valid under any of the given schemas
Failed validating 'oneOf' in schema['properties']['tags']:
{'oneOf': [{'type': 'string'},
{'$ref': '#/definitions/list_of_strings'}]}
On instance['tags']:
['network', 'network']
If tags is a list, it must contain one item, therefore an empty list (i.e tags: [])
is invalid.
Customize Shell¶
Shell Type¶
buildtest will default to bash shell when running test, but we can configure shell
option using the shell field. The shell field is defined in schema as follows:
"shell": {
"type": "string",
"description": "Specify a shell launcher to use when running jobs. This sets the shebang line in your test script. The ``shell`` key can be used with ``run`` section to describe content of script and how its executed",
"pattern": "^(/bin/bash|/bin/sh|/bin/csh|/bin/tcsh|/bin/zsh|bash|sh|csh|tcsh|zsh|python).*"
},
The shell pattern is a regular expression where one can specify a shell name along with shell options. The shell will configure the shebang in the test-script. In this example, we illustrate a few tests using different shell field.
version: "1.0"
buildspecs:
_bin_sh_shell:
executor: generic.local.sh
type: script
description: "/bin/sh shell example"
shell: /bin/sh
tags: [tutorials]
run: "bzip2 --help"
_bin_bash_shell:
executor: generic.local.bash
type: script
description: "/bin/bash shell example"
shell: /bin/bash
tags: [tutorials]
run: "bzip2 -h"
bash_shell:
executor: generic.local.bash
type: script
description: "bash shell example"
shell: bash
tags: [tutorials]
run: "echo $SHELL"
sh_shell:
executor: generic.local.sh
type: script
description: "sh shell example"
shell: sh
tags: [tutorials]
run: "echo $SHELL"
shell_options:
executor: generic.local.sh
type: script
description: "shell options"
shell: "sh -x"
tags: [tutorials]
run: |
echo $SHELL
hostname
The generated test-script for buildspec _bin_sh_shell will specify shebang
/bin/sh because we specified shell: /bin/sh:
#!/bin/sh
# Content of run section
bzip2 --help
If you don’t specify a shell path such as shell: sh, then buildtest will resolve
path by looking in $PATH and build the shebang line.
In test shell_options we specify shell: "sh -x", buildtest will tack on the
shell options into the called script as follows:
#!/bin/bash
############# START VARIABLE DECLARATION ########################
export BUILDTEST_TEST_NAME=shell_options
export BUILDTEST_TEST_ROOT=/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.sh/shell_examples/shell_options/0
export BUILDTEST_BUILDSPEC_DIR=/Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials
export BUILDTEST_STAGE_DIR=/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.sh/shell_examples/shell_options/0/stage
export BUILDTEST_TEST_ID=95c11f54-bbb1-4154-849d-44313e4417c2
############# END VARIABLE DECLARATION ########################
# source executor startup script
source /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/executor/generic.local.sh/before_script.sh
# Run generated script
sh -x /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.sh/shell_examples/shell_options/0/stage/shell_options.sh
# Get return code
returncode=$?
# Exit with return code
exit $returncode
If you prefer csh or tcsh for writing scripts just set shell: csh or
shell: tcsh, note you will need to match this with appropriate executor. For now
use executor: generic.local.csh to run your csh/tcsh scripts. In this example below
we define a script using csh, take note of run section we can write csh style.
version: "1.0"
buildspecs:
csh_shell:
executor: generic.local.csh
type: script
description: "csh shell example"
shell: csh
tags: [tutorials]
vars:
file: "/etc/csh.cshrc"
run: |
if (-e $file) then
echo "$file file found"
else
echo "$file file not found"
exit 1
endif
Customize Shebang¶
You may customize the shebang line in testscript using shebang field. This
takes precedence over the shell property which automatically detects the shebang
based on shell path.
In next example we have two tests bash_login_shebang and bash_nonlogin_shebang
which tests if shell is Login or Non-Login. The #!/bin/bash -l indicates we
want to run in login shell and expects an output of Login Shell while
test bash_nonlogin_shebang should run in default behavior which is non-login
shell and expects output Not Login Shell. We match this with regular expression
with stdout stream.
version: "1.0"
buildspecs:
bash_login_shebang:
type: script
executor: generic.local.bash
shebang: "#!/bin/bash -l"
description: customize shebang line with bash login shell
tags: tutorials
run: shopt -q login_shell && echo 'Login Shell' || echo 'Not Login Shell'
status:
regex:
exp: "^Login Shell$"
stream: stdout
bash_nonlogin_shebang:
type: script
executor: generic.local.bash
shebang: "#!/bin/bash"
description: customize shebang line with default bash (nonlogin) shell
tags: tutorials
run: shopt -q login_shell && echo 'Login Shell' || echo 'Not Login Shell'
status:
regex:
exp: "^Not Login Shell$"
stream: stdout
Now let’s run this test as we see the following.
$ buildtest build -b tutorials/shebang.yml
User: docs
Hostname: build-14673784-project-280831-buildtest
Platform: Linux
Current Time: 2021/09/09 15:54:59
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest
buildtest version: 0.11.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.11.0/bin/python
python version: 3.7.9
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest build -b tutorials/shebang.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+----------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+====================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/shebang.yml |
+----------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/shebang.yml: VALID
Total builder objects created: 2
builders: [bash_login_shebang/3415a842, bash_nonlogin_shebang/52864b0a]
name id description buildspecs
--------------------- -------- --------------------------------------------------------- --------------------------------------------------------------------------------------------------
bash_login_shebang 3415a842 customize shebang line with bash login shell /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/shebang.yml
bash_nonlogin_shebang 52864b0a customize shebang line with default bash (nonlogin) shell /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/shebang.yml
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
-----------------------+----------+--------+--------------------+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
bash_login_shebang | 3415a842 | script | generic.local.bash | tutorials | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/shebang/bash_login_shebang/3415a842/bash_login_shebang_build.sh
bash_nonlogin_shebang | 52864b0a | script | generic.local.bash | tutorials | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/shebang/bash_nonlogin_shebang/52864b0a/bash_nonlogin_shebang_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
bash_nonlogin_shebang/52864b0a: completed with returncode: 0
bash_nonlogin_shebang/52864b0a: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/shebang/bash_nonlogin_shebang/52864b0a/bash_nonlogin_shebang.out
bash_nonlogin_shebang/52864b0a: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/shebang/bash_nonlogin_shebang/52864b0a/bash_nonlogin_shebang.err
bash_nonlogin_shebang/52864b0a: performing regular expression - '^Not Login Shell$' on file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/shebang/bash_nonlogin_shebang/52864b0a/bash_nonlogin_shebang.out with regular expression
bash_nonlogin_shebang/52864b0a: Regular Expression Match - Success!
bash_login_shebang/3415a842: completed with returncode: 0
bash_login_shebang/3415a842: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/shebang/bash_login_shebang/3415a842/bash_login_shebang.out
bash_login_shebang/3415a842: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/shebang/bash_login_shebang/3415a842/bash_login_shebang.err
bash_login_shebang/3415a842: performing regular expression - '^Login Shell$' on file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/shebang/bash_login_shebang/3415a842/bash_login_shebang.out with regular expression
bash_login_shebang/3415a842: Regular Expression Match - Success!
______________________________
Launching test: bash_login_shebang
Test ID: 3415a842-ed4b-435d-a46f-7f942694f28b
Executor Name: generic.local.bash
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/shebang/bash_login_shebang/3415a842/bash_login_shebang_build.sh
______________________________
Launching test: bash_nonlogin_shebang
Test ID: 52864b0a-dc87-4e8e-a8df-ba8f8b7f98ff
Executor Name: generic.local.bash
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/shebang/bash_nonlogin_shebang/52864b0a/bash_nonlogin_shebang_build.sh
+----------------------+
| Stage: Test Summary |
+----------------------+
name | id | executor | status | returncode_match | regex_match | runtime_match | returncode | runtime
-----------------------+----------+--------------------+----------+--------------------+---------------+-----------------+--------------+-----------
bash_login_shebang | 3415a842 | generic.local.bash | PASS | False | True | False | 0 | 0.030688
bash_nonlogin_shebang | 52864b0a | generic.local.bash | PASS | False | True | False | 0 | 0.022097
Passed Tests: 2/2 Percentage: 100.000%
Failed Tests: 0/2 Percentage: 0.000%
Writing Logfile to: /tmp/buildtest_1n3al6un.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest.log
If we look at the generated test for bash_login_shebang we see the shebang line is passed into the script:
#!/bin/bash -l
# Content of run section
shopt -q login_shell && echo 'Login Shell' || echo 'Not Login Shell'
Python Shell¶
You can use script schema to write python scripts using the run property. This
can be achieved if you use the generic.local.python executor assuming you have this
defined in your buildtest configuration.
Here is a python example calculating area of circle
version: "1.0"
buildspecs:
circle_area:
executor: generic.local.python
type: script
shell: python
description: "Calculate circle of area given a radius"
tags: [tutorials, python]
run: |
import math
radius = 2
area = math.pi * radius * radius
print("Circle Radius ", radius)
print("Area of circle ", area)
The shell: python will let us write python script in the run section.
The tags field can be used to classify test, the field expects an array of
string items.
Note
Python scripts are very picky when it comes to formatting, in the run section
if you are defining multiline python script you must remember to use 2 space indent
to register multiline string. buildtest will extract the content from run section
and inject in your test script. To ensure proper formatting for a more complex python
script you may be better off writing a python script in separate file and call it
in run section.
Skipping test¶
By default, buildtest will run all tests defined in buildspecs section, if you
want to skip a test use the skip field which expects a boolean value. Shown
below is an example test.
version: "1.0"
buildspecs:
skip:
type: script
executor: generic.local.bash
description: This test is skipped
skip: Yes
tags: [tutorials]
run: hostname
unskipped:
type: script
executor: generic.local.bash
description: This test is not skipped
skip: No
tags: [tutorials]
run: hostname
The first test skip will be ignored by buildtest because skip: true is defined
while unskipped will be processed as usual.
Note
YAML and JSON have different representation for boolean. For json schema
valid values are true and false see https://json-schema.org/understanding-json-schema/reference/boolean.html
however YAML has many more representation for boolean see https://yaml.org/type/bool.html. You
may use any of the YAML boolean, however it’s best to stick with json schema values
true and false.
Here is an example build, notice message [skip] test is skipped during the build
stage
$ buildtest build -b tutorials/skip_tests.yml
User: docs
Hostname: build-14673784-project-280831-buildtest
Platform: Linux
Current Time: 2021/09/09 15:55:00
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest
buildtest version: 0.11.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.11.0/bin/python
python version: 3.7.9
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest build -b tutorials/skip_tests.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+-------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+=======================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/skip_tests.yml |
+-------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
[skip](/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/skip_tests.yml): test is skipped.
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/skip_tests.yml: VALID
Total builder objects created: 1
builders: [unskipped/27e1bc21]
name id description buildspecs
--------- -------- ------------------------ -----------------------------------------------------------------------------------------------------
unskipped 27e1bc21 This test is not skipped /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/skip_tests.yml
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
-----------+----------+--------+--------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------
unskipped | 27e1bc21 | script | generic.local.bash | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/skip_tests/unskipped/27e1bc21/unskipped_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
unskipped/27e1bc21: completed with returncode: 0
unskipped/27e1bc21: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/skip_tests/unskipped/27e1bc21/unskipped.out
unskipped/27e1bc21: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/skip_tests/unskipped/27e1bc21/unskipped.err
______________________________
Launching test: unskipped
Test ID: 27e1bc21-7820-4c39-aa31-1b91e1e27760
Executor Name: generic.local.bash
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/skip_tests/unskipped/27e1bc21/unskipped_build.sh
+----------------------+
| Stage: Test Summary |
+----------------------+
name | id | executor | status | returncode_match | regex_match | runtime_match | returncode | runtime
-----------+----------+--------------------+----------+--------------------+---------------+-----------------+--------------+-----------
unskipped | 27e1bc21 | generic.local.bash | PASS | N/A | N/A | N/A | 0 | 0.006467
Passed Tests: 1/1 Percentage: 100.000%
Failed Tests: 0/1 Percentage: 0.000%
Writing Logfile to: /tmp/buildtest_eng8vf0m.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest.log
Defining Metrics¶
buildtest provides a method to define test metrics in the buildspecs which can be used to
store arbitrary content from the output/error file into named metric. A metric is
defined using the metrics property where each element under the metrics property
is the name of the metric which must be a unique name. A metric can apply regular expression
on stdout, stderr like in this example below. The metrics are captured in the test report which can
be queried via buildtest report or buildtest inspect. Shown below is an example
where we define two metrics named hpcg_rating and hpcg_state.
version: "1.0"
buildspecs:
metric_regex_example:
executor: generic.local.sh
type: script
description: capture result metric from output
run: echo "HPCG result is VALID with a GFLOP/s rating of=63.6515"
tags: tutorials
metrics:
hpcg_rating:
regex:
exp: 'rating of=(\d+\.\d+)$'
stream: stdout
hpcg_state:
regex:
exp: '(VALID)'
stream: stdout
The metrics will not impact behavior of test, it will only impact the test report. By default
a metric will be an empty dictionary if there is no metrics property. If we fail to match
a regular expression, the metric will be defined as an empty string.
Note
If your regular expression contains an escape character \ you must surround your
string in single quotes ' as pose to double quotes "
Let’s build this test.
$ buildtest build -b tutorials/metrics_regex.yml
User: docs
Hostname: build-14673784-project-280831-buildtest
Platform: Linux
Current Time: 2021/09/09 15:55:00
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest
buildtest version: 0.11.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.11.0/bin/python
python version: 3.7.9
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest build -b tutorials/metrics_regex.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+----------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+==========================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/metrics_regex.yml |
+----------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/metrics_regex.yml: VALID
Total builder objects created: 1
builders: [metric_regex_example/15948b76]
name id description buildspecs
-------------------- -------- --------------------------------- --------------------------------------------------------------------------------------------------------
metric_regex_example 15948b76 capture result metric from output /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/metrics_regex.yml
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
----------------------+----------+--------+------------------+-----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
metric_regex_example | 15948b76 | script | generic.local.sh | tutorials | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/metrics_regex/metric_regex_example/15948b76/metric_regex_example_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
metric_regex_example/15948b76: completed with returncode: 0
metric_regex_example/15948b76: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/metrics_regex/metric_regex_example/15948b76/metric_regex_example.out
metric_regex_example/15948b76: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/metrics_regex/metric_regex_example/15948b76/metric_regex_example.err
______________________________
Launching test: metric_regex_example
Test ID: 15948b76-7261-4149-8581-39fa11dfdecd
Executor Name: generic.local.sh
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/metrics_regex/metric_regex_example/15948b76/metric_regex_example_build.sh
+----------------------+
| Stage: Test Summary |
+----------------------+
name | id | executor | status | returncode_match | regex_match | runtime_match | returncode | runtime
----------------------+----------+------------------+----------+--------------------+---------------+-----------------+--------------+-----------
metric_regex_example | 15948b76 | generic.local.sh | PASS | N/A | N/A | N/A | 0 | 0.005627
Passed Tests: 1/1 Percentage: 100.000%
Failed Tests: 0/1 Percentage: 0.000%
Writing Logfile to: /tmp/buildtest_p5lwgqj9.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest.log
We can query the metrics via buildtest report which will display all metrics as a comma separted
Key/Value pair. We can use buildtest report --format metrics to extract all metrics for a test.
Internally, we store the metrics as a dictionary but when we print them out via buildtest report we
join them together into a single string. Shown below is the metrics for the previous build.
$ buildtest report --filter buildspec=tutorials/metrics_regex.yml --format name,metrics
Reading report file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/report.json
+----------------------+------------------------------------------------+
| name | metrics |
+======================+================================================+
| metric_regex_example | hpcg_rating=rating of=63.6515,hpcg_state=VALID |
+----------------------+------------------------------------------------+
You can define a metric based on variables or environment variables
which requires you have set vars or env property in the buildspec. The vars and
env is a property under the metric name that can be used to reference name
of variable or environment variable. If you reference an invalid name, buildtest will assign the metric an empty string.
In this next example, we define two metrics gflop and foo that are assigned to variable GFLOPS and
environment variable FOO.
version: "1.0"
buildspecs:
metric_variable_assignment:
executor: generic.local.sh
type: script
description: capture result metric based on variables and environment variable
vars:
GFLOPS: "63.6515"
env:
FOO: BAR
run: |
echo $GFLOPS
echo $FOO
tags: tutorials
metrics:
gflops:
vars: "GFLOPS"
foo:
env: "FOO"
Now let’s build the test.
$ buildtest build -b tutorials/metrics_variable.yml
User: docs
Hostname: build-14673784-project-280831-buildtest
Platform: Linux
Current Time: 2021/09/09 15:55:01
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest
buildtest version: 0.11.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.11.0/bin/python
python version: 3.7.9
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest build -b tutorials/metrics_variable.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+-------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+=============================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/metrics_variable.yml |
+-------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/metrics_variable.yml: VALID
Total builder objects created: 1
builders: [metric_variable_assignment/0fbf904d]
name id description buildspecs
-------------------------- -------- ----------------------------------------------------------------- -----------------------------------------------------------------------------------------------------------
metric_variable_assignment 0fbf904d capture result metric based on variables and environment variable /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/metrics_variable.yml
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
----------------------------+----------+--------+------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
metric_variable_assignment | 0fbf904d | script | generic.local.sh | tutorials | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/metrics_variable/metric_variable_assignment/0fbf904d/metric_variable_assignment_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
metric_variable_assignment/0fbf904d: completed with returncode: 0
metric_variable_assignment/0fbf904d: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/metrics_variable/metric_variable_assignment/0fbf904d/metric_variable_assignment.out
metric_variable_assignment/0fbf904d: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/metrics_variable/metric_variable_assignment/0fbf904d/metric_variable_assignment.err
______________________________
Launching test: metric_variable_assignment
Test ID: 0fbf904d-e32a-429e-9a83-8007ac59ef08
Executor Name: generic.local.sh
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/metrics_variable/metric_variable_assignment/0fbf904d/metric_variable_assignment_build.sh
+----------------------+
| Stage: Test Summary |
+----------------------+
name | id | executor | status | returncode_match | regex_match | runtime_match | returncode | runtime
----------------------------+----------+------------------+----------+--------------------+---------------+-----------------+--------------+-----------
metric_variable_assignment | 0fbf904d | generic.local.sh | PASS | N/A | N/A | N/A | 0 | 0.005851
Passed Tests: 1/1 Percentage: 100.000%
Failed Tests: 0/1 Percentage: 0.000%
Writing Logfile to: /tmp/buildtest_1_5x3yi0.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest.log
Now if we query the previous test, we will see the two metrics gflops and foo are captured in the test.
$ buildtest report --filter buildspec=tutorials/metrics_variable.yml --format name,metrics
Reading report file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/report.json
+----------------------------+------------------------+
| name | metrics |
+============================+========================+
| metric_variable_assignment | gflops=63.6515,foo=BAR |
+----------------------------+------------------------+
You can also define metrics with the compiler schema which works slightly different
when it comes to variable and environment assignment. Since you can define vars and env in defaults
or config section. Let’s take a look at this next example where we compile an openmp code
that will use the OMP_NUM_THREADS environment as the metric that is assigned to name openmp_threads. Since
we have defined OMP_NUM_THREADS under the defaults and config section we will use the
environment variable that corresponds to each compiler.
version: "1.0"
buildspecs:
metrics_variable_compiler:
type: compiler
description: define metrics with compiler schema
executor: generic.local.bash
tags: [tutorials, compile]
source: "src/hello_omp.c"
compilers:
name: ["^(builtin_gcc|gcc)"]
default:
gcc:
cflags: -fopenmp
env:
OMP_NUM_THREADS: 4
config:
builtin_gcc:
env:
OMP_NUM_THREADS: 1
gcc/9.3.0-n7p74fd:
env:
OMP_NUM_THREADS: 2
metrics:
openmp_threads:
env: "OMP_NUM_THREADS"
Note
This test uses a custom site configuration that defines gcc multiple compilers.
Let’s build this test as follows
$ buildtest -c config/laptop.yml build -b tutorials/compilers/metrics_openmp.yml
User: siddiq90
Hostname: DOE-7086392.local
Platform: Darwin
Current Time: 2021/07/24 00:14:33
buildtest path: /Users/siddiq90/Documents/GitHubDesktop/buildtest/bin/buildtest
buildtest version: 0.10.0
python path: /Users/siddiq90/.local/share/virtualenvs/buildtest-KLOcDrW0/bin/python
python version: 3.7.3
Test Directory: /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests
Configuration File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/config/laptop.yml
Command: /Users/siddiq90/Documents/GitHubDesktop/buildtest/bin/buildtest -c config/laptop.yml build -b tutorials/compilers/metrics_openmp.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+==========================================================================================+
| /Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/compilers/metrics_openmp.yml |
+------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
---------------------------+--------------+------------------------------------------------------------------------------------------
compiler-v1.0.schema.json | True | /Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/compilers/metrics_openmp.yml
name description
------------------------- -----------------------------------
metrics_variable_compiler define metrics with compiler schema
metrics_variable_compiler define metrics with compiler schema
metrics_variable_compiler define metrics with compiler schema
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | compiler | testpath
---------------------------+----------+----------+--------------------+--------------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------
metrics_variable_compiler | e45976b8 | compiler | generic.local.bash | ['tutorials', 'compile'] | builtin_gcc | /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/metrics_openmp/metrics_variable_compiler/11/metrics_variable_compiler_build.sh
metrics_variable_compiler | 8bc71f19 | compiler | generic.local.bash | ['tutorials', 'compile'] | gcc/9.3.0-n7p74fd | /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/metrics_openmp/metrics_variable_compiler/12/metrics_variable_compiler_build.sh
metrics_variable_compiler | 7127eb46 | compiler | generic.local.bash | ['tutorials', 'compile'] | gcc/10.2.0-37fmsw7 | /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/metrics_openmp/metrics_variable_compiler/13/metrics_variable_compiler_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
name | id | executor | status | returncode
---------------------------+----------+--------------------+----------+--------------
metrics_variable_compiler | e45976b8 | generic.local.bash | FAIL | 127
metrics_variable_compiler | 8bc71f19 | generic.local.bash | PASS | 0
metrics_variable_compiler | 7127eb46 | generic.local.bash | PASS | 0
+----------------------+
| Stage: Test Summary |
+----------------------+
Passed Tests: 2/3 Percentage: 66.667%
Failed Tests: 1/3 Percentage: 33.333%
Writing Logfile to: /Users/siddiq90/buildtest/buildtest_0a04808e.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest.log
Now if we filter the results, notice that builtin_gcc got metrics openmp_threads=1 since
that is the value set under the builtin_gcc compiler instance under the config section. The gcc/9.3.0-n7p74fd compiler
got value of 2 because we have an entry defined under the config section while gcc/10.2.0-37fmsw7
compiler got the value of 4 from the default section that is inherited for all gcc compilers.
$ buildtest report --filter buildspec=tutorials/compilers/metrics_openmp.yml --format name,compiler,metrics
Reading report file: /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/report.json
+---------------------------+--------------------+------------------+
| name | compiler | metrics |
+===========================+====================+==================+
| metrics_variable_compiler | builtin_gcc | openmp_threads=1 |
+---------------------------+--------------------+------------------+
| metrics_variable_compiler | gcc/9.3.0-n7p74fd | openmp_threads=2 |
+---------------------------+--------------------+------------------+
| metrics_variable_compiler | gcc/10.2.0-37fmsw7 | openmp_threads=4 |
+---------------------------+--------------------+------------------+
Running test across multiple executors¶
The executor property can support regular expression to search for compatible
executors, this can be used if you want to run a test across multiple executors. In buildtest,
we use re.fullmatch with the input
pattern defined by executor property against a list of available executors defined in configuration file.
You can retrieve a list of executors by running buildtest config executors.
In example below we will run this test on generic.local.bash and generic.local.sh executor based on the regular expression.
version: "1.0"
buildspecs:
executor_regex_script_schema:
type: script
executor: 'generic.local.(bash|sh)'
description: regular expression test with executor using script schema
tags: [tutorials]
run: date
If we build this test, notice that there are two tests, one for each executor.
$ buildtest build -b tutorials/executor_regex_script.yml
User: docs
Hostname: build-14673784-project-280831-buildtest
Platform: Linux
Current Time: 2021/09/09 15:55:01
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest
buildtest version: 0.11.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.11.0/bin/python
python version: 3.7.9
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest build -b tutorials/executor_regex_script.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+------------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+==================================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/executor_regex_script.yml |
+------------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/executor_regex_script.yml: VALID
Total builder objects created: 2
builders: [executor_regex_script_schema/1bc9d0da, executor_regex_script_schema/4220359a]
name id description buildspecs
---------------------------- -------- --------------------------------------------------------- ----------------------------------------------------------------------------------------------------------------
executor_regex_script_schema 1bc9d0da regular expression test with executor using script schema /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/executor_regex_script.yml
executor_regex_script_schema 4220359a regular expression test with executor using script schema /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/executor_regex_script.yml
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
------------------------------+----------+--------+--------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
executor_regex_script_schema | 1bc9d0da | script | generic.local.bash | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/executor_regex_script/executor_regex_script_schema/1bc9d0da/executor_regex_script_schema_build.sh
executor_regex_script_schema | 4220359a | script | generic.local.sh | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/executor_regex_script/executor_regex_script_schema/4220359a/executor_regex_script_schema_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
executor_regex_script_schema/4220359a: completed with returncode: 0
executor_regex_script_schema/4220359a: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/executor_regex_script/executor_regex_script_schema/4220359a/executor_regex_script_schema.out
executor_regex_script_schema/4220359a: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/executor_regex_script/executor_regex_script_schema/4220359a/executor_regex_script_schema.err
executor_regex_script_schema/1bc9d0da: completed with returncode: 0
executor_regex_script_schema/1bc9d0da: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/executor_regex_script/executor_regex_script_schema/1bc9d0da/executor_regex_script_schema.out
executor_regex_script_schema/1bc9d0da: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/executor_regex_script/executor_regex_script_schema/1bc9d0da/executor_regex_script_schema.err
______________________________
Launching test: executor_regex_script_schema
Test ID: 1bc9d0da-7ec3-4131-ad36-338cf98d229e
Executor Name: generic.local.bash
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/executor_regex_script/executor_regex_script_schema/1bc9d0da/executor_regex_script_schema_build.sh
______________________________
Launching test: executor_regex_script_schema
Test ID: 4220359a-940f-4aab-890f-29bab98ebc2b
Executor Name: generic.local.sh
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/executor_regex_script/executor_regex_script_schema/4220359a/executor_regex_script_schema_build.sh
+----------------------+
| Stage: Test Summary |
+----------------------+
name | id | executor | status | returncode_match | regex_match | runtime_match | returncode | runtime
------------------------------+----------+--------------------+----------+--------------------+---------------+-----------------+--------------+-----------
executor_regex_script_schema | 1bc9d0da | generic.local.bash | PASS | N/A | N/A | N/A | 0 | 0.032167
executor_regex_script_schema | 4220359a | generic.local.sh | PASS | N/A | N/A | N/A | 0 | 0.026747
Passed Tests: 2/2 Percentage: 100.000%
Failed Tests: 0/2 Percentage: 0.000%
Writing Logfile to: /tmp/buildtest_fvx48ab1.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest.log
Multiple Executors¶
Note
This feature is in active development
Note
This feature is compatible with type: script and type: spack.
The executors property can be used to define executor specific configuration
for each test, currently this field can be used with vars, env
, scheduler directives: sbatch, bsub, pbs, cobalt and cray burst buffer/data warp.
The executors field is a JSON object that expects name of executor followed by property set per executor. In this next example,
we define variables X, Y and environment SHELL based on executors generic.local.sh and generic.local.bash.
version: "1.0"
buildspecs:
executors_vars_env_declaration:
type: script
executor: 'generic.local.(bash|sh)'
description: Declaring env and vars by executors section
tags: [tutorials]
run: |
echo "X:" $X
echo "Y:" $Y
echo $SHELL
executors:
generic.local.bash:
vars:
X: 1
Y: 3
env:
SHELL: bash
generic.local.sh:
vars:
X: 2
Y: 4
env:
SHELL: sh
Let’s build this test.
$ buildtest build -b tutorials/script/multiple_executors.yml
User: docs
Hostname: build-14673784-project-280831-buildtest
Platform: Linux
Current Time: 2021/09/09 15:55:02
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest
buildtest version: 0.11.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.11.0/bin/python
python version: 3.7.9
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest build -b tutorials/script/multiple_executors.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+----------------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+======================================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/script/multiple_executors.yml |
+----------------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/script/multiple_executors.yml: VALID
Total builder objects created: 2
builders: [executors_vars_env_declaration/cc02b315, executors_vars_env_declaration/b19d2068]
name id description buildspecs
------------------------------ -------- ------------------------------------------- --------------------------------------------------------------------------------------------------------------------
executors_vars_env_declaration cc02b315 Declaring env and vars by executors section /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/script/multiple_executors.yml
executors_vars_env_declaration b19d2068 Declaring env and vars by executors section /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/script/multiple_executors.yml
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
--------------------------------+----------+--------+--------------------+---------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
executors_vars_env_declaration | cc02b315 | script | generic.local.bash | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/multiple_executors/executors_vars_env_declaration/cc02b315/executors_vars_env_declaration_build.sh
executors_vars_env_declaration | b19d2068 | script | generic.local.sh | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/multiple_executors/executors_vars_env_declaration/b19d2068/executors_vars_env_declaration_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
executors_vars_env_declaration/cc02b315: completed with returncode: 0
executors_vars_env_declaration/cc02b315: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/multiple_executors/executors_vars_env_declaration/cc02b315/executors_vars_env_declaration.out
executors_vars_env_declaration/cc02b315: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/multiple_executors/executors_vars_env_declaration/cc02b315/executors_vars_env_declaration.err
executors_vars_env_declaration/b19d2068: completed with returncode: 0
executors_vars_env_declaration/b19d2068: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/multiple_executors/executors_vars_env_declaration/b19d2068/executors_vars_env_declaration.out
executors_vars_env_declaration/b19d2068: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/multiple_executors/executors_vars_env_declaration/b19d2068/executors_vars_env_declaration.err
______________________________
Launching test: executors_vars_env_declaration
Test ID: cc02b315-0c77-4958-bb16-4d181319c4a4
Executor Name: generic.local.bash
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/multiple_executors/executors_vars_env_declaration/cc02b315/executors_vars_env_declaration_build.sh
______________________________
Launching test: executors_vars_env_declaration
Test ID: b19d2068-1076-448e-93f4-18dbd54cac49
Executor Name: generic.local.sh
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/multiple_executors/executors_vars_env_declaration/b19d2068/executors_vars_env_declaration_build.sh
+----------------------+
| Stage: Test Summary |
+----------------------+
name | id | executor | status | returncode_match | regex_match | runtime_match | returncode | runtime
--------------------------------+----------+--------------------+----------+--------------------+---------------+-----------------+--------------+-----------
executors_vars_env_declaration | cc02b315 | generic.local.bash | PASS | N/A | N/A | N/A | 0 | 0.026931
executors_vars_env_declaration | b19d2068 | generic.local.sh | PASS | N/A | N/A | N/A | 0 | 0.024118
Passed Tests: 2/2 Percentage: 100.000%
Failed Tests: 0/2 Percentage: 0.000%
Writing Logfile to: /tmp/buildtest_ebbywpnl.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest.log
Now let’s look at the generated content of the test as follows. We will see that buildtest will
set X=1, Y=3 and SHELL=bash for generic.local.bash and X=2, Y=4 and SHELL=sh for
generic.local.sh
$ buildtest inspect query -d all -t executors_vars_env_declaration
______________________________ executors_vars_env_declaration (ID: cc02b315-0c77-4958-bb16-4d181319c4a4) ______________________________
executor: generic.local.bash
description: Declaring env and vars by executors section
state: PASS
returncode: 0
runtime: 0.026931
starttime: 2021/09/09 15:55:02
endtime: 2021/09/09 15:55:02
************************* Start of Test Path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/multiple_executors/executors_vars_env_declaration/cc02b315/executors_vars_env_declaration.sh *************************
#!/bin/bash
# Declare environment variables
export SHELL=bash
# Declare environment variables
export X=1
export Y=3
# Content of run section
echo "X:" $X
echo "Y:" $Y
echo $SHELL
************************* End of Test Path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/multiple_executors/executors_vars_env_declaration/cc02b315/executors_vars_env_declaration.sh *************************
______________________________ executors_vars_env_declaration (ID: b19d2068-1076-448e-93f4-18dbd54cac49) ______________________________
executor: generic.local.sh
description: Declaring env and vars by executors section
state: PASS
returncode: 0
runtime: 0.024118
starttime: 2021/09/09 15:55:02
endtime: 2021/09/09 15:55:02
************************* Start of Test Path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/multiple_executors/executors_vars_env_declaration/b19d2068/executors_vars_env_declaration.sh *************************
#!/bin/bash
# Declare environment variables
export SHELL=sh
# Declare environment variables
export X=2
export Y=4
# Content of run section
echo "X:" $X
echo "Y:" $Y
echo $SHELL
************************* End of Test Path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/multiple_executors/executors_vars_env_declaration/b19d2068/executors_vars_env_declaration.sh *************************
Scheduler Directives¶
We can also define scheduler directives based on executor type, in this example we define
sbatch property per executor type. Note that sbatch property in the executors section
will override the sbatch property defined in the top-level file otherwise it will use the default.
version: "1.0"
buildspecs:
executors_sbatch_declaration:
type: script
executor: 'generic.local.(bash|sh)'
description: Declaring env and vars by executors section
tags: [tutorials]
run: hostname
sbatch: ["-N 4"]
executors:
generic.local.bash:
sbatch: ["-n 4", "-N 1", "-t 30"]
generic.local.sh:
sbatch: ["-n 8", "-N 1", "-t 60"]
$ buildtest build -b tutorials/script/executor_scheduler.yml
User: docs
Hostname: build-14673784-project-280831-buildtest
Platform: Linux
Current Time: 2021/09/09 15:55:02
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest
buildtest version: 0.11.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.11.0/bin/python
python version: 3.7.9
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest build -b tutorials/script/executor_scheduler.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+----------------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+======================================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/script/executor_scheduler.yml |
+----------------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/script/executor_scheduler.yml: VALID
Total builder objects created: 2
builders: [executors_sbatch_declaration/17f960fc, executors_sbatch_declaration/17627bec]
name id description buildspecs
---------------------------- -------- ------------------------------------------- --------------------------------------------------------------------------------------------------------------------
executors_sbatch_declaration 17f960fc Declaring env and vars by executors section /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/script/executor_scheduler.yml
executors_sbatch_declaration 17627bec Declaring env and vars by executors section /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/script/executor_scheduler.yml
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
------------------------------+----------+--------+--------------------+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
executors_sbatch_declaration | 17f960fc | script | generic.local.bash | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declaration/17f960fc/executors_sbatch_declaration_build.sh
executors_sbatch_declaration | 17627bec | script | generic.local.sh | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaration/17627bec/executors_sbatch_declaration_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
executors_sbatch_declaration/17f960fc: completed with returncode: 0
executors_sbatch_declaration/17f960fc: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declaration/17f960fc/executors_sbatch_declaration.out
executors_sbatch_declaration/17f960fc: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declaration/17f960fc/executors_sbatch_declaration.err
executors_sbatch_declaration/17627bec: completed with returncode: 0
executors_sbatch_declaration/17627bec: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaration/17627bec/executors_sbatch_declaration.out
executors_sbatch_declaration/17627bec: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaration/17627bec/executors_sbatch_declaration.err
______________________________
Launching test: executors_sbatch_declaration
Test ID: 17f960fc-0691-4997-bd7f-b420d899a406
Executor Name: generic.local.bash
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declaration/17f960fc/executors_sbatch_declaration_build.sh
______________________________
Launching test: executors_sbatch_declaration
Test ID: 17627bec-636c-42d2-a55b-0429bb94a7d7
Executor Name: generic.local.sh
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaration/17627bec/executors_sbatch_declaration_build.sh
+----------------------+
| Stage: Test Summary |
+----------------------+
name | id | executor | status | returncode_match | regex_match | runtime_match | returncode | runtime
------------------------------+----------+--------------------+----------+--------------------+---------------+-----------------+--------------+-----------
executors_sbatch_declaration | 17f960fc | generic.local.bash | PASS | N/A | N/A | N/A | 0 | 0.023433
executors_sbatch_declaration | 17627bec | generic.local.sh | PASS | N/A | N/A | N/A | 0 | 0.027592
Passed Tests: 2/2 Percentage: 100.000%
Failed Tests: 0/2 Percentage: 0.000%
Writing Logfile to: /tmp/buildtest_5mjf75ja.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest.log
If we inspect this test, we will see each each test have different #SBATCH directives for each test
based on the sbatch property defined in the executors field.
$ buildtest inspect query -d all -t executors_sbatch_declaration
______________________________ executors_sbatch_declaration (ID: 17f960fc-0691-4997-bd7f-b420d899a406) ______________________________
executor: generic.local.bash
description: Declaring env and vars by executors section
state: PASS
returncode: 0
runtime: 0.023433
starttime: 2021/09/09 15:55:02
endtime: 2021/09/09 15:55:02
************************* Start of Test Path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declaration/17f960fc/executors_sbatch_declaration.sh *************************
#!/bin/bash
####### START OF SCHEDULER DIRECTIVES #######
#SBATCH -n 4
#SBATCH -N 1
#SBATCH -t 30
#SBATCH --job-name=executors_sbatch_declaration
#SBATCH --output=executors_sbatch_declaration.out
#SBATCH --error=executors_sbatch_declaration.err
####### END OF SCHEDULER DIRECTIVES #######
# Content of run section
hostname
************************* End of Test Path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declaration/17f960fc/executors_sbatch_declaration.sh *************************
______________________________ executors_sbatch_declaration (ID: 17627bec-636c-42d2-a55b-0429bb94a7d7) ______________________________
executor: generic.local.sh
description: Declaring env and vars by executors section
state: PASS
returncode: 0
runtime: 0.027592
starttime: 2021/09/09 15:55:02
endtime: 2021/09/09 15:55:02
************************* Start of Test Path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaration/17627bec/executors_sbatch_declaration.sh *************************
#!/bin/bash
####### START OF SCHEDULER DIRECTIVES #######
#SBATCH -n 8
#SBATCH -N 1
#SBATCH -t 60
#SBATCH --job-name=executors_sbatch_declaration
#SBATCH --output=executors_sbatch_declaration.out
#SBATCH --error=executors_sbatch_declaration.err
####### END OF SCHEDULER DIRECTIVES #######
# Content of run section
hostname
************************* End of Test Path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaration/17627bec/executors_sbatch_declaration.sh *************************
Cray Burst Buffer and Data Warp¶
You can also define BB and DW directives in the executors field to override
cray burst buffer and data warp settings per executor. buildtest will use the fields BB
and DW and insert the #BB and #DW directives in the job script. For more details
see Cray Burst Buffer & Data Warp.
version: "1.0"
buildspecs:
create_burst_buffer_multiple_executors:
type: script
executor: "generic.local.(sh|bash)"
sbatch: ["-N 1", "-t 10", "-C knl"]
description: Create a burst buffer for multiple executors
tags: [jobs]
executors:
generic.local.sh:
BB:
- create_persistent name=buffer1 capacity=10GB access_mode=striped type=scratch
DW:
- persistentdw name=buffer1
generic.local.bash:
BB:
- create_persistent name=buffer2 capacity=10GB access_mode=striped type=scratch
DW:
- persistentdw name=buffer2
run: hostname
Status and Metrics Field¶
The status and metrics field are supported in executors
which can be defined within the named executor. In this next example, we will define generic.local.bash to match
test based on returncode 0 or 2 and define metrics named firstname that is assigned the value
from variable FIRST. The second test using generic.local.sh will match returncode of 1 and
define a metrics named lastname that will store the value defined by variable LAST.
version: "1.0"
buildspecs:
status_returncode_by_executors:
type: script
executor: "generic.local.(bash|sh)"
description: define status and metrics per executor type.
tags: [tutorials]
vars:
FIRST: Michael
LAST: Jackson
run: echo "my name is $FIRST $LAST"
executors:
generic.local.bash:
status:
returncode: [0, 2]
metrics:
firstname:
vars: "FIRST"
generic.local.sh:
status:
returncode: 1
metrics:
lastname:
vars: "LAST"
Now let’s run this test and we will see the test using generic.local.sh will fail because we have a returncode mismatch even though both tests got a 0 returncode as its actual value.
$ buildtest build -b tutorials/script/status_by_executors.yml
User: docs
Hostname: build-14673784-project-280831-buildtest
Platform: Linux
Current Time: 2021/09/09 15:55:03
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest
buildtest version: 0.11.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.11.0/bin/python
python version: 3.7.9
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest build -b tutorials/script/status_by_executors.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+-----------------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+=======================================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/script/status_by_executors.yml |
+-----------------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/script/status_by_executors.yml: VALID
Total builder objects created: 2
builders: [status_returncode_by_executors/8af6a3ff, status_returncode_by_executors/912c478d]
name id description buildspecs
------------------------------ -------- -------------------------------------------- ---------------------------------------------------------------------------------------------------------------------
status_returncode_by_executors 8af6a3ff define status and metrics per executor type. /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/script/status_by_executors.yml
status_returncode_by_executors 912c478d define status and metrics per executor type. /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/script/status_by_executors.yml
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
--------------------------------+----------+--------+--------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
status_returncode_by_executors | 8af6a3ff | script | generic.local.bash | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_by_executors/status_returncode_by_executors/8af6a3ff/status_returncode_by_executors_build.sh
status_returncode_by_executors | 912c478d | script | generic.local.sh | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/status_by_executors/status_returncode_by_executors/912c478d/status_returncode_by_executors_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
status_returncode_by_executors/912c478d: completed with returncode: 0
status_returncode_by_executors/912c478d: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/status_by_executors/status_returncode_by_executors/912c478d/status_returncode_by_executors.out
status_returncode_by_executors/912c478d: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/status_by_executors/status_returncode_by_executors/912c478d/status_returncode_by_executors.err
status_returncode_by_executors/912c478d: Checking returncode - 0 is matched in list [1]
status_returncode_by_executors/8af6a3ff: completed with returncode: 0
status_returncode_by_executors/8af6a3ff: Writing output file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_by_executors/status_returncode_by_executors/8af6a3ff/status_returncode_by_executors.out
status_returncode_by_executors/8af6a3ff: Writing error file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_by_executors/status_returncode_by_executors/8af6a3ff/status_returncode_by_executors.err
status_returncode_by_executors/8af6a3ff: Checking returncode - 0 is matched in list [0, 2]
______________________________
Launching test: status_returncode_by_executors
Test ID: 8af6a3ff-a9d9-4db7-8782-6cc477deb384
Executor Name: generic.local.bash
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_by_executors/status_returncode_by_executors/8af6a3ff/status_returncode_by_executors_build.sh
______________________________
Launching test: status_returncode_by_executors
Test ID: 912c478d-85ba-4ef7-b1f4-48ca351a1cfb
Executor Name: generic.local.sh
Running Test: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.sh/status_by_executors/status_returncode_by_executors/912c478d/status_returncode_by_executors_build.sh
+----------------------+
| Stage: Test Summary |
+----------------------+
name | id | executor | status | returncode_match | regex_match | runtime_match | returncode | runtime
--------------------------------+----------+--------------------+----------+--------------------+---------------+-----------------+--------------+-----------
status_returncode_by_executors | 8af6a3ff | generic.local.bash | PASS | True | False | False | 0 | 0.020059
status_returncode_by_executors | 912c478d | generic.local.sh | FAIL | False | False | False | 0 | 0.013939
Passed Tests: 1/2 Percentage: 50.000%
Failed Tests: 1/2 Percentage: 50.000%
Writing Logfile to: /tmp/buildtest_78rzfc0s.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest.log
Now let’s see the test results by inspecting the metrics field using buildtest report. We see one test
has the metrics name firstname=Michael and second test has lastname=Jackson.
$ buildtest report --format id,name,metrics --filter name=status_returncode_by_executors
Reading report file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/report.json
+----------+--------------------------------+-------------------+
| id | name | metrics |
+==========+================================+===================+
| 8af6a3ff | status_returncode_by_executors | firstname=Michael |
+----------+--------------------------------+-------------------+
| 912c478d | status_returncode_by_executors | lastname=Jackson |
+----------+--------------------------------+-------------------+
run_only¶
The run_only property is used for running test given a specific condition has met.
For example, you may want a test to run only if its particular system (Linux, Darwin),
operating system, scheduler, etc…
run_only - user¶
buildtest will skip test if any of the conditions are not met. Let’s take an example
in this buildspec we define a test name run_only_as_root that requires root user
to run test. The run_only is a property of key/value pairs and user is one
of the field. buildtest will only build & run test if current user matches user field.
We detect current user using $USER and match with input field user.
buildtest will skip test if there is no match.
version: "1.0"
buildspecs:
run_only_as_root:
description: "This test will only run if current user is root"
executor: generic.local.bash
type: script
tags: ["tutorials"]
run_only:
user: root
run: echo $USER
Now if we run this test we see buildtest will skip test run_only_as_root because current user is not root.
$ buildtest build -b tutorials/root_user.yml
User: docs
Hostname: build-14673784-project-280831-buildtest
Platform: Linux
Current Time: 2021/09/09 15:55:03
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest
buildtest version: 0.11.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.11.0/bin/python
python version: 3.7.9
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest build -b tutorials/root_user.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+======================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/root_user.yml |
+------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
[run_only_as_root][/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/root_user.yml]: test is skipped because this test is expected to run as user: root but detected user: None.
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/root_user.yml: VALID
Unable to create any builder objects
run_only - platform¶
Similarly, we can run test if it matches target platform. In this example we have
two tests run_only_platform_darwin and run_only_platform_linux that are
run if target platform is Darwin or Linux. This is configured using platform
field which is a property of run_only object. buildtest will match
target platform using platform.system()
with field platform, if there is no match buildtest will skip test. In this test,
we define a python shell using shell: python and run platform.system(). We
expect the output of each test to have Darwin and Linux which we match
with stdout using regular expression.
version: "1.0"
buildspecs:
run_only_platform_darwin:
description: "This test will only run if target platform is Darwin"
executor: generic.local.python
type: script
tags: ["tutorials"]
run_only:
platform: Darwin
shell: python
run: |
import platform
print(platform.system())
status:
regex:
stream: stdout
exp: "^Darwin$"
run_only_platform_linux:
description: "This test will only run if target platform is Linux"
executor: generic.local.python
type: script
tags: ["tutorials"]
run_only:
platform: Linux
shell: python
run: |
import platform
print(platform.system())
status:
regex:
stream: stdout
exp: "^Linux"
This test was ran on a MacOS (Darwin) so we expect test run_only_platform_linux to be skipped.
$ buildtest build -b tutorials/run_only_platform.yml
User: siddiq90
Hostname: DOE-7086392.local
Platform: Darwin
Current Time: 2021/07/06 18:54:27
buildtest path: /Users/siddiq90/Documents/GitHubDesktop/buildtest/bin/buildtest
buildtest version: 0.9.6
python path: /Users/siddiq90/.local/share/virtualenvs/buildtest-KLOcDrW0/bin/python
python version: 3.7.3
Test Directory: /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests
Configuration File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest/settings/config.yml
Command: /Users/siddiq90/Documents/GitHubDesktop/buildtest/bin/buildtest build -b tutorials/run_only_platform.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+-----------------------------------------------------------------------------------+
| Discovered Buildspecs |
+===================================================================================+
| /Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/run_only_platform.yml |
+-----------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
[run_only_platform_linux][/Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/run_only_platform.yml]: test is skipped because this test is expected to run on platform: Linux but detected platform: Darwin.
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
-------------------------+--------------+-----------------------------------------------------------------------------------
script-v1.0.schema.json | True | /Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/run_only_platform.yml
name description
------------------------ ----------------------------------------------------
run_only_platform_darwin This test will only run if target platform is Darwin
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
--------------------------+----------+--------+----------------------+---------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------
run_only_platform_darwin | 964e3016 | script | generic.local.python | ['tutorials'] | /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.python/run_only_platform/run_only_platform_darwin/3/run_only_platform_darwin_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
name | id | executor | status | returncode
--------------------------+----------+----------------------+----------+--------------
run_only_platform_darwin | 964e3016 | generic.local.python | PASS | 0
+----------------------+
| Stage: Test Summary |
+----------------------+
Passed Tests: 1/1 Percentage: 100.000%
Failed Tests: 0/1 Percentage: 0.000%
Writing Logfile to: /var/folders/1m/_jjv09h17k37mkktwnmbkmj0002t_q/T/buildtest__md43sa1.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest.log
run_only - scheduler¶
buildtest can run test if a particular scheduler is available. In this example,
we introduce a new field scheduler that is part of run_only property. This
field expects one of the following values: [lsf, slurm, cobalt, pbs]
and buildtest will check if target system supports detects the scheduler. In this example we require
lsf scheduler because this test runs bmgroup which is a LSF binary.
Note
buildtest assumes scheduler binaries are available in $PATH, if no scheduler is found buildtest sets this to an empty list
version: "1.0"
buildspecs:
show_host_groups:
type: script
executor: generic.local.bash
description: Show information about host groups using bmgroup
tags: lsf
run_only:
scheduler: lsf
run: bmgroup
If we build this test on a target system without LSF notice that buildtest skips test show_host_groups.
$ buildtest build -b general_tests/sched/lsf/bmgroups.yml
User: docs
Hostname: build-14673784-project-280831-buildtest
Platform: Linux
Current Time: 2021/09/09 15:55:04
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest
buildtest version: 0.11.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.11.0/bin/python
python version: 3.7.9
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest build -b general_tests/sched/lsf/bmgroups.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+-------------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+===================================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/general_tests/sched/lsf/bmgroups.yml |
+-------------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
[show_host_groups][/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/general_tests/sched/lsf/bmgroups.yml]: test is skipped because ['run_only']['scheduler'] got value: lsf but detected scheduler: [].
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/general_tests/sched/lsf/bmgroups.yml: VALID
Unable to create any builder objects
run_only - linux_distro¶
buildtest can run test if it matches a Linux distro, this is configured using
linux_distro field that is a list of Linux distros that is returned via
distro.id(). In this example,
we run test only if host distro is darwin.
version: "1.0"
buildspecs:
run_only_macos_distro:
type: script
executor: generic.local.bash
description: "Run test only if distro is darwin."
tags: [mac]
run_only:
linux_distro:
- darwin
run: uname
status:
regex:
stream: stdout
exp: "^Darwin$"
run_only_linux_distro:
type: script
executor: generic.local.bash
description: "Run test only if distro is CentOS."
tags: [mac]
run_only:
linux_distro:
- centos
run: uname
This test will run successfully because this was ran on a Mac OS (darwin) system.
$ buildtest build -b tutorials/run_only_distro.yml
User: siddiq90
Hostname: DOE-7086392.local
Platform: Darwin
Current Time: 2021/07/06 18:54:28
buildtest path: /Users/siddiq90/Documents/GitHubDesktop/buildtest/bin/buildtest
buildtest version: 0.9.6
python path: /Users/siddiq90/.local/share/virtualenvs/buildtest-KLOcDrW0/bin/python
python version: 3.7.3
Test Directory: /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests
Configuration File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest/settings/config.yml
Command: /Users/siddiq90/Documents/GitHubDesktop/buildtest/bin/buildtest build -b tutorials/run_only_distro.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+---------------------------------------------------------------------------------+
| Discovered Buildspecs |
+=================================================================================+
| /Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/run_only_distro.yml |
+---------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
[run_only_linux_distro][/Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/run_only_distro.yml]: test is skipped because this test is expected to run on linux distro: ['centos'] but detected linux distro: darwin.
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
-------------------------+--------------+---------------------------------------------------------------------------------
script-v1.0.schema.json | True | /Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/run_only_distro.yml
name description
--------------------- ----------------------------------
run_only_macos_distro Run test only if distro is darwin.
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
-----------------------+----------+--------+--------------------+---------+-------------------------------------------------------------------------------------------------------------------------------------------------------
run_only_macos_distro | 9d4d0d97 | script | generic.local.bash | ['mac'] | /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/run_only_distro/run_only_macos_distro/0/run_only_macos_distro_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
name | id | executor | status | returncode
-----------------------+----------+--------------------+----------+--------------
run_only_macos_distro | 9d4d0d97 | generic.local.bash | PASS | 0
+----------------------+
| Stage: Test Summary |
+----------------------+
Passed Tests: 1/1 Percentage: 100.000%
Failed Tests: 0/1 Percentage: 0.000%
Writing Logfile to: /var/folders/1m/_jjv09h17k37mkktwnmbkmj0002t_q/T/buildtest_6asbja74.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest.log