Buildspec Overview¶
What is a buildspec?¶
A buildspec is a YAML file that defines your test in buildtest which is validated by schema followed by building a shell script and running the generated test. Buildtest will parse the buildspec with the global schema file which defines the top-level structure of buildspec file.
Example¶
Let’s start off with a simple example that declares two variables X and Y and prints the sum of X+Y.
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.
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:
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. The description field is limited to 80 characters.
In this example we can specify multiple commands in run
section, this
can be done in YAML using run: |
followed by content of run section tab indented
2 spaces.
In this next example, we introduce the summary
field, which can be used as an extended description of test. It has no
impact on the test. Unlike the description
field, the summary field has no limit on character count and one can define multi-line
string using the pipe symbol |.
buildspecs:
summary_example:
type: script
executor: generic.local.bash
description: The summary field can be a multi-line string and exceed 80 char
tags: [tutorials]
summary: |
This is a long description of test that
can exceed 80 characters and be multiline
run: hostname
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.schema.json.
{
"$id": "script.schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "script schema version",
"description": "The script schema is of ``type: script`` in sub-schema which is used for running shell scripts",
"type": "object",
"required": [
"type",
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
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.
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`"
multiline_string: |
Hello my name is Bob \n
I am 30 years old
run: |
echo "$X+$Y="$(($X+$Y))
echo $literalstring
echo $singlequote
echo $doublequote
echo "current user:" $current_user
echo "number of files:" $num_files
echo -e $multiline_string
Next we build this test by running buildtest build -b $BUILDTEST_ROOT/tutorials/vars.yml
.
buildtest build -b $BUILDTEST_ROOT/tutorials/vars.yml
$ buildtest build -b $BUILDTEST_ROOT/tutorials/vars.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:14 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/vars.yml: VALID
Total builder objects created: 1
Total compiler builder: 0
Total script builder: 1
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ variables… │ generic.l… │ None │ None │ None │ Declare │ /home/doc… │
│ │ │ │ │ │ shell │ │
│ │ │ │ │ │ variables │ │
│ │ │ │ │ │ in bash │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
variables_bash/8f92e8f4: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/vars/variables_bash/8f92e8f4
variables_bash/8f92e8f4: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/vars/variables_bash/8f92e8f4/stage
variables_bash/8f92e8f4: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/vars/variables_bash/8f92e8f4/variables_bash_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
variables_bash/8f92e8f4 does not have any dependencies adding test to queue
variables_bash/8f92e8f4: Running Test via command: bash --norc --noprofile -eo pipefail variables_bash_build.sh
variables_bash/8f92e8f4: Test completed in 0.010681 seconds
variables_bash/8f92e8f4: Test completed with returncode: 0
variables_bash/8f92e8f4: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/vars/variables_bash/8f92e8f4/variables_bash.out
variables_bash/8f92e8f4: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/vars/variables_bash/8f92e8f4/variables_bash.err
In this iteration we are going to run the following tests: [variables_bash/8f92e8f4]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ variables_ba │ generic.loc… │ PASS │ N/A N/A N/A │ 0 │ 0.010681 │
│ sh/8f92e8f4 │ │ │ │ │ │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘
Passed Tests: 1/1 Percentage: 100.000%
Failed Tests: 0/1 Percentage: 0.000%
Adding 1 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_5rir65d3.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
$ buildtest inspect query -o variables_bash
───────────── variables_bash/8f92e8f4-bedf-43ca-8583-00a2a189ad1a ──────────────
Executor: generic.local.bash
Description: Declare shell variables in bash
State: PASS
Returncode: 0
Runtime: 0.010681 sec
Starttime: 2022/10/14 14:50:14
Endtime: 2022/10/14 14:50:14
Command: bash --norc --noprofile -eo pipefail variables_bash_build.sh
Test Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/vars/variables_bash/8f92e8f4/variables_bash.sh
Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/vars/variables_bash/8f92e8f4/variables_bash_build.sh
Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/vars/variables_bash/8f92e8f4/variables_bash.out
Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/vars/variables_bash/8f92e8f4/variables_bash.err
Log File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_5rir65d3.log
─ Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/che… ─
1+2=3
this is a literal string
\'singlequote\'
"doublequote"
current user: docs
number of files: 4
Hello my name is Bob
I am 30 years old
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
.
buildspecs:
exit1_fail:
executor: generic.local.bash
type: script
description: exit 1 by default is FAIL
tags: [tutorials, fail]
run: exit 1
exit1_pass:
executor: generic.local.bash
type: script
description: report exit 1 as PASS
run: exit 1
tags: [tutorials, pass]
status:
returncode: [1]
returncode_list_mismatch:
executor: generic.local.bash
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.bash
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/test_status/pass_returncode.yml
$ buildtest build -b tutorials/test_status/pass_returncode.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:15 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/test_status/pass_returncode.yml: VALID
Total builder objects created: 4
Total compiler builder: 0
Total script builder: 4
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ exit1_fai… │ generic.l… │ None │ None │ None │ exit 1 by │ /home/doc… │
│ │ │ │ │ │ default is │ │
│ │ │ │ │ │ FAIL │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ exit1_pas… │ generic.l… │ None │ None │ None │ report │ /home/doc… │
│ │ │ │ │ │ exit 1 as │ │
│ │ │ │ │ │ PASS │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ returncod… │ generic.l… │ None │ None │ None │ exit 2 │ /home/doc… │
│ │ │ │ │ │ failed │ │
│ │ │ │ │ │ since it │ │
│ │ │ │ │ │ failed to │ │
│ │ │ │ │ │ match │ │
│ │ │ │ │ │ returncode │ │
│ │ │ │ │ │ 1 │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ returncod… │ generic.l… │ None │ None │ None │ exit 128 │ /home/doc… │
│ │ │ │ │ │ matches │ │
│ │ │ │ │ │ returncode │ │
│ │ │ │ │ │ 128 │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
exit1_fail/f1a282fe: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/exit1_fail/f1a282fe
exit1_fail/f1a282fe: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/exit1_fail/f1a282fe/stage
exit1_fail/f1a282fe: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/exit1_fail/f1a282fe/exit1_fail_build.sh
exit1_pass/0d6611d4: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/exit1_pass/0d6611d4
exit1_pass/0d6611d4: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/exit1_pass/0d6611d4/stage
exit1_pass/0d6611d4: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/exit1_pass/0d6611d4/exit1_pass_build.sh
returncode_list_mismatch/c34d8c98: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/returncode_list_mismatch/c34d8c98
returncode_list_mismatch/c34d8c98: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/returncode_list_mismatch/c34d8c98/stage
returncode_list_mismatch/c34d8c98: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/returncode_list_mismatch/c34d8c98/returncode_list_mismatch_build.sh
returncode_int_match/cb4c70f4: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/returncode_int_match/cb4c70f4
returncode_int_match/cb4c70f4: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/returncode_int_match/cb4c70f4/stage
returncode_int_match/cb4c70f4: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/returncode_int_match/cb4c70f4/returncode_int_match_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
exit1_fail/f1a282fe does not have any dependencies adding test to queue
returncode_list_mismatch/c34d8c98 does not have any dependencies adding test to queue
returncode_int_match/cb4c70f4 does not have any dependencies adding test to queue
exit1_pass/0d6611d4 does not have any dependencies adding test to queue
exit1_fail/f1a282fe: Running Test via command: bash --norc --noprofile -eo pipefail exit1_fail_build.sh
exit1_fail/f1a282fe: Test completed in 0.005817 seconds
exit1_fail/f1a282fe: Test completed with returncode: 1
exit1_fail/f1a282fe: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/exit1_fail/f1a282fe/exit1_fail.out
exit1_fail/f1a282fe: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/exit1_fail/f1a282fe/exit1_fail.err
returncode_list_mismatch/c34d8c98: Running Test via command: bash --norc --noprofile -eo pipefail returncode_list_mismatch_build.sh
returncode_list_mismatch/c34d8c98: Test completed in 0.005482 seconds
returncode_list_mismatch/c34d8c98: Test completed with returncode: 2
returncode_list_mismatch/c34d8c98: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/returncode_list_mismatch/c34d8c98/returncode_list_mismatch.out
returncode_list_mismatch/c34d8c98: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/returncode_list_mismatch/c34d8c98/returncode_list_mismatch.err
returncode_list_mismatch/c34d8c98: Checking returncode - 2 is matched in list [1, 3]
returncode_int_match/cb4c70f4: Running Test via command: bash --norc --noprofile -eo pipefail returncode_int_match_build.sh
returncode_int_match/cb4c70f4: Test completed in 0.005694 seconds
returncode_int_match/cb4c70f4: Test completed with returncode: 128
returncode_int_match/cb4c70f4: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/returncode_int_match/cb4c70f4/returncode_int_match.out
returncode_int_match/cb4c70f4: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/returncode_int_match/cb4c70f4/returncode_int_match.err
returncode_int_match/cb4c70f4: Checking returncode - 128 is matched in list [128]
exit1_pass/0d6611d4: Running Test via command: bash --norc --noprofile -eo pipefail exit1_pass_build.sh
exit1_pass/0d6611d4: Test completed in 0.005397 seconds
exit1_pass/0d6611d4: Test completed with returncode: 1
exit1_pass/0d6611d4: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/exit1_pass/0d6611d4/exit1_pass.out
exit1_pass/0d6611d4: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/pass_returncode/exit1_pass/0d6611d4/exit1_pass.err
exit1_pass/0d6611d4: Checking returncode - 1 is matched in list [1]
In this iteration we are going to run the following tests: [exit1_fail/f1a282fe, returncode_list_mismatch/c34d8c98, returncode_int_match/cb4c70f4, exit1_pass/0d6611d4]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ returncode_l │ generic.loc… │ FAIL │ False False │ 2 │ 0.005482 │
│ ist_mismatch │ │ │ False │ │ │
│ /c34d8c98 │ │ │ │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ exit1_fail/f │ generic.loc… │ FAIL │ N/A N/A N/A │ 1 │ 0.005817 │
│ 1a282fe │ │ │ │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ exit1_pass/0 │ generic.loc… │ PASS │ True False │ 1 │ 0.005397 │
│ d6611d4 │ │ │ False │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ returncode_i │ generic.loc… │ PASS │ True False │ 128 │ 0.005694 │
│ nt_match/cb4 │ │ │ False │ │ │
│ c70f4 │ │ │ │ │ │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘
Passed Tests: 2/4 Percentage: 50.000%
Failed Tests: 2/4 Percentage: 50.000%
Adding 4 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_mwl2nyhj.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.
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/test_status/status_regex.yml
$ buildtest build -b tutorials/test_status/status_regex.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:16 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/test_status/status_regex.yml: VALID
Total builder objects created: 2
Total compiler builder: 0
Total script builder: 2
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ status_re… │ generic.l… │ None │ None │ None │ Pass test │ /home/doc… │
│ │ │ │ │ │ based on │ │
│ │ │ │ │ │ regular │ │
│ │ │ │ │ │ expression │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ status_re… │ generic.l… │ None │ None │ None │ Pass test │ /home/doc… │
│ │ │ │ │ │ based on │ │
│ │ │ │ │ │ regular │ │
│ │ │ │ │ │ expression │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
status_regex_pass/bc7d53c6: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_regex/status_regex_pass/bc7d53c6
status_regex_pass/bc7d53c6: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_regex/status_regex_pass/bc7d53c6/stage
status_regex_pass/bc7d53c6: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_regex/status_regex_pass/bc7d53c6/status_regex_pass_build.sh
status_regex_fail/9170fd8e: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_regex/status_regex_fail/9170fd8e
status_regex_fail/9170fd8e: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_regex/status_regex_fail/9170fd8e/stage
status_regex_fail/9170fd8e: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_regex/status_regex_fail/9170fd8e/status_regex_fail_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
status_regex_pass/bc7d53c6 does not have any dependencies adding test to queue
status_regex_fail/9170fd8e does not have any dependencies adding test to queue
status_regex_pass/bc7d53c6: Running Test via command: bash --norc --noprofile -eo pipefail status_regex_pass_build.sh
status_regex_pass/bc7d53c6: Test completed in 0.005762 seconds
status_regex_pass/bc7d53c6: Test completed with returncode: 0
status_regex_pass/bc7d53c6: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_regex/status_regex_pass/bc7d53c6/status_regex_pass.out
status_regex_pass/bc7d53c6: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_regex/status_regex_pass/bc7d53c6/status_regex_pass.err
status_regex_pass/bc7d53c6: performing regular expression - '^(PASS)$' on file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_regex/status_regex_pass/bc7d53c6/status_regex_pass.out
status_regex_pass/bc7d53c6: Regular Expression Match - Success!
status_regex_fail/9170fd8e: Running Test via command: bash --norc --noprofile -eo pipefail status_regex_fail_build.sh
status_regex_fail/9170fd8e: Test completed in 0.005654 seconds
status_regex_fail/9170fd8e: Test completed with returncode: 0
status_regex_fail/9170fd8e: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_regex/status_regex_fail/9170fd8e/status_regex_fail.out
status_regex_fail/9170fd8e: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_regex/status_regex_fail/9170fd8e/status_regex_fail.err
status_regex_fail/9170fd8e: performing regular expression - '^(123FAIL)$' on file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_regex/status_regex_fail/9170fd8e/status_regex_fail.out
status_regex_fail/9170fd8e: Regular Expression Match - Failed!
In this iteration we are going to run the following tests: [status_regex_pass/bc7d53c6, status_regex_fail/9170fd8e]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ status_regex │ generic.loc… │ PASS │ False True │ 0 │ 0.005762 │
│ _pass/bc7d53 │ │ │ False │ │ │
│ c6 │ │ │ │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ status_regex │ generic.loc… │ FAIL │ False False │ 0 │ 0.005654 │
│ _fail/9170fd │ │ │ False │ │ │
│ 8e │ │ │ │ │ │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘
Passed Tests: 1/2 Percentage: 50.000%
Failed Tests: 1/2 Percentage: 50.000%
Adding 2 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_8clpqkkh.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.
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/test_status/runtime_status_test.yml
$ buildtest build -b tutorials/test_status/runtime_status_test.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:17 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/test_status/runtime_status_test.yml: VALID
Total builder objects created: 5
Total compiler builder: 0
Total script builder: 5
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ timelimit… │ generic.l… │ None │ None │ None │ Run a │ /home/doc… │
│ │ │ │ │ │ sleep job │ │
│ │ │ │ │ │ for 2 │ │
│ │ │ │ │ │ seconds │ │
│ │ │ │ │ │ and test │ │
│ │ │ │ │ │ pass if │ │
│ │ │ │ │ │ its within │ │
│ │ │ │ │ │ 1.0-3.0sec │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ timelimit… │ generic.l… │ None │ None │ None │ Run a │ /home/doc… │
│ │ │ │ │ │ sleep job │ │
│ │ │ │ │ │ for 2 │ │
│ │ │ │ │ │ seconds │ │
│ │ │ │ │ │ and test │ │
│ │ │ │ │ │ pass if │ │
│ │ │ │ │ │ its │ │
│ │ │ │ │ │ exceeds │ │
│ │ │ │ │ │ min time │ │
│ │ │ │ │ │ of 1.0 sec │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ timelimit… │ generic.l… │ None │ None │ None │ Run a │ /home/doc… │
│ │ │ │ │ │ sleep job │ │
│ │ │ │ │ │ for 2 │ │
│ │ │ │ │ │ seconds │ │
│ │ │ │ │ │ and test │ │
│ │ │ │ │ │ pass if │ │
│ │ │ │ │ │ it's │ │
│ │ │ │ │ │ within max │ │
│ │ │ │ │ │ time: 5.0 │ │
│ │ │ │ │ │ sec │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ timelimit… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ fails │ │
│ │ │ │ │ │ because it │ │
│ │ │ │ │ │ runs less │ │
│ │ │ │ │ │ than │ │
│ │ │ │ │ │ mintime of │ │
│ │ │ │ │ │ 10 second │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ timelimit… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ fails │ │
│ │ │ │ │ │ because it │ │
│ │ │ │ │ │ exceeds │ │
│ │ │ │ │ │ maxtime of │ │
│ │ │ │ │ │ 1.0 second │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
timelimit_min_max/73c9f453: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_max/73c9f453
timelimit_min_max/73c9f453: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_max/73c9f453/stage
timelimit_min_max/73c9f453: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_max/73c9f453/timelimit_min_max_build.sh
timelimit_min/cebb2601: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min/cebb2601
timelimit_min/cebb2601: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min/cebb2601/stage
timelimit_min/cebb2601: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min/cebb2601/timelimit_min_build.sh
timelimit_max/5365bdf0: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max/5365bdf0
timelimit_max/5365bdf0: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max/5365bdf0/stage
timelimit_max/5365bdf0: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max/5365bdf0/timelimit_max_build.sh
timelimit_min_fail/d772eab7: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_fail/d772eab7
timelimit_min_fail/d772eab7: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_fail/d772eab7/stage
timelimit_min_fail/d772eab7: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_fail/d772eab7/timelimit_min_fail_build.sh
timelimit_max_fail/9b72321d: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max_fail/9b72321d
timelimit_max_fail/9b72321d: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max_fail/9b72321d/stage
timelimit_max_fail/9b72321d: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max_fail/9b72321d/timelimit_max_fail_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
timelimit_min_fail/d772eab7 does not have any dependencies adding test to queue
timelimit_min/cebb2601 does not have any dependencies adding test to queue
timelimit_max_fail/9b72321d does not have any dependencies adding test to queue
timelimit_min_max/73c9f453 does not have any dependencies adding test to queue
timelimit_max/5365bdf0 does not have any dependencies adding test to queue
timelimit_min_fail/d772eab7: Running Test via command: sh --norc --noprofile -eo pipefail timelimit_min_fail_build.sh
timelimit_min_fail/d772eab7: Test completed in 0.003365 seconds
timelimit_min_fail/d772eab7: Test completed with returncode: 2
timelimit_min_fail/d772eab7: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_fail/d772eab7/timelimit_min_fail.out
timelimit_min_fail/d772eab7: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_fail/d772eab7/timelimit_min_fail.err
timelimit_max_fail/9b72321d: Running Test via command: sh --norc --noprofile -eo pipefail timelimit_max_fail_build.sh
timelimit_max_fail/9b72321d: Test completed in 0.003183 seconds
timelimit_max_fail/9b72321d: Test completed with returncode: 2
timelimit_max_fail/9b72321d: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max_fail/9b72321d/timelimit_max_fail.out
timelimit_max_fail/9b72321d: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max_fail/9b72321d/timelimit_max_fail.err
timelimit_min/cebb2601: Running Test via command: sh --norc --noprofile -eo pipefail timelimit_min_build.sh
timelimit_min/cebb2601: Test completed in 0.003179 seconds
timelimit_min/cebb2601: Test completed with returncode: 2
timelimit_min/cebb2601: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min/cebb2601/timelimit_min.out
timelimit_min/cebb2601: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min/cebb2601/timelimit_min.err
timelimit_min_max/73c9f453: Running Test via command: sh --norc --noprofile -eo pipefail timelimit_min_max_build.sh
timelimit_min_max/73c9f453: Test completed in 0.00322 seconds
timelimit_min_max/73c9f453: Test completed with returncode: 2
timelimit_min_max/73c9f453: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_max/73c9f453/timelimit_min_max.out
timelimit_min_max/73c9f453: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_min_max/73c9f453/timelimit_min_max.err
timelimit_max/5365bdf0: Running Test via command: sh --norc --noprofile -eo pipefail timelimit_max_build.sh
timelimit_max/5365bdf0: Test completed in 0.003219 seconds
timelimit_max/5365bdf0: Test completed with returncode: 2
timelimit_max/5365bdf0: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max/5365bdf0/timelimit_max.out
timelimit_max/5365bdf0: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/runtime_status_test/timelimit_max/5365bdf0/timelimit_max.err
In this iteration we are going to run the following tests: [timelimit_min_fail/d772eab7, timelimit_max_fail/9b72321d, timelimit_min/cebb2601, timelimit_min_max/73c9f453, timelimit_max/5365bdf0]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ timelimit_mi │ generic.loc… │ FAIL │ False False │ 2 │ 0.003365 │
│ n_fail/d772e │ │ │ False │ │ │
│ ab7 │ │ │ │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ timelimit_ma │ generic.loc… │ PASS │ False False │ 2 │ 0.003219 │
│ x/5365bdf0 │ │ │ True │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ timelimit_ma │ generic.loc… │ PASS │ False False │ 2 │ 0.003183 │
│ x_fail/9b723 │ │ │ True │ │ │
│ 21d │ │ │ │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ timelimit_mi │ generic.loc… │ FAIL │ False False │ 2 │ 0.003179 │
│ n/cebb2601 │ │ │ False │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ timelimit_mi │ generic.loc… │ FAIL │ False False │ 2 │ 0.00322 │
│ n_max/73c9f4 │ │ │ False │ │ │
│ 53 │ │ │ │ │ │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘
Passed Tests: 2/5 Percentage: 40.000%
Failed Tests: 3/5 Percentage: 60.000%
Adding 5 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_boysmct1.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/test_status/runtime_status_test.yml --format name,id,state,runtime --latest
$ buildtest report --filter buildspec=tutorials/test_status/runtime_status_test.yml --format name,id,state,runtime --latest
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ name ┃ id ┃ state ┃ runtime ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
│ timelimit_min_fail │ d772eab7 │ FAIL │ 0.003365 │
├────────────────────────────────┼────────────────┼────────────┼───────────────┤
│ timelimit_max │ 5365bdf0 │ PASS │ 0.003219 │
├────────────────────────────────┼────────────────┼────────────┼───────────────┤
│ timelimit_max_fail │ 9b72321d │ PASS │ 0.003183 │
├────────────────────────────────┼────────────────┼────────────┼───────────────┤
│ timelimit_min │ cebb2601 │ FAIL │ 0.003179 │
├────────────────────────────────┼────────────────┼────────────┼───────────────┤
│ timelimit_min_max │ 73c9f453 │ FAIL │ 0.00322 │
└────────────────────────────────┴────────────────┴────────────┴───────────────┘
Explicitly Declaring Status of Test¶
You can explicitly define status of test regardless of what buildtest does for checking status of test. This
can be useful if you want to explicitly mark a test as PASS or FAIL regardless of how test behaves. This can be done via
state
property which expects one of two types PASS or FAIL. If state
property is specified, buildtest will ignore any checks
including returncode, regex, or runtime match.
In this next example we will demonstrate how one can use state
property for marking test state. In this
example we have four tests. The first test always_pass
will PASS even though we have a non-zero returncode. The
second test always_fail
will FAIL even though it has a 0 returncode. The last two test demonstrate how one
can define state regardless of what is specified for returncode match. buildtest will honor the state
property even if
their is a match on the returncode.
buildspecs:
always_pass:
type: script
executor: 'generic.local.sh'
description: This test will always 'PASS'
run: exit 1
status:
state: PASS
always_fail:
type: script
executor: 'generic.local.sh'
description: This test will always 'FAIL'
run: exit 0
status:
state: FAIL
test_fail_returncode_match:
type: script
executor: 'generic.local.sh'
description: This test will 'FAIL' even if we have returncode match
run: exit 1
status:
state: FAIL
returncode: 1
test_pass_returncode_mismatch:
type: script
executor: 'generic.local.sh'
description: This test will 'PASS' even if we have returncode mismatch
run: exit 1
status:
state: PASS
returncode: 2
If we build this test, we expect buildtest to honor the value of state
property
buildtest build -b tutorials/test_status/explicit_state.yml
$ buildtest build -b tutorials/test_status/explicit_state.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:18 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/test_status/explicit_state.yml: VALID
Total builder objects created: 4
Total compiler builder: 0
Total script builder: 4
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ always_pa… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ will │ │
│ │ │ │ │ │ always │ │
│ │ │ │ │ │ 'PASS' │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ always_fa… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ will │ │
│ │ │ │ │ │ always │ │
│ │ │ │ │ │ 'FAIL' │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ test_fail… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ will │ │
│ │ │ │ │ │ 'FAIL' │ │
│ │ │ │ │ │ even if we │ │
│ │ │ │ │ │ have │ │
│ │ │ │ │ │ returncode │ │
│ │ │ │ │ │ match │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ test_pass… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ will │ │
│ │ │ │ │ │ 'PASS' │ │
│ │ │ │ │ │ even if we │ │
│ │ │ │ │ │ have │ │
│ │ │ │ │ │ returncode │ │
│ │ │ │ │ │ mismatch │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
always_pass/c9c787ff: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/always_pass/c9c787ff
always_pass/c9c787ff: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/always_pass/c9c787ff/stage
always_pass/c9c787ff: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/always_pass/c9c787ff/always_pass_build.sh
always_fail/d3ef1b16: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/always_fail/d3ef1b16
always_fail/d3ef1b16: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/always_fail/d3ef1b16/stage
always_fail/d3ef1b16: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/always_fail/d3ef1b16/always_fail_build.sh
test_fail_returncode_match/e0a34d94: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/test_fail_returncode_match/e0a34d94
test_fail_returncode_match/e0a34d94: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/test_fail_returncode_match/e0a34d94/stage
test_fail_returncode_match/e0a34d94: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/test_fail_returncode_match/e0a34d94/test_fail_returncode_match_build.sh
test_pass_returncode_mismatch/827f8841: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/test_pass_returncode_mismatch/827f8841
test_pass_returncode_mismatch/827f8841: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/test_pass_returncode_mismatch/827f8841/stage
test_pass_returncode_mismatch/827f8841: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/test_pass_returncode_mismatch/827f8841/test_pass_returncode_mismatch_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
always_pass/c9c787ff does not have any dependencies adding test to queue
test_pass_returncode_mismatch/827f8841 does not have any dependencies adding test to queue
always_fail/d3ef1b16 does not have any dependencies adding test to queue
test_fail_returncode_match/e0a34d94 does not have any dependencies adding test to queue
always_pass/c9c787ff: Running Test via command: sh --norc --noprofile -eo pipefail always_pass_build.sh
always_pass/c9c787ff: Test completed in 0.003314 seconds
always_pass/c9c787ff: Test completed with returncode: 2
always_pass/c9c787ff: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/always_pass/c9c787ff/always_pass.out
always_pass/c9c787ff: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/always_pass/c9c787ff/always_pass.err
test_pass_returncode_mismatch/827f8841: Running Test via command: sh --norc --noprofile -eo pipefail test_pass_returncode_mismatch_build.sh
test_pass_returncode_mismatch/827f8841: Test completed in 0.00301 seconds
test_pass_returncode_mismatch/827f8841: Test completed with returncode: 2
test_pass_returncode_mismatch/827f8841: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/test_pass_returncode_mismatch/827f8841/test_pass_returncode_mismatch.out
test_pass_returncode_mismatch/827f8841: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/test_pass_returncode_mismatch/827f8841/test_pass_returncode_mismatch.err
test_pass_returncode_mismatch/827f8841: Checking returncode - 2 is matched in list [2]
always_fail/d3ef1b16: Running Test via command: sh --norc --noprofile -eo pipefail always_fail_build.sh
always_fail/d3ef1b16: Test completed in 0.002996 seconds
always_fail/d3ef1b16: Test completed with returncode: 2
always_fail/d3ef1b16: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/always_fail/d3ef1b16/always_fail.out
always_fail/d3ef1b16: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/always_fail/d3ef1b16/always_fail.err
test_fail_returncode_match/e0a34d94: Running Test via command: sh --norc --noprofile -eo pipefail test_fail_returncode_match_build.sh
test_fail_returncode_match/e0a34d94: Test completed in 0.002924 seconds
test_fail_returncode_match/e0a34d94: Test completed with returncode: 2
test_fail_returncode_match/e0a34d94: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/test_fail_returncode_match/e0a34d94/test_fail_returncode_match.out
test_fail_returncode_match/e0a34d94: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/explicit_state/test_fail_returncode_match/e0a34d94/test_fail_returncode_match.err
test_fail_returncode_match/e0a34d94: Checking returncode - 2 is matched in list [1]
In this iteration we are going to run the following tests: [always_pass/c9c787ff, test_pass_returncode_mismatch/827f8841, always_fail/d3ef1b16, test_fail_returncode_match/e0a34d94]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ always_pass/ │ generic.loc… │ PASS │ False False │ 2 │ 0.003314 │
│ c9c787ff │ │ │ False │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ always_fail/ │ generic.loc… │ FAIL │ False False │ 2 │ 0.002996 │
│ d3ef1b16 │ │ │ False │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ test_pass_re │ generic.loc… │ PASS │ True False │ 2 │ 0.00301 │
│ turncode_mis │ │ │ False │ │ │
│ match/827f88 │ │ │ │ │ │
│ 41 │ │ │ │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ test_fail_re │ generic.loc… │ FAIL │ False False │ 2 │ 0.002924 │
│ turncode_mat │ │ │ False │ │ │
│ ch/e0a34d94 │ │ │ │ │ │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘
Passed Tests: 2/4 Percentage: 50.000%
Failed Tests: 2/4 Percentage: 50.000%
Adding 4 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_w_fs_v_4.log
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
.
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.
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.
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.
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.
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
$ buildtest build -b tutorials/shebang.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:18 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/shebang.yml: VALID
Total builder objects created: 2
Total compiler builder: 0
Total script builder: 2
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ bash_logi… │ generic.l… │ None │ None │ None │ customize │ /home/doc… │
│ │ │ │ │ │ shebang │ │
│ │ │ │ │ │ line with │ │
│ │ │ │ │ │ bash login │ │
│ │ │ │ │ │ shell │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ bash_nonl… │ generic.l… │ None │ None │ None │ customize │ /home/doc… │
│ │ │ │ │ │ shebang │ │
│ │ │ │ │ │ line with │ │
│ │ │ │ │ │ default │ │
│ │ │ │ │ │ bash │ │
│ │ │ │ │ │ (nonlogin) │ │
│ │ │ │ │ │ shell │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
bash_login_shebang/38fe662b: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/shebang/bash_login_shebang/38fe662b
bash_login_shebang/38fe662b: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/shebang/bash_login_shebang/38fe662b/stage
bash_login_shebang/38fe662b: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/shebang/bash_login_shebang/38fe662b/bash_login_shebang_build.sh
bash_nonlogin_shebang/4cf61725: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/shebang/bash_nonlogin_shebang/4cf61725
bash_nonlogin_shebang/4cf61725: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/shebang/bash_nonlogin_shebang/4cf61725/stage
bash_nonlogin_shebang/4cf61725: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/shebang/bash_nonlogin_shebang/4cf61725/bash_nonlogin_shebang_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
bash_login_shebang/38fe662b does not have any dependencies adding test to queue
bash_nonlogin_shebang/4cf61725 does not have any dependencies adding test to queue
bash_login_shebang/38fe662b: Running Test via command: bash --norc --noprofile -eo pipefail bash_login_shebang_build.sh
bash_login_shebang/38fe662b: Test completed in 0.07837 seconds
bash_login_shebang/38fe662b: Test completed with returncode: 0
bash_login_shebang/38fe662b: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/shebang/bash_login_shebang/38fe662b/bash_login_shebang.out
bash_login_shebang/38fe662b: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/shebang/bash_login_shebang/38fe662b/bash_login_shebang.err
bash_login_shebang/38fe662b: performing regular expression - '^Login Shell$' on file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/shebang/bash_login_shebang/38fe662b/bash_login_shebang.out
bash_login_shebang/38fe662b: Regular Expression Match - Success!
bash_nonlogin_shebang/4cf61725: Running Test via command: bash --norc --noprofile -eo pipefail bash_nonlogin_shebang_build.sh
bash_nonlogin_shebang/4cf61725: Test completed in 0.005785 seconds
bash_nonlogin_shebang/4cf61725: Test completed with returncode: 0
bash_nonlogin_shebang/4cf61725: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/shebang/bash_nonlogin_shebang/4cf61725/bash_nonlogin_shebang.out
bash_nonlogin_shebang/4cf61725: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/shebang/bash_nonlogin_shebang/4cf61725/bash_nonlogin_shebang.err
bash_nonlogin_shebang/4cf61725: performing regular expression - '^Not Login Shell$' on file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/shebang/bash_nonlogin_shebang/4cf61725/bash_nonlogin_shebang.out
bash_nonlogin_shebang/4cf61725: Regular Expression Match - Success!
In this iteration we are going to run the following tests: [bash_login_shebang/38fe662b, bash_nonlogin_shebang/4cf61725]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ bash_nonlogi │ generic.loc… │ PASS │ False True │ 0 │ 0.005785 │
│ n_shebang/4c │ │ │ False │ │ │
│ f61725 │ │ │ │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ bash_login_s │ generic.loc… │ PASS │ False True │ 0 │ 0.07837 │
│ hebang/38fe6 │ │ │ False │ │ │
│ 62b │ │ │ │ │ │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘
Passed Tests: 2/2 Percentage: 100.000%
Failed Tests: 0/2 Percentage: 0.000%
Adding 2 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_syf5buuw.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. In order to write python code you
must set shell
property to python interpreter such as `shell: python
or full path to python wrapper such
as shell: /usr/bin/python
.
Here is a python example calculating area of circle
buildspecs:
circle_area:
executor: generic.local.bash
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)
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 invoke the
python script in the 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.
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
$ buildtest build -b tutorials/skip_tests.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:19 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
skip: skipping test due to 'skip' property.
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/skip_tests.yml: VALID
Total builder objects created: 1
Total compiler builder: 0
Total script builder: 1
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ unskipped… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ is not │ │
│ │ │ │ │ │ skipped │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
unskipped/79e230a2: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/skip_tests/unskipped/79e230a2
unskipped/79e230a2: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/skip_tests/unskipped/79e230a2/stage
unskipped/79e230a2: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/skip_tests/unskipped/79e230a2/unskipped_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
unskipped/79e230a2 does not have any dependencies adding test to queue
unskipped/79e230a2: Running Test via command: bash --norc --noprofile -eo pipefail unskipped_build.sh
unskipped/79e230a2: Test completed in 0.008253 seconds
unskipped/79e230a2: Test completed with returncode: 0
unskipped/79e230a2: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/skip_tests/unskipped/79e230a2/unskipped.out
unskipped/79e230a2: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/skip_tests/unskipped/79e230a2/unskipped.err
In this iteration we are going to run the following tests: [unskipped/79e230a2]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ unskipped/79 │ generic.loc… │ PASS │ N/A N/A N/A │ 0 │ 0.008253 │
│ e230a2 │ │ │ │ │ │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘
Passed Tests: 1/1 Percentage: 100.000%
Failed Tests: 0/1 Percentage: 0.000%
Adding 1 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_sk2_ezqh.log
Skipping a buildspec¶
Sometimes you may want to skip all test in a buildspec instead of updating every test with skip
property, this can be done by setting
skip at the top-level. This can be useful if you are running several test in a directory such as buildtest build -b dir1/
and you don’t
want to explicitly exclude file via -x
option every time, instead you can hardcode this into the buildspec. A typical use-case of skipping
test is when a test is broken and you don’t want to run it then its good idea to set skip: yes
on the buildspec and fix it later.
In this next example we set skip: yes
, buildtest will skip the buildspec and no test will be processed even if skip
is set in each test.
skip: yes
buildspecs:
skip_all_tests:
type: script
executor: generic.local.bash
description: "All test in this buildspec are skipped"
tags: [tutorials]
run: hostname
this_test_is_also_skipped:
type: script
skip: no
executor: generic.local.bash
description: "This test is also skipped even if skip is defined in test"
tags: [ tutorials ]
run: hostname
If you try building this buildspec, you will see buildtest will skip the buildspec and terminate.
buildtest build -b tutorials/skip_buildspec.yml
$ buildtest build -b tutorials/skip_buildspec.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:20 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/skip_buildspec.yml: skipping all test since 'skip' is defined
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/skip_buildspec.yml: VALID
Buildspecs Filtered out
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ buildspecs ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… │
└──────────────────────────────────────────────────────────────────────────────┘
buildtest is unable to create any tests because there are no valid buildspecs.
Please see logfile: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/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
.
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: '(\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
$ buildtest build -b tutorials/metrics_regex.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:20 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/metrics_regex.yml: VALID
Total builder objects created: 1
Total compiler builder: 0
Total script builder: 1
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ metric_re… │ generic.l… │ None │ None │ None │ capture │ /home/doc… │
│ │ │ │ │ │ result │ │
│ │ │ │ │ │ metric │ │
│ │ │ │ │ │ from │ │
│ │ │ │ │ │ output │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
metric_regex_example/f5142bd9: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/metrics_regex/metric_regex_example/f5142bd9
metric_regex_example/f5142bd9: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/metrics_regex/metric_regex_example/f5142bd9/stage
metric_regex_example/f5142bd9: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/metrics_regex/metric_regex_example/f5142bd9/metric_regex_example_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
metric_regex_example/f5142bd9 does not have any dependencies adding test to queue
metric_regex_example/f5142bd9: Running Test via command: sh --norc --noprofile -eo pipefail metric_regex_example_build.sh
metric_regex_example/f5142bd9: Test completed in 0.003252 seconds
metric_regex_example/f5142bd9: Test completed with returncode: 2
metric_regex_example/f5142bd9: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/metrics_regex/metric_regex_example/f5142bd9/metric_regex_example.out
metric_regex_example/f5142bd9: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/metrics_regex/metric_regex_example/f5142bd9/metric_regex_example.err
In this iteration we are going to run the following tests: [metric_regex_example/f5142bd9]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ metric_regex │ generic.loc… │ FAIL │ N/A N/A N/A │ 2 │ 0.003252 │
│ _example/f51 │ │ │ │ │ │
│ 42bd9 │ │ │ │ │ │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘
Passed Tests: 0/1 Percentage: 0.000%
Failed Tests: 1/1 Percentage: 100.000%
Adding 1 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_by81nbdl.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
$ buildtest report --filter buildspec=tutorials/metrics_regex.yml --format name,metrics
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ name ┃ metrics ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ metric_regex_example │ hpcg_rating=,hpcg_state= │
└────────────────────────────────────┴─────────────────────────────────────────┘
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
.
Test Dependency¶
Note
This feature is subject to change
Buildtest can support test dependencies which allows one to specify condition before running a test. Let’s take a look
at this next example, we have a buildspec with three tests jobA
, jobB
, and jobC
. The test jobA will run immediately
but now we introduce a new keyword needs
which is a list of test names as dependency. We want test jobB to run after jobA is
complete, and jobC to run once jobA and jobB is complete.
buildspecs:
jobA:
type: script
executor: generic.local.bash
description: no job dependency
run: |
echo "This job has no dependency"
sleep 5
jobB:
type: script
executor: generic.local.bash
description: job dependency on jobA
needs: [jobA]
run: |
echo "This job depends on jobA"
sleep 2
jobC:
type: script
executor: generic.local.bash
description: job dependency on jobA and jobB
needs: [jobA, jobB]
run: |
echo "This job depends on jobA and jobB"
sleep 2
The needs
property expects a list of strings, and values must match name of test. If you specify an invalid
test name in needs property then buildtest will ignore the value. If multiple tests are specified in needs property then
all test must finish prior to running test.
Let’s run this test, and take a note that buildtest will run test jobA, followed by jobB then jobC.
buildtest build -b tutorials/job_dependency/ex1.yml
$ buildtest build -b tutorials/job_dependency/ex1.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:21 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/job_dependency/ex1.yml: VALID
Total builder objects created: 3
Total compiler builder: 0
Total script builder: 3
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ jobA/7c36… │ generic.l… │ None │ None │ None │ no job │ /home/doc… │
│ │ │ │ │ │ dependency │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ jobB/0f43… │ generic.l… │ None │ None │ None │ job │ /home/doc… │
│ │ │ │ │ │ dependency │ │
│ │ │ │ │ │ on jobA │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ jobC/0d8c… │ generic.l… │ None │ None │ None │ job │ /home/doc… │
│ │ │ │ │ │ dependency │ │
│ │ │ │ │ │ on jobA │ │
│ │ │ │ │ │ and jobB │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
jobA/7c362693: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex1/jobA/7c362693
jobA/7c362693: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex1/jobA/7c362693/stage
jobA/7c362693: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex1/jobA/7c362693/jobA_build.sh
jobB/0f439911: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex1/jobB/0f439911
jobB/0f439911: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex1/jobB/0f439911/stage
jobB/0f439911: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex1/jobB/0f439911/jobB_build.sh
jobC/0d8c32d7: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex1/jobC/0d8c32d7
jobC/0d8c32d7: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex1/jobC/0d8c32d7/stage
jobC/0d8c32d7: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex1/jobC/0d8c32d7/jobC_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
jobA/7c362693 does not have any dependencies adding test to queue
jobC/0d8c32d7 Skipping job because it has job dependency on jobA/7c362693 which is in state PENDING
jobB/0f439911 Skipping job because it has job dependency on jobA/7c362693 which is in state PENDING
jobA/7c362693: Running Test via command: bash --norc --noprofile -eo pipefail jobA_build.sh
jobA/7c362693: Test completed in 5.007318 seconds
jobA/7c362693: Test completed with returncode: 0
jobA/7c362693: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex1/jobA/7c362693/jobA.out
jobA/7c362693: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex1/jobA/7c362693/jobA.err
In this iteration we are going to run the following tests: [jobA/7c362693]
───────────────────────────────── Iteration 2 ──────────────────────────────────
jobC/0d8c32d7 Skipping job because it has job dependency on jobB/0f439911 which is in state PENDING
jobB/0f439911: Running Test via command: bash --norc --noprofile -eo pipefail jobB_build.sh
jobB/0f439911: Test completed in 2.007041 seconds
jobB/0f439911: Test completed with returncode: 0
jobB/0f439911: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex1/jobB/0f439911/jobB.out
jobB/0f439911: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex1/jobB/0f439911/jobB.err
In this iteration we are going to run the following tests: [jobB/0f439911]
───────────────────────────────── Iteration 3 ──────────────────────────────────
jobC/0d8c32d7: Running Test via command: bash --norc --noprofile -eo pipefail jobC_build.sh
jobC/0d8c32d7: Test completed in 2.007041 seconds
jobC/0d8c32d7: Test completed with returncode: 0
jobC/0d8c32d7: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex1/jobC/0d8c32d7/jobC.out
jobC/0d8c32d7: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex1/jobC/0d8c32d7/jobC.err
In this iteration we are going to run the following tests: [jobC/0d8c32d7]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ jobA/7c36269 │ generic.loca… │ PASS │ N/A N/A N/A │ 0 │ 5.007318 │
│ 3 │ │ │ │ │ │
├──────────────┼───────────────┼────────┼──────────────┼────────────┼──────────┤
│ jobB/0f43991 │ generic.loca… │ PASS │ N/A N/A N/A │ 0 │ 2.007041 │
│ 1 │ │ │ │ │ │
├──────────────┼───────────────┼────────┼──────────────┼────────────┼──────────┤
│ jobC/0d8c32d │ generic.loca… │ PASS │ N/A N/A N/A │ 0 │ 2.007041 │
│ 7 │ │ │ │ │ │
└──────────────┴───────────────┴────────┴──────────────┴────────────┴──────────┘
Passed Tests: 3/3 Percentage: 100.000%
Failed Tests: 0/3 Percentage: 0.000%
Adding 3 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_ay9_nw2j.log
Test Dependency by returncode¶
In this next example, we can control behavior of job dependency based on returncode for a given test. This test has three
tests: test1
, test2
and test3
. The first test will exit with returncode 1 but this test will pass because we have
set state: PASS
to override the status check. The next test test2
requires test1 to have a returncode of 1 in order
to satisfy dependency. The returncode
property expects a valid returncode and it can be a list of returncode similar to
how one specify returncode
under the status property see Return Code Matching. The needs
property can support multiple
test with returncode, in test3
we require test1
to have returncode 1 while test2
has a returncode of 2. We expect test2
to return a returncode of 2 because of exit 2
statement so we expect all three tests to run.
buildspecs:
test1:
type: script
executor: generic.local.bash
description: This test will pass with exit 1
run: exit 1
status:
state: PASS
test2:
type: script
executor: generic.local.bash
description: This test will run if test1 has returncode 1
run: exit 2
status:
state: PASS
needs:
- test1:
returncode: 1
test3:
type: script
executor: generic.local.bash
description: This test will run if test1 has returncode 1 and test2 has returncode 2
run: exit 1
status:
state: PASS
needs:
- test1:
returncode: 1
- test2:
returncode: 2
Let’s build this test and take note of execution order of test.
buildtest build -b tutorials/job_dependency/ex2.yml
$ buildtest build -b tutorials/job_dependency/ex2.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:31 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/job_dependency/ex2.yml: VALID
Total builder objects created: 3
Total compiler builder: 0
Total script builder: 3
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ test1/319… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ will pass │ │
│ │ │ │ │ │ with exit │ │
│ │ │ │ │ │ 1 │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ test2/d30… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ will run │ │
│ │ │ │ │ │ if test1 │ │
│ │ │ │ │ │ has │ │
│ │ │ │ │ │ returncode │ │
│ │ │ │ │ │ 1 │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ test3/367… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ will run │ │
│ │ │ │ │ │ if test1 │ │
│ │ │ │ │ │ has │ │
│ │ │ │ │ │ returncode │ │
│ │ │ │ │ │ 1 and │ │
│ │ │ │ │ │ test2 has │ │
│ │ │ │ │ │ returncode │ │
│ │ │ │ │ │ 2 │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
test1/319d8dae: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex2/test1/319d8dae
test1/319d8dae: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex2/test1/319d8dae/stage
test1/319d8dae: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex2/test1/319d8dae/test1_build.sh
test2/d30a0d11: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex2/test2/d30a0d11
test2/d30a0d11: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex2/test2/d30a0d11/stage
test2/d30a0d11: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex2/test2/d30a0d11/test2_build.sh
test3/367b38f4: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex2/test3/367b38f4
test3/367b38f4: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex2/test3/367b38f4/stage
test3/367b38f4: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex2/test3/367b38f4/test3_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
test1/319d8dae does not have any dependencies adding test to queue
test2/d30a0d11 Skipping job because it has job dependency on test1/319d8dae
test3/367b38f4 Skipping job because it has job dependency on test1/319d8dae
test1/319d8dae: Running Test via command: bash --norc --noprofile -eo pipefail test1_build.sh
test1/319d8dae: Test completed in 0.005713 seconds
test1/319d8dae: Test completed with returncode: 1
test1/319d8dae: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex2/test1/319d8dae/test1.out
test1/319d8dae: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex2/test1/319d8dae/test1.err
In this iteration we are going to run the following tests: [test1/319d8dae]
───────────────────────────────── Iteration 2 ──────────────────────────────────
test3/367b38f4 Skipping job because it has job dependency on test2/d30a0d11
test2/d30a0d11: Running Test via command: bash --norc --noprofile -eo pipefail test2_build.sh
test2/d30a0d11: Test completed in 0.005417 seconds
test2/d30a0d11: Test completed with returncode: 2
test2/d30a0d11: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex2/test2/d30a0d11/test2.out
test2/d30a0d11: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex2/test2/d30a0d11/test2.err
In this iteration we are going to run the following tests: [test2/d30a0d11]
───────────────────────────────── Iteration 3 ──────────────────────────────────
test3/367b38f4: Running Test via command: bash --norc --noprofile -eo pipefail test3_build.sh
test3/367b38f4: Test completed in 0.005238 seconds
test3/367b38f4: Test completed with returncode: 1
test3/367b38f4: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex2/test3/367b38f4/test3.out
test3/367b38f4: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex2/test3/367b38f4/test3.err
In this iteration we are going to run the following tests: [test3/367b38f4]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ test1/319d8d │ generic.loc… │ PASS │ False False │ 1 │ 0.005713 │
│ ae │ │ │ False │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ test3/367b38 │ generic.loc… │ PASS │ False False │ 1 │ 0.005238 │
│ f4 │ │ │ False │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ test2/d30a0d │ generic.loc… │ PASS │ False False │ 2 │ 0.005417 │
│ 11 │ │ │ False │ │ │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘
Passed Tests: 3/3 Percentage: 100.000%
Failed Tests: 0/3 Percentage: 0.000%
Adding 3 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_95c51v0i.log
Test Dependency by state¶
You can specify state
as a property to check for test state when specify test dependency. In this next example, we have
have four tests pass_test, fail_test, pass_and_fail_test, and final_test. The first test will be a PASS because
we have state: PASS
. The test fail_test
depends on pass_test only if it has state: PASS
, if value is mismatch then test
will be skipped. Note that buildtest will skip test until next iteration if test is not executed, however if test is complete then buildtest
will cancel dependent test. We can specify multiple test dependencies with state property such as test pass_and_fail_test which expects
pass_test
to have state: PASS and fail_test
to have state: FAIL. In test final_test
, shows how you can combine the format, the
needs
property is a list of object where each element is name of test. If no properties are associated with test name then buildtest will
wait until job is complete to execute test. In this example, the test expects both pass_test
and fail_test
to run while pass_and_fail_test
must have returncode of 1.
buildspecs:
pass_test:
type: script
executor: generic.local.bash
description: This test will always pass
status:
state: PASS
run: |
echo "This test will pass"
sleep 2
fail_test:
type: script
executor: generic.local.bash
description: This test will run if test 'pass_test' is in state 'PASS'
status:
state: FAIL
needs:
- pass_test:
state: PASS
run: |
echo "This test will fail"
sleep 2
pass_and_fail_test:
type: script
executor: generic.local.bash
description: This test will run if pass_test is 'PASS' and fail_test is 'FAIL'
needs:
- pass_test:
state: PASS
- fail_test:
state: FAIL
run: |
sleep 2
exit 1
status:
returncode: 1
final_test:
type: script
executor: generic.local.bash
description: Test will run after 'pass_test', 'fail_test', and 'pass_and_fail_test'
needs:
- pass_test
- fail_test
- pass_and_fail_test:
returncode: 1
run: |
sleep 2
echo "Hello world"
Let’s build this test and take note all tests are run.
buildtest build -b tutorials/job_dependency/ex3.yml
$ buildtest build -b tutorials/job_dependency/ex3.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:32 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/job_dependency/ex3.yml: VALID
Total builder objects created: 4
Total compiler builder: 0
Total script builder: 4
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ pass_test… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ will │ │
│ │ │ │ │ │ always │ │
│ │ │ │ │ │ pass │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ fail_test… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ will run │ │
│ │ │ │ │ │ if test │ │
│ │ │ │ │ │ 'pass_tes… │ │
│ │ │ │ │ │ is in │ │
│ │ │ │ │ │ state │ │
│ │ │ │ │ │ 'PASS' │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ pass_and_… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ will run │ │
│ │ │ │ │ │ if │ │
│ │ │ │ │ │ pass_test │ │
│ │ │ │ │ │ is 'PASS' │ │
│ │ │ │ │ │ and │ │
│ │ │ │ │ │ fail_test │ │
│ │ │ │ │ │ is 'FAIL' │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ final_tes… │ generic.l… │ None │ None │ None │ Test will │ /home/doc… │
│ │ │ │ │ │ run after │ │
│ │ │ │ │ │ 'pass_tes… │ │
│ │ │ │ │ │ 'fail_tes… │ │
│ │ │ │ │ │ and │ │
│ │ │ │ │ │ 'pass_and… │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
pass_test/ef4bde32: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/pass_test/ef4bde32
pass_test/ef4bde32: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/pass_test/ef4bde32/stage
pass_test/ef4bde32: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/pass_test/ef4bde32/pass_test_build.sh
fail_test/b7b657b4: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/fail_test/b7b657b4
fail_test/b7b657b4: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/fail_test/b7b657b4/stage
fail_test/b7b657b4: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/fail_test/b7b657b4/fail_test_build.sh
pass_and_fail_test/39072976: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/pass_and_fail_test/39072976
pass_and_fail_test/39072976: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/pass_and_fail_test/39072976/stage
pass_and_fail_test/39072976: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/pass_and_fail_test/39072976/pass_and_fail_test_build.sh
final_test/943745e8: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/final_test/943745e8
final_test/943745e8: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/final_test/943745e8/stage
final_test/943745e8: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/final_test/943745e8/final_test_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
pass_test/ef4bde32 does not have any dependencies adding test to queue
final_test/943745e8 Skipping job because it has job dependency on pass_test/ef4bde32 which is in state PENDING
pass_and_fail_test/39072976 Skipping job because it has job dependency on pass_test/ef4bde32
fail_test/b7b657b4 Skipping job because it has job dependency on pass_test/ef4bde32
pass_test/ef4bde32: Running Test via command: bash --norc --noprofile -eo pipefail pass_test_build.sh
pass_test/ef4bde32: Test completed in 2.006947 seconds
pass_test/ef4bde32: Test completed with returncode: 0
pass_test/ef4bde32: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/pass_test/ef4bde32/pass_test.out
pass_test/ef4bde32: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/pass_test/ef4bde32/pass_test.err
In this iteration we are going to run the following tests: [pass_test/ef4bde32]
───────────────────────────────── Iteration 2 ──────────────────────────────────
final_test/943745e8 Skipping job because it has job dependency on fail_test/b7b657b4 which is in state PENDING
pass_and_fail_test/39072976 Skipping job because it has job dependency on fail_test/b7b657b4
fail_test/b7b657b4: Running Test via command: bash --norc --noprofile -eo pipefail fail_test_build.sh
fail_test/b7b657b4: Test completed in 2.007556 seconds
fail_test/b7b657b4: Test completed with returncode: 0
fail_test/b7b657b4: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/fail_test/b7b657b4/fail_test.out
fail_test/b7b657b4: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/fail_test/b7b657b4/fail_test.err
In this iteration we are going to run the following tests: [fail_test/b7b657b4]
───────────────────────────────── Iteration 3 ──────────────────────────────────
final_test/943745e8 Skipping job because it has job dependency on pass_and_fail_test/39072976
pass_and_fail_test/39072976: Running Test via command: bash --norc --noprofile -eo pipefail pass_and_fail_test_build.sh
pass_and_fail_test/39072976: Test completed in 2.007194 seconds
pass_and_fail_test/39072976: Test completed with returncode: 1
pass_and_fail_test/39072976: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/pass_and_fail_test/39072976/pass_and_fail_test.out
pass_and_fail_test/39072976: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/pass_and_fail_test/39072976/pass_and_fail_test.err
pass_and_fail_test/39072976: Checking returncode - 1 is matched in list [1]
In this iteration we are going to run the following tests: [pass_and_fail_test/39072976]
───────────────────────────────── Iteration 4 ──────────────────────────────────
final_test/943745e8: Running Test via command: bash --norc --noprofile -eo pipefail final_test_build.sh
final_test/943745e8: Test completed in 2.007039 seconds
final_test/943745e8: Test completed with returncode: 0
final_test/943745e8: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/final_test/943745e8/final_test.out
final_test/943745e8: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex3/final_test/943745e8/final_test.err
In this iteration we are going to run the following tests: [final_test/943745e8]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ pass_and_fai │ generic.loc… │ PASS │ True False │ 1 │ 2.007194 │
│ l_test/39072 │ │ │ False │ │ │
│ 976 │ │ │ │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ fail_test/b7 │ generic.loc… │ FAIL │ False False │ 0 │ 2.007556 │
│ b657b4 │ │ │ False │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ pass_test/ef │ generic.loc… │ PASS │ False False │ 0 │ 2.006947 │
│ 4bde32 │ │ │ False │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ final_test/9 │ generic.loc… │ PASS │ N/A N/A N/A │ 0 │ 2.007039 │
│ 43745e8 │ │ │ │ │ │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘
Passed Tests: 3/4 Percentage: 75.000%
Failed Tests: 1/4 Percentage: 25.000%
Adding 4 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_6c8vq0dw.log
In this next example, we have three tests the first test will runtime_test
will sleep for 5 seconds but it will fail due to runtime
requirement of 2sec. The next two tests runtime_test_pass
and runtime_test_fail
both depend on runtime_test
however due to condition
only one of them can be run because runtime_test_pass
expects runtime_test to have state: PASS while runtime_test_fail
expects runtime_test
to have state: FAIL. This type of workflow can be used if you want to run a set of test based on one condition while running a different set of
test based on the negative condition.
buildspecs:
runtime_test:
type: script
executor: generic.local.bash
description: This test will sleep 5 second but will fail due to runtime 2sec
status:
runtime:
min: 2.0
run: sleep 5
runtime_test_pass:
type: script
executor: generic.local.bash
description: This test will run when runtime_test_pass is PASS
needs:
- runtime_test:
state: PASS
run: echo "Performing some action when test PASS"
runtime_test_fail:
type: script
executor: generic.local.bash
description: This test will run when runtime_test_pass is FAIL
needs:
- runtime_test:
state: FAIL
run: echo "Performing some action when test FAIL"
Let’s build this test and take note that we only run two tests and runtime_test_fail was skipped because test runtime_test has a
state: PASS
.
buildtest build -b tutorials/job_dependency/ex4.yml
$ buildtest build -b tutorials/job_dependency/ex4.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:40 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/job_dependency/ex4.yml: VALID
Total builder objects created: 3
Total compiler builder: 0
Total script builder: 3
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ runtime_t… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ will sleep │ │
│ │ │ │ │ │ 5 second │ │
│ │ │ │ │ │ but will │ │
│ │ │ │ │ │ fail due │ │
│ │ │ │ │ │ to runtime │ │
│ │ │ │ │ │ 2sec │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ runtime_t… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ will run │ │
│ │ │ │ │ │ when │ │
│ │ │ │ │ │ runtime_t… │ │
│ │ │ │ │ │ is PASS │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ runtime_t… │ generic.l… │ None │ None │ None │ This test │ /home/doc… │
│ │ │ │ │ │ will run │ │
│ │ │ │ │ │ when │ │
│ │ │ │ │ │ runtime_t… │ │
│ │ │ │ │ │ is FAIL │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
runtime_test/f198c325: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex4/runtime_test/f198c325
runtime_test/f198c325: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex4/runtime_test/f198c325/stage
runtime_test/f198c325: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex4/runtime_test/f198c325/runtime_test_build.sh
runtime_test_pass/ba916363: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex4/runtime_test_pass/ba916363
runtime_test_pass/ba916363: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex4/runtime_test_pass/ba916363/stage
runtime_test_pass/ba916363: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex4/runtime_test_pass/ba916363/runtime_test_pass_build.sh
runtime_test_fail/63ebd845: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex4/runtime_test_fail/63ebd845
runtime_test_fail/63ebd845: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex4/runtime_test_fail/63ebd845/stage
runtime_test_fail/63ebd845: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex4/runtime_test_fail/63ebd845/runtime_test_fail_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
runtime_test_pass/ba916363 Skipping job because it has job dependency on runtime_test/f198c325
runtime_test_fail/63ebd845 Skipping job because it has job dependency on runtime_test/f198c325
runtime_test/f198c325 does not have any dependencies adding test to queue
runtime_test/f198c325: Running Test via command: bash --norc --noprofile -eo pipefail runtime_test_build.sh
runtime_test/f198c325: Test completed in 5.006893 seconds
runtime_test/f198c325: Test completed with returncode: 0
runtime_test/f198c325: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex4/runtime_test/f198c325/runtime_test.out
runtime_test/f198c325: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex4/runtime_test/f198c325/runtime_test.err
In this iteration we are going to run the following tests: [runtime_test/f198c325]
───────────────────────────────── Iteration 2 ──────────────────────────────────
runtime_test_fail/63ebd845 is cancelled because it depends on runtime_test/f198c325 to have state: FAIL but actual value is PASS
runtime_test_pass/ba916363: Running Test via command: bash --norc --noprofile -eo pipefail runtime_test_pass_build.sh
runtime_test_pass/ba916363: Test completed in 0.005654 seconds
runtime_test_pass/ba916363: Test completed with returncode: 0
runtime_test_pass/ba916363: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex4/runtime_test_pass/ba916363/runtime_test_pass.out
runtime_test_pass/ba916363: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/ex4/runtime_test_pass/ba916363/runtime_test_pass.err
In this iteration we are going to run the following tests: [runtime_test_pass/ba916363]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ runtime_test │ generic.loc… │ PASS │ False False │ 0 │ 5.006893 │
│ /f198c325 │ │ │ True │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ runtime_test │ generic.loc… │ PASS │ N/A N/A N/A │ 0 │ 0.005654 │
│ _pass/ba9163 │ │ │ │ │ │
│ 63 │ │ │ │ │ │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘
Passed Tests: 2/2 Percentage: 100.000%
Failed Tests: 0/2 Percentage: 0.000%
Adding 2 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_jmhyrji3.log
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.
buildspecs:
multiple_executors:
type: script
executor: 'generic.local.(bash|sh)'
description: run test with executor generic.local.bash and generic.local.sh executor
tags: [tutorials]
run: date
If we build this test, notice that there are two tests, one for each executor.
buildtest build -b tutorials/multi_executors/executor_regex_script.yml
$ buildtest build -b tutorials/multi_executors/executor_regex_script.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:46 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/multi_executors/executor_regex_script.yml: VALID
Total builder objects created: 2
Total compiler builder: 0
Total script builder: 2
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ multiple_… │ generic.l… │ None │ None │ None │ run test │ /home/doc… │
│ │ │ │ │ │ with │ │
│ │ │ │ │ │ executor │ │
│ │ │ │ │ │ generic.l… │ │
│ │ │ │ │ │ and │ │
│ │ │ │ │ │ generic.l… │ │
│ │ │ │ │ │ executor │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ multiple_… │ generic.l… │ None │ None │ None │ run test │ /home/doc… │
│ │ │ │ │ │ with │ │
│ │ │ │ │ │ executor │ │
│ │ │ │ │ │ generic.l… │ │
│ │ │ │ │ │ and │ │
│ │ │ │ │ │ generic.l… │ │
│ │ │ │ │ │ executor │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
multiple_executors/ff612070: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executor_regex_script/multiple_executors/ff612070
multiple_executors/ff612070: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executor_regex_script/multiple_executors/ff612070/stage
multiple_executors/ff612070: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executor_regex_script/multiple_executors/ff612070/multiple_executors_build.sh
multiple_executors/86cef1fd: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executor_regex_script/multiple_executors/86cef1fd
multiple_executors/86cef1fd: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executor_regex_script/multiple_executors/86cef1fd/stage
multiple_executors/86cef1fd: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executor_regex_script/multiple_executors/86cef1fd/multiple_executors_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
multiple_executors/86cef1fd does not have any dependencies adding test to queue
multiple_executors/ff612070 does not have any dependencies adding test to queue
multiple_executors/86cef1fd: Running Test via command: sh --norc --noprofile -eo pipefail multiple_executors_build.sh
multiple_executors/86cef1fd: Test completed in 0.003194 seconds
multiple_executors/86cef1fd: Test completed with returncode: 2
multiple_executors/86cef1fd: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executor_regex_script/multiple_executors/86cef1fd/multiple_executors.out
multiple_executors/86cef1fd: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executor_regex_script/multiple_executors/86cef1fd/multiple_executors.err
multiple_executors/ff612070: Running Test via command: bash --norc --noprofile -eo pipefail multiple_executors_build.sh
multiple_executors/ff612070: Test completed in 0.007629 seconds
multiple_executors/ff612070: Test completed with returncode: 0
multiple_executors/ff612070: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executor_regex_script/multiple_executors/ff612070/multiple_executors.out
multiple_executors/ff612070: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executor_regex_script/multiple_executors/ff612070/multiple_executors.err
In this iteration we are going to run the following tests: [multiple_executors/86cef1fd, multiple_executors/ff612070]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ multiple_exe │ generic.loc… │ FAIL │ N/A N/A N/A │ 2 │ 0.003194 │
│ cutors/86cef │ │ │ │ │ │
│ 1fd │ │ │ │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ multiple_exe │ generic.loc… │ PASS │ N/A N/A N/A │ 0 │ 0.007629 │
│ cutors/ff612 │ │ │ │ │ │
│ 070 │ │ │ │ │ │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘
Passed Tests: 1/2 Percentage: 50.000%
Failed Tests: 1/2 Percentage: 50.000%
Adding 2 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_qio810q0.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.
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/multi_executors/executors_var_env_declaration.yml
$ buildtest build -b tutorials/multi_executors/executors_var_env_declaration.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:46 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/multi_executors/executors_var_env_declaration.yml: VALID
Total builder objects created: 2
Total compiler builder: 0
Total script builder: 2
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ executors… │ generic.l… │ None │ None │ None │ Declaring │ /home/doc… │
│ │ │ │ │ │ env and │ │
│ │ │ │ │ │ vars by │ │
│ │ │ │ │ │ executors │ │
│ │ │ │ │ │ section │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ executors… │ generic.l… │ None │ None │ None │ Declaring │ /home/doc… │
│ │ │ │ │ │ env and │ │
│ │ │ │ │ │ vars by │ │
│ │ │ │ │ │ executors │ │
│ │ │ │ │ │ section │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
executors_vars_env_declaration/372b48ee: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executors_var_env_declaration/executors_vars_env_declaration/372b48ee
executors_vars_env_declaration/372b48ee: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executors_var_env_declaration/executors_vars_env_declaration/372b48ee/stage
executors_vars_env_declaration/372b48ee: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executors_var_env_declaration/executors_vars_env_declaration/372b48ee/executors_vars_env_declaration_build.sh
executors_vars_env_declaration/b2ddd01d: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executors_var_env_declaration/executors_vars_env_declaration/b2ddd01d
executors_vars_env_declaration/b2ddd01d: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executors_var_env_declaration/executors_vars_env_declaration/b2ddd01d/stage
executors_vars_env_declaration/b2ddd01d: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executors_var_env_declaration/executors_vars_env_declaration/b2ddd01d/executors_vars_env_declaration_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
executors_vars_env_declaration/372b48ee does not have any dependencies adding test to queue
executors_vars_env_declaration/b2ddd01d does not have any dependencies adding test to queue
executors_vars_env_declaration/372b48ee: Running Test via command: bash --norc --noprofile -eo pipefail executors_vars_env_declaration_build.sh
executors_vars_env_declaration/372b48ee: Test completed in 0.005725 seconds
executors_vars_env_declaration/372b48ee: Test completed with returncode: 0
executors_vars_env_declaration/372b48ee: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executors_var_env_declaration/executors_vars_env_declaration/372b48ee/executors_vars_env_declaration.out
executors_vars_env_declaration/372b48ee: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executors_var_env_declaration/executors_vars_env_declaration/372b48ee/executors_vars_env_declaration.err
executors_vars_env_declaration/b2ddd01d: Running Test via command: sh --norc --noprofile -eo pipefail executors_vars_env_declaration_build.sh
executors_vars_env_declaration/b2ddd01d: Test completed in 0.003173 seconds
executors_vars_env_declaration/b2ddd01d: Test completed with returncode: 2
executors_vars_env_declaration/b2ddd01d: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executors_var_env_declaration/executors_vars_env_declaration/b2ddd01d/executors_vars_env_declaration.out
executors_vars_env_declaration/b2ddd01d: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executors_var_env_declaration/executors_vars_env_declaration/b2ddd01d/executors_vars_env_declaration.err
In this iteration we are going to run the following tests: [executors_vars_env_declaration/372b48ee, executors_vars_env_declaration/b2ddd01d]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ executors_va │ generic.loc… │ FAIL │ N/A N/A N/A │ 2 │ 0.003173 │
│ rs_env_decla │ │ │ │ │ │
│ ration/b2ddd │ │ │ │ │ │
│ 01d │ │ │ │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ executors_va │ generic.loc… │ PASS │ N/A N/A N/A │ 0 │ 0.005725 │
│ rs_env_decla │ │ │ │ │ │
│ ration/372b4 │ │ │ │ │ │
│ 8ee │ │ │ │ │ │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘
Passed Tests: 1/2 Percentage: 50.000%
Failed Tests: 1/2 Percentage: 50.000%
Adding 2 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest__6qonodm.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 -t executors_vars_env_declaration/
$ buildtest inspect query -t executors_vars_env_declaration/
───── executors_vars_env_declaration/372b48ee-0ca8-4534-ac07-5b2ee10697b7 ──────
Executor: generic.local.bash
Description: Declaring env and vars by executors section
State: PASS
Returncode: 0
Runtime: 0.005725 sec
Starttime: 2022/10/14 14:50:46
Endtime: 2022/10/14 14:50:46
Command: bash --norc --noprofile -eo pipefail executors_vars_env_declaration_build.sh
Test Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executors_var_env_declaration/executors_vars_env_declaration/372b48ee/executors_vars_env_declaration.sh
Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executors_var_env_declaration/executors_vars_env_declaration/372b48ee/executors_vars_env_declaration_build.sh
Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executors_var_env_declaration/executors_vars_env_declaration/372b48ee/executors_vars_env_declaration.out
Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executors_var_env_declaration/executors_vars_env_declaration/372b48ee/executors_vars_env_declaration.err
Log File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest__6qonodm.log
─ Test File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/check… ─
#!/usr/bin/bash
export SHELL="bash"
X="1"
Y="3"
# Content of run section
echo "X:" $X
echo "Y:" $Y
echo $SHELL
───── executors_vars_env_declaration/b2ddd01d-62b9-4a33-8c9a-e54fb36686b1 ──────
Executor: generic.local.sh
Description: Declaring env and vars by executors section
State: FAIL
Returncode: 2
Runtime: 0.003173 sec
Starttime: 2022/10/14 14:50:47
Endtime: 2022/10/14 14:50:47
Command: sh --norc --noprofile -eo pipefail executors_vars_env_declaration_build.sh
Test Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executors_var_env_declaration/executors_vars_env_declaration/b2ddd01d/executors_vars_env_declaration.sh
Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executors_var_env_declaration/executors_vars_env_declaration/b2ddd01d/executors_vars_env_declaration_build.sh
Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executors_var_env_declaration/executors_vars_env_declaration/b2ddd01d/executors_vars_env_declaration.out
Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executors_var_env_declaration/executors_vars_env_declaration/b2ddd01d/executors_vars_env_declaration.err
Log File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest__6qonodm.log
─ Test File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/check… ─
#!/usr/bin/sh
export SHELL="sh"
X="2"
Y="4"
# Content of run section
echo "X:" $X
echo "Y:" $Y
echo $SHELL
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.
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/multi_executors/executor_scheduler.yml
$ buildtest build -b tutorials/multi_executors/executor_scheduler.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:48 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/multi_executors/executor_scheduler.yml: VALID
Total builder objects created: 2
Total compiler builder: 0
Total script builder: 2
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ executors… │ generic.l… │ None │ None │ None │ Declaring │ /home/doc… │
│ │ │ │ │ │ env and │ │
│ │ │ │ │ │ vars by │ │
│ │ │ │ │ │ executors │ │
│ │ │ │ │ │ section │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ executors… │ generic.l… │ None │ None │ None │ Declaring │ /home/doc… │
│ │ │ │ │ │ env and │ │
│ │ │ │ │ │ vars by │ │
│ │ │ │ │ │ executors │ │
│ │ │ │ │ │ section │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
executors_sbatch_declaration/5b42e5e7: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declaration/5b42e5e7
executors_sbatch_declaration/5b42e5e7: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declaration/5b42e5e7/stage
executors_sbatch_declaration/5b42e5e7: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declaration/5b42e5e7/executors_sbatch_declaration_build.sh
executors_sbatch_declaration/97def6d0: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaration/97def6d0
executors_sbatch_declaration/97def6d0: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaration/97def6d0/stage
executors_sbatch_declaration/97def6d0: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaration/97def6d0/executors_sbatch_declaration_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
executors_sbatch_declaration/5b42e5e7 does not have any dependencies adding test to queue
executors_sbatch_declaration/97def6d0 does not have any dependencies adding test to queue
executors_sbatch_declaration/5b42e5e7: Running Test via command: bash --norc --noprofile -eo pipefail executors_sbatch_declaration_build.sh
executors_sbatch_declaration/5b42e5e7: Test completed in 0.006305 seconds
executors_sbatch_declaration/5b42e5e7: Test completed with returncode: 0
executors_sbatch_declaration/5b42e5e7: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declaration/5b42e5e7/executors_sbatch_declaration.out
executors_sbatch_declaration/5b42e5e7: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declaration/5b42e5e7/executors_sbatch_declaration.err
executors_sbatch_declaration/97def6d0: Running Test via command: sh --norc --noprofile -eo pipefail executors_sbatch_declaration_build.sh
executors_sbatch_declaration/97def6d0: Test completed in 0.002978 seconds
executors_sbatch_declaration/97def6d0: Test completed with returncode: 2
executors_sbatch_declaration/97def6d0: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaration/97def6d0/executors_sbatch_declaration.out
executors_sbatch_declaration/97def6d0: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaration/97def6d0/executors_sbatch_declaration.err
In this iteration we are going to run the following tests: [executors_sbatch_declaration/5b42e5e7, executors_sbatch_declaration/97def6d0]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ executors_sb │ generic.loc… │ FAIL │ N/A N/A N/A │ 2 │ 0.002978 │
│ atch_declara │ │ │ │ │ │
│ tion/97def6d │ │ │ │ │ │
│ 0 │ │ │ │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ executors_sb │ generic.loc… │ PASS │ N/A N/A N/A │ 0 │ 0.006305 │
│ atch_declara │ │ │ │ │ │
│ tion/5b42e5e │ │ │ │ │ │
│ 7 │ │ │ │ │ │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘
Passed Tests: 1/2 Percentage: 50.000%
Failed Tests: 1/2 Percentage: 50.000%
Adding 2 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_wbr9ho19.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 -t executors_sbatch_declaration/
$ buildtest inspect query -t executors_sbatch_declaration/
────── executors_sbatch_declaration/97def6d0-79ac-472b-adef-55e0c15eca45 ───────
Executor: generic.local.sh
Description: Declaring env and vars by executors section
State: FAIL
Returncode: 2
Runtime: 0.002978 sec
Starttime: 2022/10/14 14:50:48
Endtime: 2022/10/14 14:50:48
Command: sh --norc --noprofile -eo pipefail executors_sbatch_declaration_build.sh
Test Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaration/97def6d0/executors_sbatch_declaration.sh
Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaration/97def6d0/executors_sbatch_declaration_build.sh
Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaration/97def6d0/executors_sbatch_declaration.out
Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaration/97def6d0/executors_sbatch_declaration.err
Log File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_wbr9ho19.log
─ Test File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/check… ─
#!/usr/bin/sh
#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
# Content of run section
hostname
────── executors_sbatch_declaration/5b42e5e7-c8b6-4d2d-a6d8-57dec12c8867 ───────
Executor: generic.local.bash
Description: Declaring env and vars by executors section
State: PASS
Returncode: 0
Runtime: 0.006305 sec
Starttime: 2022/10/14 14:50:48
Endtime: 2022/10/14 14:50:48
Command: bash --norc --noprofile -eo pipefail executors_sbatch_declaration_build.sh
Test Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declaration/5b42e5e7/executors_sbatch_declaration.sh
Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declaration/5b42e5e7/executors_sbatch_declaration_build.sh
Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declaration/5b42e5e7/executors_sbatch_declaration.out
Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declaration/5b42e5e7/executors_sbatch_declaration.err
Log File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_wbr9ho19.log
─ Test File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/check… ─
#!/usr/bin/bash
#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
# Content of run section
hostname
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.
buildspecs:
create_burst_buffer_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
Custom Status by Executor¶
The status and metrics field are supported in executors
which can be defined within the named executor. In this next example, we will define executor generic.local.bash
to
match for returncode 0 or 2 while second test will use executor generic.local.sh
to match returncode of 1.
buildspecs:
status_returncode_by_executors:
type: script
executor: "generic.local.(bash|sh)"
description: define status per executor type.
tags: [tutorials]
run: exit 0
executors:
generic.local.bash:
status:
returncode: [0, 2]
generic.local.sh:
status:
returncode: 1
Now let’s run this test and we will see the test using executor 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/multi_executors/status_by_executors.yml
$ buildtest build -b tutorials/multi_executors/status_by_executors.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-18342644-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2022/10/14 14:50:49 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 1.0 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.7.13 │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/t… ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Buildtest will parse 1 buildspecs
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/tutorials/multi_executors/status_by_executors.yml: VALID
Total builder objects created: 2
Total compiler builder: 0
Total script builder: 2
Total spack builder: 0
Script Builder Details
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ builder ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ descripti… ┃ buildspecs ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ status_re… │ generic.l… │ None │ None │ None │ define │ /home/doc… │
│ │ │ │ │ │ status per │ │
│ │ │ │ │ │ executor │ │
│ │ │ │ │ │ type. │ │
├────────────┼────────────┼──────────┼───────┼───────┼────────────┼────────────┤
│ status_re… │ generic.l… │ None │ None │ None │ define │ /home/doc… │
│ │ │ │ │ │ status per │ │
│ │ │ │ │ │ executor │ │
│ │ │ │ │ │ type. │ │
└────────────┴────────────┴──────────┴───────┴───────┴────────────┴────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
status_returncode_by_executors/6678c702: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_by_executors/status_returncode_by_executors/6678c702
status_returncode_by_executors/6678c702: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_by_executors/status_returncode_by_executors/6678c702/stage
status_returncode_by_executors/6678c702: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_by_executors/status_returncode_by_executors/6678c702/status_returncode_by_executors_build.sh
status_returncode_by_executors/848e23b8: Creating test directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/status_by_executors/status_returncode_by_executors/848e23b8
status_returncode_by_executors/848e23b8: Creating the stage directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/status_by_executors/status_returncode_by_executors/848e23b8/stage
status_returncode_by_executors/848e23b8: Writing build script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/status_by_executors/status_returncode_by_executors/848e23b8/status_returncode_by_executors_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
status_returncode_by_executors/6678c702 does not have any dependencies adding test to queue
status_returncode_by_executors/848e23b8 does not have any dependencies adding test to queue
status_returncode_by_executors/6678c702: Running Test via command: bash --norc --noprofile -eo pipefail status_returncode_by_executors_build.sh
status_returncode_by_executors/6678c702: Test completed in 0.005612 seconds
status_returncode_by_executors/6678c702: Test completed with returncode: 0
status_returncode_by_executors/6678c702: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_by_executors/status_returncode_by_executors/6678c702/status_returncode_by_executors.out
status_returncode_by_executors/6678c702: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.bash/status_by_executors/status_returncode_by_executors/6678c702/status_returncode_by_executors.err
status_returncode_by_executors/6678c702: Checking returncode - 0 is matched in list [0, 2]
status_returncode_by_executors/848e23b8: Running Test via command: sh --norc --noprofile -eo pipefail status_returncode_by_executors_build.sh
status_returncode_by_executors/848e23b8: Test completed in 0.002977 seconds
status_returncode_by_executors/848e23b8: Test completed with returncode: 2
status_returncode_by_executors/848e23b8: Writing output file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/status_by_executors/status_returncode_by_executors/848e23b8/status_returncode_by_executors.out
status_returncode_by_executors/848e23b8: Writing error file - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/tests/generic.local.sh/status_by_executors/status_returncode_by_executors/848e23b8/status_returncode_by_executors.err
status_returncode_by_executors/848e23b8: Checking returncode - 2 is matched in list [1]
In this iteration we are going to run the following tests: [status_returncode_by_executors/6678c702, status_returncode_by_executors/848e23b8]
Test Summary
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ checks ┃ ┃ ┃
┃ ┃ ┃ ┃ (ReturnCode, ┃ ┃ ┃
┃ ┃ ┃ ┃ Regex, ┃ ┃ ┃
┃ builder ┃ executor ┃ status ┃ Runtime) ┃ returnCode ┃ runtime ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ status_retur │ generic.loc… │ PASS │ True False │ 0 │ 0.005612 │
│ ncode_by_exe │ │ │ False │ │ │
│ cutors/6678c │ │ │ │ │ │
│ 702 │ │ │ │ │ │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ status_retur │ generic.loc… │ FAIL │ False False │ 2 │ 0.002977 │
│ ncode_by_exe │ │ │ False │ │ │
│ cutors/848e2 │ │ │ │ │ │
│ 3b8 │ │ │ │ │ │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘
Passed Tests: 1/2 Percentage: 50.000%
Failed Tests: 1/2 Percentage: 50.000%
Adding 2 test results to /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v1.0/var/logs/buildtest_06yo3gtk.log