Buildspec Overview

What is a buildspec?

In buildtest, we refer to buildspec as a YAML file that defines your test that buildtest will parse using the provided schemas and build a shell script from the buildspec file. Every buildspec is validated with a global schema which you can find more if you click here.

Example

Let’s start off with a simple example that declares two variables X and Y and prints the sum of X+Y.

version: "1.0"
buildspecs:
  add_numbers:
    type: script
    executor: generic.local.bash
    description: Add X+Y
    tags: [tutorials]
    vars:
      X: 1
      Y: 2
    run: echo "$X+$Y=" $(($X+$Y))

buildtest will validate the entire file with global.schema.json, the schema requires version and buildspec in order to validate file. The buildspec is where you define each test. The name of the test is add_numbers. The test requires a type field which is the sub-schema used to validate the test section. In this example type: script informs buildtest to use the Script Schema when validating test section.

Each subschema has a list of field attributes that are supported, for example the fields: type, executor, vars and run are all valid fields supported by the script schema. The version field informs which version of subschema to use. Currently all sub-schemas are at version 1.0 where buildtest will validate with a schema script-v1.0.schema.json. In future, we can support multiple versions of subschema for backwards compatibility.

Let’s look at a more interesting example, shown below is a multi line run example using the script schema with test name called systemd_default_target, shown below is the content of test:

version: "1.0"
buildspecs:
  systemd_default_target:
    executor: generic.local.bash
    type: script
    tags: [system]
    description: check if default target is multi-user.target
    run: |
      if [ "multi-user.target" == `systemctl get-default` ]; then
        echo "multi-user is the default target";
        exit 0
      fi
      echo "multi-user is not the default target";
      exit 1

The test name systemd_default_target defined in buildspec section is validated with the following pattern "^[A-Za-z_][A-Za-z0-9_]*$". This test will use the executor generic.local.bash which means it will use the Local Executor with an executor name bash defined in the buildtest settings. The default buildtest settings will provide a bash executor as follows:

system:
  generic:
    hostnames: ["localhost"]
    executors:
      local:
        bash:
          description: submit jobs on local machine using bash shell
          shell: bash

The shell: bash indicates this executor will use bash to run the test scripts. To reference this executor use the format <system>.<type>.<name> in this case generic.local.bash refers to bash executor.

The description field is an optional key that can be used to provide a brief summary of the test. In this example we can a full multi-line run section, this is achieved in YAML using run: | followed by content of run section tab indented 2 spaces.

Script Schema

The script schema is used for writing simple scripts (bash, sh, python) in Buildspec. To use this schema you must set type: script. The run field is responsible for writing the content of test.

Shown below is schema header for script-v1.0.schema.json.

{
  "$id": "script-v1.0.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "script schema version 1.0",
  "description": "The script schema is of ``type: script`` in sub-schema which is used for running shell scripts",
  "type": "object",
  "required": ["type", "run", "executor"],
  "additionalProperties": false,

The "type": "object" means sub-schema is a JSON object where we define a list of key/value pair. The "required" field specifies a list of fields that must be specified in order to validate the Buildspec. In this example, type, run, and executor are required fields. The additionalProperties: false informs schema to reject any extra properties not defined in the schema.

The executor key is required for all sub-schemas which instructs buildtest which executor to use when running the test. The executors are defined in Configuring buildtest. In our first example we define variables using the vars property which is a Key/Value pair for variable assignment. The run section is required for script schema which defines the content of the test script.

For more details on script schema see schema docs at https://buildtesters.github.io/buildtest/

Declaring Environment Variables

You can define environment variables using the env property, this is compatible with shells: bash, sh, zsh, csh and tcsh. It does not work with shell: python. In example below we declare three tests using environment variable with default shell (bash), csh, and tcsh

version: "1.0"
buildspecs:
  bash_env_variables:
    executor: generic.local.bash
    description: Declare environment variables in default shell (bash)
    type: script
    env:
      FIRST_NAME: avocado
      LAST_NAME: dinosaur
    tags: [tutorials]
    run: |
      hostname
      whoami
      echo $USER
      printf "${FIRST_NAME} ${LAST_NAME}\n"

  csh_env_declaration:
    executor: generic.local.csh
    type: script
    description: "csh shell example to declare environment variables"
    shell: /bin/csh
    tags: [tutorials]
    env:
      SHELL_NAME: "csh"
    run: echo "This is running $SHELL_NAME"

  tcsh_env_declaration:
    executor: generic.local.csh
    type: script
    description: "tcsh shell example to declare environment variables"
    shell: /bin/tcsh
    tags: [tutorials]
    env:
      path: "/usr/local/bin:$PATH"
    run: echo $path

This test can be run by issuing the following command: buildtest build -b tutorials/environment.yml. If we inspect one of the test script we will see that buildtest generates a build script that invokes the test using the shell wrapper /bin/csh for the csh test and gets the returncode.

#!/bin/bash


############# START VARIABLE DECLARATION ########################
export BUILDTEST_TEST_NAME=csh_env_declaration
export BUILDTEST_TEST_ROOT=/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.csh/environment/csh_env_declaration/0
export BUILDTEST_BUILDSPEC_DIR=/Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials
export BUILDTEST_STAGE_DIR=/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.csh/environment/csh_env_declaration/0/stage
export BUILDTEST_TEST_ID=501ec5d3-e614-4ae8-9c1e-4849ce340c76
############# END VARIABLE DECLARATION   ########################


# source executor startup script
source /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/executor/generic.local.csh/before_script.sh
# Run generated script
/bin/csh /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.csh/environment/csh_env_declaration/0/stage/csh_env_declaration.csh
# Get return code
returncode=$?
# Exit with return code
exit $returncode

This generated test looks something like this

#!/bin/csh
# Declare environment variables
setenv SHELL_NAME csh


# Content of run section
echo "This is running $SHELL_NAME"

Environment variables are defined using export in bash, sh, zsh while csh and tcsh use setenv.

Declaring Variables

Variables can be defined using vars property, this is compatible with all shells except for python. The variables are defined slightly different in csh, tcsh as pose to bash, sh, and zsh. In example below we define tests with bash and csh.

In YAML strings can be specified with or without quotes however in bash, variables need to be enclosed in quotes " if you are defining a multi word string (name="First Last").

If you need define a literal string it is recommended to use the literal block | that is a special character in YAML. If you want to specify " or ' in string you can use the escape character \ followed by any of the special character. In example below we define several variables such as X, Y that contain numbers, variable literalstring is a literal string processed by YAML. The variable singlequote and doublequote defines a variable with the special character ' and ". The variables current_user and num_files store result of a shell command. This can be done using var=$(<command>) or var=`<command>` where <command> is a Linux command.

version: "1.0"
buildspecs:
  variables_bash:
    type: script
    executor: generic.local.bash
    description: Declare shell variables in bash
    tags: [tutorials]
    vars:
      X: 1
      Y: 2
      literalstring: |
        "this is a literal string ':' "
      singlequote: \'singlequote\'
      doublequote: \"doublequote\"
      current_user: "$(whoami)"
      num_files: "`find $HOME -type f -maxdepth 1 | wc -l`"

    run: |
      echo "$X+$Y="$(($X+$Y))
      echo $literalstring
      echo $singlequote
      echo $doublequote
      echo "current user:" $current_user
      echo "number of files:" $num_files

Next we build this test by running buildtest build -b $BUILDTEST_ROOT/tutorials/vars.yml.

$ buildtest build -b $BUILDTEST_ROOT/tutorials/vars.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-15773998-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2022/01/14 16:19:40                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest                                             │
│ buildtest version:  0.12.0                                                   │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/envs/devel/bin/python3                                                    │
│ python version:     3.7.12                                                   │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/buildtest/settings/config.yml                             │
│ Test Directory:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/var/tests                                                 │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest build -b /home/docs/checkouts/readthedocs.o │
│ rg/user_builds/buildtest/checkouts/devel/tutorials/vars.yml                  │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                   ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ║
╚══════════════════════════════════════════════════════════════════════════════╝
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutor
ials/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          ┃ description      ┃ buildspecs        ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ variables_bash/3f │ generic.local.bas │ Declare shell    │ /home/docs/checko │
│ 523fb6            │ h                 │ variables in     │ uts/readthedocs.o │
│                   │                   │ bash             │ rg/user_builds/bu │
│                   │                   │                  │ ildtest/checkouts │
│                   │                   │                  │ /devel/tutorials/ │
│                   │                   │                  │ vars.yml          │
└───────────────────┴───────────────────┴──────────────────┴───────────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
variables_bash/3f523fb6: Creating test directory: /home/docs/checkouts/readthedo
cs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/vars/v
ariables_bash/3f523fb6
variables_bash/3f523fb6: Creating the stage directory: /home/docs/checkouts/read
thedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/v
ars/variables_bash/3f523fb6/stage
variables_bash/3f523fb6: Writing build script: /home/docs/checkouts/readthedocs.
org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/vars/vari
ables_bash/3f523fb6/variables_bash_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
______________________________
Launching test: variables_bash/3f523fb6
variables_bash/3f523fb6: Running Test via command: bash --norc --noprofile -eo 
pipefail variables_bash_build.sh
variables_bash/3f523fb6: Test completed with returncode: 0
variables_bash/3f523fb6: Test completed in 0.013659 seconds
variables_bash/3f523fb6: Writing output file -  /home/docs/checkouts/readthedocs
.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/vars/var
iables_bash/3f523fb6/variables_bash.out
variables_bash/3f523fb6: Writing error file - /home/docs/checkouts/readthedocs.o
rg/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/vars/varia
bles_bash/3f523fb6/variables_bash.err
                                  Test Summary                                  
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃              ┃              ┃        ┃ Checks        ┃            ┃          ┃
┃              ┃              ┃        ┃ (ReturnCode,  ┃            ┃          ┃
┃              ┃              ┃        ┃ Regex,        ┃            ┃          ┃
┃ Builder      ┃ executor     ┃ status ┃ Runtime)      ┃ ReturnCode ┃ Runtime  ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ variables_ba │ generic.loc… │ PASS   │ N/A N/A N/A   │ 0          │ 0.013659 │
│ sh/3f523fb6  │              │        │               │            │          │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘



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/buildt
est/checkouts/devel/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/logs/buildtest_9sh6erdm.log

Let’s check the generated script from the previous build, you can run buildtest inspect query -o variables_bash where -o refers to output file for testname variables_bash. Take note of the output file we

$ buildtest inspect query -o variables_bash
───────────── variables_bash/3f523fb6-8b62-4791-bf60-0e68ba5d53fd ──────────────
Executor: generic.local.bash
Description: Declare shell variables in bash
State: PASS
Returncode: 0
Runtime: 0.013659 sec
Starttime: 2022/01/14 16:19:40
Endtime: 2022/01/14 16:19:40
Command: bash --norc --noprofile -eo pipefail variables_bash_build.sh
Test Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/devel/var/tests/generic.local.bash/vars/variables_bash/3f523fb6/variables_bash
.sh
Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkou
ts/devel/var/tests/generic.local.bash/vars/variables_bash/3f523fb6/variables_bas
h_build.sh
Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/devel/var/tests/generic.local.bash/vars/variables_bash/3f523fb6/variables_bash
.out
Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts
/devel/var/tests/generic.local.bash/vars/variables_bash/3f523fb6/variables_bash.
err
Log File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/d
evel/var/logs/buildtest_9sh6erdm.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

Test Status

buildtest will record state of each test which can be PASS or FAIL. By default a 0 exit code is PASS and everything else is a FAIL. The status property can be used to determine how test will report its state. Currently, we can match state based on returncode, runtime, or regular expression.

Return Code Matching

buildtest can report PASS/FAIL based on returncode, by default a 0 exit code is PASS and everything else is FAIL. The returncode can be a list of exit codes to match. In this example we have four tests called exit1_fail, exit1_pass, returncode_list_mismatch and returncode_int_match. We expect exit1_fail and returncode_mismatch to FAIL while exit1_pass and returncode_int_match will PASS.

version: "1.0"
buildspecs:

  exit1_fail:
    executor: generic.local.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/pass_returncode.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-15773998-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2022/01/14 16:19:41                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest                                             │
│ buildtest version:  0.12.0                                                   │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/envs/devel/bin/python3                                                    │
│ python version:     3.7.12                                                   │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/buildtest/settings/config.yml                             │
│ Test Directory:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/var/tests                                                 │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest build -b tutorials/pass_returncode.yml      │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                   ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ║
╚══════════════════════════════════════════════════════════════════════════════╝
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutor
ials/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          ┃ description      ┃ buildspecs        ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ exit1_fail/3a1394 │ generic.local.bas │ exit 1 by        │ /home/docs/checko │
│ a9                │ h                 │ default is FAIL  │ uts/readthedocs.o │
│                   │                   │                  │ rg/user_builds/bu │
│                   │                   │                  │ ildtest/checkouts │
│                   │                   │                  │ /devel/tutorials/ │
│                   │                   │                  │ pass_returncode.y │
│                   │                   │                  │ ml                │
├───────────────────┼───────────────────┼──────────────────┼───────────────────┤
│ exit1_pass/ea45b1 │ generic.local.bas │ report exit 1 as │ /home/docs/checko │
│ 8c                │ h                 │ PASS             │ uts/readthedocs.o │
│                   │                   │                  │ rg/user_builds/bu │
│                   │                   │                  │ ildtest/checkouts │
│                   │                   │                  │ /devel/tutorials/ │
│                   │                   │                  │ pass_returncode.y │
│                   │                   │                  │ ml                │
├───────────────────┼───────────────────┼──────────────────┼───────────────────┤
│ returncode_list_m │ generic.local.bas │ exit 2 failed    │ /home/docs/checko │
│ ismatch/65482cdd  │ h                 │ since it failed  │ uts/readthedocs.o │
│                   │                   │ to match         │ rg/user_builds/bu │
│                   │                   │ returncode 1     │ ildtest/checkouts │
│                   │                   │                  │ /devel/tutorials/ │
│                   │                   │                  │ pass_returncode.y │
│                   │                   │                  │ ml                │
├───────────────────┼───────────────────┼──────────────────┼───────────────────┤
│ returncode_int_ma │ generic.local.bas │ exit 128 matches │ /home/docs/checko │
│ tch/82f93790      │ h                 │ returncode 128   │ uts/readthedocs.o │
│                   │                   │                  │ rg/user_builds/bu │
│                   │                   │                  │ ildtest/checkouts │
│                   │                   │                  │ /devel/tutorials/ │
│                   │                   │                  │ pass_returncode.y │
│                   │                   │                  │ ml                │
└───────────────────┴───────────────────┴──────────────────┴───────────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
exit1_fail/3a1394a9: Creating test directory: /home/docs/checkouts/readthedocs.o
rg/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/pass_retur
ncode/exit1_fail/3a1394a9
exit1_fail/3a1394a9: Creating the stage directory: /home/docs/checkouts/readthed
ocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/pass_
returncode/exit1_fail/3a1394a9/stage
exit1_fail/3a1394a9: Writing build script: /home/docs/checkouts/readthedocs.org/
user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/pass_returnco
de/exit1_fail/3a1394a9/exit1_fail_build.sh
exit1_pass/ea45b18c: Creating test directory: /home/docs/checkouts/readthedocs.o
rg/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/pass_retur
ncode/exit1_pass/ea45b18c
exit1_pass/ea45b18c: Creating the stage directory: /home/docs/checkouts/readthed
ocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/pass_
returncode/exit1_pass/ea45b18c/stage
exit1_pass/ea45b18c: Writing build script: /home/docs/checkouts/readthedocs.org/
user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/pass_returnco
de/exit1_pass/ea45b18c/exit1_pass_build.sh
returncode_list_mismatch/65482cdd: Creating test directory: /home/docs/checkouts
/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.b
ash/pass_returncode/returncode_list_mismatch/65482cdd
returncode_list_mismatch/65482cdd: Creating the stage directory: /home/docs/chec
kouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.lo
cal.bash/pass_returncode/returncode_list_mismatch/65482cdd/stage
returncode_list_mismatch/65482cdd: Writing build script: /home/docs/checkouts/re
adthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash
/pass_returncode/returncode_list_mismatch/65482cdd/returncode_list_mismatch_buil
d.sh
returncode_int_match/82f93790: Creating test directory: /home/docs/checkouts/rea
dthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/
pass_returncode/returncode_int_match/82f93790
returncode_int_match/82f93790: Creating the stage directory: /home/docs/checkout
s/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.
bash/pass_returncode/returncode_int_match/82f93790/stage
returncode_int_match/82f93790: Writing build script: /home/docs/checkouts/readth
edocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/pas
s_returncode/returncode_int_match/82f93790/returncode_int_match_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
______________________________
Launching test: exit1_fail/3a1394a9
______________________________
Launching test: exit1_pass/ea45b18c
______________________________
Launching test: returncode_list_mismatch/65482cdd
______________________________
Launching test: returncode_int_match/82f93790
exit1_fail/3a1394a9: Running Test via command: bash --norc --noprofile -eo 
pipefail exit1_fail_build.sh
exit1_pass/ea45b18c: Running Test via command: bash --norc --noprofile -eo 
pipefail exit1_pass_build.sh
exit1_pass/ea45b18c: Test completed with returncode: 1
exit1_pass/ea45b18c: Test completed in 0.026021 seconds
exit1_pass/ea45b18c: Writing output file -  /home/docs/checkouts/readthedocs.org
/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/pass_returnc
ode/exit1_pass/ea45b18c/exit1_pass.out
exit1_pass/ea45b18c: Writing error file - /home/docs/checkouts/readthedocs.org/u
ser_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/pass_returncod
e/exit1_pass/ea45b18c/exit1_pass.err
exit1_pass/ea45b18c: Checking returncode - 1 is matched in list [1]
returncode_list_mismatch/65482cdd: Running Test via command: bash --norc 
--noprofile -eo pipefail returncode_list_mismatch_build.sh
exit1_fail/3a1394a9: Test completed with returncode: 1
exit1_fail/3a1394a9: Test completed in 0.038435 seconds
exit1_fail/3a1394a9: Writing output file -  /home/docs/checkouts/readthedocs.org
/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/pass_returnc
ode/exit1_fail/3a1394a9/exit1_fail.out
exit1_fail/3a1394a9: Writing error file - /home/docs/checkouts/readthedocs.org/u
ser_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/pass_returncod
e/exit1_fail/3a1394a9/exit1_fail.err
returncode_int_match/82f93790: Running Test via command: bash --norc --noprofile
-eo pipefail returncode_int_match_build.sh
returncode_list_mismatch/65482cdd: Test completed with returncode: 2
returncode_list_mismatch/65482cdd: Test completed in 0.030233 seconds
returncode_int_match/82f93790: Test completed with returncode: 128
returncode_int_match/82f93790: Test completed in 0.024643 seconds
returncode_list_mismatch/65482cdd: Writing output file -  /home/docs/checkouts/r
eadthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bas
h/pass_returncode/returncode_list_mismatch/65482cdd/returncode_list_mismatch.out
returncode_list_mismatch/65482cdd: Writing error file - /home/docs/checkouts/rea
dthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/
pass_returncode/returncode_list_mismatch/65482cdd/returncode_list_mismatch.err
returncode_int_match/82f93790: Writing output file -  /home/docs/checkouts/readt
hedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/pa
ss_returncode/returncode_int_match/82f93790/returncode_int_match.out
returncode_list_mismatch/65482cdd: Checking returncode - 2 is matched in list 
[1, 3]
returncode_int_match/82f93790: Writing error file - /home/docs/checkouts/readthe
docs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/pass
_returncode/returncode_int_match/82f93790/returncode_int_match.err
returncode_int_match/82f93790: Checking returncode - 128 is matched in list 
[128]
                                  Test Summary                                  
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃              ┃              ┃        ┃ Checks        ┃            ┃          ┃
┃              ┃              ┃        ┃ (ReturnCode,  ┃            ┃          ┃
┃              ┃              ┃        ┃ Regex,        ┃            ┃          ┃
┃ Builder      ┃ executor     ┃ status ┃ Runtime)      ┃ ReturnCode ┃ Runtime  ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ exit1_fail/3 │ generic.loc… │ FAIL   │ N/A N/A N/A   │ 1          │ 0.038435 │
│ a1394a9      │              │        │               │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ exit1_pass/e │ generic.loc… │ PASS   │ True False    │ 1          │ 0.026021 │
│ a45b18c      │              │        │ False         │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ returncode_l │ generic.loc… │ FAIL   │ False False   │ 2          │ 0.030233 │
│ ist_mismatch │              │        │ False         │            │          │
│ /65482cdd    │              │        │               │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ returncode_i │ generic.loc… │ PASS   │ True False    │ 128        │ 0.024643 │
│ nt_match/82f │              │        │ False         │            │          │
│ 93790        │              │        │               │            │          │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘



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/buildt
est/checkouts/devel/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/logs/buildtest_32gx13p9.log

The returncode field can be an integer or list of integers but it may not accept duplicate values. If you specify a list of exit codes, buildtest will check actual returncode with list of expected returncodes specified by returncode field.

Shown below are examples of invalid returncodes:

# empty list is not allowed
returncode: []

# floating point is not accepted in list
returncode: [1, 1.5]

# floating point not accepted
returncode: 1.5

# duplicates are not allowed
returncode: [1, 2, 5, 5]

Passing Test based on regular expression

buildtest can configure PASS/FAIL of test based on regular expression on output or error file. This can be useful if you are expecting a certain output from the test as pose to returncode check.

In this example we introduce, the regex field which is part of status that expects a regular expression via exp. The stream property must be stdout or stderr which indicates buildtest will read output or error file and apply regular expression. If there is a match, buildtest will record the test state as PASS otherwise it will be a FAIL. In this example, we have two tests that will apply regular expression on output file.

version: "1.0"
buildspecs:
  status_regex_pass:
    executor: generic.local.bash
    type: script
    tags: [system]
    description: Pass test based on regular expression
    run: echo "PASS"
    status:
      regex:
        stream: stdout
        exp: "^(PASS)$"

  status_regex_fail:
    executor: generic.local.bash
    type: script
    tags: [system]
    description: Pass test based on regular expression
    run: echo "FAIL"
    status:
      regex:
        stream: stdout
        exp: "^(123FAIL)$"

Now if we run this test, we will see first test will pass while second one will fail even though the returncode is a 0. Take a close look at the status property

$ buildtest build -b tutorials/status_regex.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-15773998-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2022/01/14 16:19:42                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest                                             │
│ buildtest version:  0.12.0                                                   │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/envs/devel/bin/python3                                                    │
│ python version:     3.7.12                                                   │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/buildtest/settings/config.yml                             │
│ Test Directory:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/var/tests                                                 │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest build -b tutorials/status_regex.yml         │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                   ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ║
╚══════════════════════════════════════════════════════════════════════════════╝
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutor
ials/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          ┃ description      ┃ buildspecs        ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ status_regex_pass │ generic.local.bas │ Pass test based  │ /home/docs/checko │
│ /c8ff5767         │ h                 │ on regular       │ uts/readthedocs.o │
│                   │                   │ expression       │ rg/user_builds/bu │
│                   │                   │                  │ ildtest/checkouts │
│                   │                   │                  │ /devel/tutorials/ │
│                   │                   │                  │ status_regex.yml  │
├───────────────────┼───────────────────┼──────────────────┼───────────────────┤
│ status_regex_fail │ generic.local.bas │ Pass test based  │ /home/docs/checko │
│ /34d7e3e2         │ h                 │ on regular       │ uts/readthedocs.o │
│                   │                   │ expression       │ rg/user_builds/bu │
│                   │                   │                  │ ildtest/checkouts │
│                   │                   │                  │ /devel/tutorials/ │
│                   │                   │                  │ status_regex.yml  │
└───────────────────┴───────────────────┴──────────────────┴───────────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
status_regex_pass/c8ff5767: Creating test directory: /home/docs/checkouts/readth
edocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/sta
tus_regex/status_regex_pass/c8ff5767
status_regex_pass/c8ff5767: Creating the stage directory: /home/docs/checkouts/r
eadthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bas
h/status_regex/status_regex_pass/c8ff5767/stage
status_regex_pass/c8ff5767: Writing build script: /home/docs/checkouts/readthedo
cs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/status
_regex/status_regex_pass/c8ff5767/status_regex_pass_build.sh
status_regex_fail/34d7e3e2: Creating test directory: /home/docs/checkouts/readth
edocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/sta
tus_regex/status_regex_fail/34d7e3e2
status_regex_fail/34d7e3e2: Creating the stage directory: /home/docs/checkouts/r
eadthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bas
h/status_regex/status_regex_fail/34d7e3e2/stage
status_regex_fail/34d7e3e2: Writing build script: /home/docs/checkouts/readthedo
cs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/status
_regex/status_regex_fail/34d7e3e2/status_regex_fail_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
______________________________
Launching test: status_regex_pass/c8ff5767
______________________________
Launching test: status_regex_fail/34d7e3e2
status_regex_fail/34d7e3e2: Running Test via command: bash --norc --noprofile 
-eo pipefail status_regex_fail_build.sh
status_regex_pass/c8ff5767: Running Test via command: bash --norc --noprofile 
-eo pipefail status_regex_pass_build.sh
status_regex_fail/34d7e3e2: Test completed with returncode: 0
status_regex_fail/34d7e3e2: Test completed in 0.01973 seconds
status_regex_fail/34d7e3e2: Writing output file -  /home/docs/checkouts/readthed
ocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/statu
s_regex/status_regex_fail/34d7e3e2/status_regex_fail.out
status_regex_fail/34d7e3e2: Writing error file - /home/docs/checkouts/readthedoc
s.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/status_
regex/status_regex_fail/34d7e3e2/status_regex_fail.err
status_regex_pass/c8ff5767: Test completed with returncode: 0
status_regex_pass/c8ff5767: Test completed in 0.025499 seconds
status_regex_fail/34d7e3e2: performing regular expression - '^(123FAIL)$' on 
file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel
/var/tests/generic.local.bash/status_regex/status_regex_fail/34d7e3e2/status_reg
ex_fail.out
status_regex_fail/34d7e3e2: Regular Expression Match - Failed!
status_regex_pass/c8ff5767: Writing output file -  /home/docs/checkouts/readthed
ocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/statu
s_regex/status_regex_pass/c8ff5767/status_regex_pass.out
status_regex_pass/c8ff5767: Writing error file - /home/docs/checkouts/readthedoc
s.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/status_
regex/status_regex_pass/c8ff5767/status_regex_pass.err
status_regex_pass/c8ff5767: performing regular expression - '^(PASS)$' on file: 
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/t
ests/generic.local.bash/status_regex/status_regex_pass/c8ff5767/status_regex_pas
s.out
status_regex_pass/c8ff5767: Regular Expression Match - Success!
                                  Test Summary                                  
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃              ┃              ┃        ┃ Checks        ┃            ┃          ┃
┃              ┃              ┃        ┃ (ReturnCode,  ┃            ┃          ┃
┃              ┃              ┃        ┃ Regex,        ┃            ┃          ┃
┃ Builder      ┃ executor     ┃ status ┃ Runtime)      ┃ ReturnCode ┃ Runtime  ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ status_regex │ generic.loc… │ PASS   │ False True    │ 0          │ 0.025499 │
│ _pass/c8ff57 │              │        │ False         │            │          │
│ 67           │              │        │               │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ status_regex │ generic.loc… │ FAIL   │ False False   │ 0          │ 0.01973  │
│ _fail/34d7e3 │              │        │ False         │            │          │
│ e2           │              │        │               │            │          │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘



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/buildt
est/checkouts/devel/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/logs/buildtest_xomzcxla.log

Passing Test based on runtime

buildtest can determine state of test based on runtime property which is part of status object. This can be used if you want to control how test PASS or FAIL based on execution time of test. In example below we have five tests that make use of runtime property for passing a test. The runtime property support min and max property that can mark test pass based on minimum and maximum runtime. A test will pass if it’s execution time is greater than min time and less than max time. If min is specified without max property the upperbound is not set, likewise max without min will pass if test is less than max time. The lower bound is not set, but test runtime will be greater than 0 sec.

In test timelimit_min, we sleep for 2 seconds and it will pass because minimum runtime is 1.0 seconds. Similarly, timelimit_max will pass because we sleep for 2 seconds with a max time of 5.0.

version: "1.0"
buildspecs:
  timelimit_min_max:
    type: script
    executor: generic.local.sh
    description: "Run a sleep job for 2 seconds and test pass if its within 1.0-3.0sec"
    tags: ["tutorials"]
    run: sleep 2
    status:
      runtime:
        min: 1.0
        max: 3.0


  timelimit_min:
    type: script
    executor: generic.local.sh
    description: "Run a sleep job for 2 seconds and test pass if its exceeds min time of 1.0 sec"
    tags: ["tutorials"]
    run: sleep 2
    status:
      runtime:
        min: 1.0

  timelimit_max:
    type: script
    executor: generic.local.sh
    description: "Run a sleep job for 2 seconds and test pass if it's within max time: 5.0 sec"
    tags: ["tutorials"]
    run: sleep 2
    status:
      runtime:
        max: 5.0


  timelimit_min_fail:
    type: script
    executor: generic.local.sh
    description: "This test fails because it runs less than mintime of 10 second"
    tags: ["tutorials"]
    run: sleep 2
    status:
      runtime:
        min: 10.0

  timelimit_max_fail:
    type: script
    executor: generic.local.sh
    description: "This test fails because it exceeds maxtime of 1.0 second"
    tags: ["tutorials"]
    run: sleep 3
    status:
      runtime:
        max: 1.0
$ buildtest build -b tutorials/runtime_status_test.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-15773998-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2022/01/14 16:19:43                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest                                             │
│ buildtest version:  0.12.0                                                   │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/envs/devel/bin/python3                                                    │
│ python version:     3.7.12                                                   │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/buildtest/settings/config.yml                             │
│ Test Directory:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/var/tests                                                 │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest build -b tutorials/runtime_status_test.yml  │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                   ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ║
╚══════════════════════════════════════════════════════════════════════════════╝
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutor
ials/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         ┃ description       ┃ buildspecs        ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ timelimit_min_max │ generic.local.sh │ Run a sleep job   │ /home/docs/checko │
│ /482220d0         │                  │ for 2 seconds and │ uts/readthedocs.o │
│                   │                  │ test pass if its  │ rg/user_builds/bu │
│                   │                  │ within 1.0-3.0sec │ ildtest/checkouts │
│                   │                  │                   │ /devel/tutorials/ │
│                   │                  │                   │ runtime_status_te │
│                   │                  │                   │ st.yml            │
├───────────────────┼──────────────────┼───────────────────┼───────────────────┤
│ timelimit_min/8e4 │ generic.local.sh │ Run a sleep job   │ /home/docs/checko │
│ 8177a             │                  │ for 2 seconds and │ uts/readthedocs.o │
│                   │                  │ test pass if its  │ rg/user_builds/bu │
│                   │                  │ exceeds min time  │ ildtest/checkouts │
│                   │                  │ of 1.0 sec        │ /devel/tutorials/ │
│                   │                  │                   │ runtime_status_te │
│                   │                  │                   │ st.yml            │
├───────────────────┼──────────────────┼───────────────────┼───────────────────┤
│ timelimit_max/433 │ generic.local.sh │ Run a sleep job   │ /home/docs/checko │
│ 0feab             │                  │ for 2 seconds and │ uts/readthedocs.o │
│                   │                  │ test pass if it's │ rg/user_builds/bu │
│                   │                  │ within max time:  │ ildtest/checkouts │
│                   │                  │ 5.0 sec           │ /devel/tutorials/ │
│                   │                  │                   │ runtime_status_te │
│                   │                  │                   │ st.yml            │
├───────────────────┼──────────────────┼───────────────────┼───────────────────┤
│ timelimit_min_fai │ generic.local.sh │ This test fails   │ /home/docs/checko │
│ l/bab68a56        │                  │ because it runs   │ uts/readthedocs.o │
│                   │                  │ less than mintime │ rg/user_builds/bu │
│                   │                  │ of 10 second      │ ildtest/checkouts │
│                   │                  │                   │ /devel/tutorials/ │
│                   │                  │                   │ runtime_status_te │
│                   │                  │                   │ st.yml            │
├───────────────────┼──────────────────┼───────────────────┼───────────────────┤
│ timelimit_max_fai │ generic.local.sh │ This test fails   │ /home/docs/checko │
│ l/0b4a545a        │                  │ because it        │ uts/readthedocs.o │
│                   │                  │ exceeds maxtime   │ rg/user_builds/bu │
│                   │                  │ of 1.0 second     │ ildtest/checkouts │
│                   │                  │                   │ /devel/tutorials/ │
│                   │                  │                   │ runtime_status_te │
│                   │                  │                   │ st.yml            │
└───────────────────┴──────────────────┴───────────────────┴───────────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
timelimit_min_max/482220d0: Creating test directory: /home/docs/checkouts/readth
edocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runti
me_status_test/timelimit_min_max/482220d0
timelimit_min_max/482220d0: Creating the stage directory: /home/docs/checkouts/r
eadthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/
runtime_status_test/timelimit_min_max/482220d0/stage
timelimit_min_max/482220d0: Writing build script: /home/docs/checkouts/readthedo
cs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtime_
status_test/timelimit_min_max/482220d0/timelimit_min_max_build.sh
timelimit_min/8e48177a: Creating test directory: /home/docs/checkouts/readthedoc
s.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtime_s
tatus_test/timelimit_min/8e48177a
timelimit_min/8e48177a: Creating the stage directory: /home/docs/checkouts/readt
hedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runt
ime_status_test/timelimit_min/8e48177a/stage
timelimit_min/8e48177a: Writing build script: /home/docs/checkouts/readthedocs.o
rg/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtime_stat
us_test/timelimit_min/8e48177a/timelimit_min_build.sh
timelimit_max/4330feab: Creating test directory: /home/docs/checkouts/readthedoc
s.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtime_s
tatus_test/timelimit_max/4330feab
timelimit_max/4330feab: Creating the stage directory: /home/docs/checkouts/readt
hedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runt
ime_status_test/timelimit_max/4330feab/stage
timelimit_max/4330feab: Writing build script: /home/docs/checkouts/readthedocs.o
rg/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtime_stat
us_test/timelimit_max/4330feab/timelimit_max_build.sh
timelimit_min_fail/bab68a56: Creating test directory: /home/docs/checkouts/readt
hedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runt
ime_status_test/timelimit_min_fail/bab68a56
timelimit_min_fail/bab68a56: Creating the stage directory: /home/docs/checkouts/
readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh
/runtime_status_test/timelimit_min_fail/bab68a56/stage
timelimit_min_fail/bab68a56: Writing build script: /home/docs/checkouts/readthed
ocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtime
_status_test/timelimit_min_fail/bab68a56/timelimit_min_fail_build.sh
timelimit_max_fail/0b4a545a: Creating test directory: /home/docs/checkouts/readt
hedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runt
ime_status_test/timelimit_max_fail/0b4a545a
timelimit_max_fail/0b4a545a: Creating the stage directory: /home/docs/checkouts/
readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh
/runtime_status_test/timelimit_max_fail/0b4a545a/stage
timelimit_max_fail/0b4a545a: Writing build script: /home/docs/checkouts/readthed
ocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtime
_status_test/timelimit_max_fail/0b4a545a/timelimit_max_fail_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
______________________________
Launching test: timelimit_min_max/482220d0
______________________________
Launching test: timelimit_min/8e48177a
______________________________
Launching test: timelimit_max/4330feab
______________________________
Launching test: timelimit_min_fail/bab68a56
______________________________
Launching test: timelimit_max_fail/0b4a545a
timelimit_min_max/482220d0: Running Test via command: sh --norc --noprofile -eo 
pipefail timelimit_min_max_build.sh
timelimit_min/8e48177a: Running Test via command: sh --norc --noprofile -eo 
pipefail timelimit_min_build.sh
timelimit_min/8e48177a: Test completed with returncode: 2
timelimit_min/8e48177a: Test completed in 0.01259 seconds
timelimit_min_max/482220d0: Test completed with returncode: 2
timelimit_min_max/482220d0: Test completed in 0.015386 seconds
timelimit_min/8e48177a: Writing output file -  /home/docs/checkouts/readthedocs.
org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtime_sta
tus_test/timelimit_min/8e48177a/timelimit_min.out
timelimit_min_max/482220d0: Writing output file -  /home/docs/checkouts/readthed
ocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtime
_status_test/timelimit_min_max/482220d0/timelimit_min_max.out
timelimit_min/8e48177a: Writing error file - /home/docs/checkouts/readthedocs.or
g/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtime_statu
s_test/timelimit_min/8e48177a/timelimit_min.err
timelimit_min_max/482220d0: Writing error file - /home/docs/checkouts/readthedoc
s.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtime_s
tatus_test/timelimit_min_max/482220d0/timelimit_min_max.err
timelimit_max/4330feab: Running Test via command: sh --norc --noprofile -eo 
pipefail timelimit_max_build.sh
timelimit_min_fail/bab68a56: Running Test via command: sh --norc --noprofile -eo
pipefail timelimit_min_fail_build.sh
timelimit_max/4330feab: Test completed with returncode: 2
timelimit_max/4330feab: Test completed in 0.004452 seconds
timelimit_max/4330feab: Writing output file -  /home/docs/checkouts/readthedocs.
org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtime_sta
tus_test/timelimit_max/4330feab/timelimit_max.out
timelimit_max/4330feab: Writing error file - /home/docs/checkouts/readthedocs.or
g/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtime_statu
s_test/timelimit_max/4330feab/timelimit_max.err
timelimit_max_fail/0b4a545a: Running Test via command: sh --norc --noprofile -eo
pipefail timelimit_max_fail_build.sh
timelimit_min_fail/bab68a56: Test completed with returncode: 2
timelimit_min_fail/bab68a56: Test completed in 0.014496 seconds
timelimit_min_fail/bab68a56: Writing output file -  /home/docs/checkouts/readthe
docs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtim
e_status_test/timelimit_min_fail/bab68a56/timelimit_min_fail.out
timelimit_min_fail/bab68a56: Writing error file - /home/docs/checkouts/readthedo
cs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtime_
status_test/timelimit_min_fail/bab68a56/timelimit_min_fail.err
timelimit_max_fail/0b4a545a: Test completed with returncode: 2
timelimit_max_fail/0b4a545a: Test completed in 0.011478 seconds
timelimit_max_fail/0b4a545a: Writing output file -  /home/docs/checkouts/readthe
docs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtim
e_status_test/timelimit_max_fail/0b4a545a/timelimit_max_fail.out
timelimit_max_fail/0b4a545a: Writing error file - /home/docs/checkouts/readthedo
cs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/runtime_
status_test/timelimit_max_fail/0b4a545a/timelimit_max_fail.err
                                  Test Summary                                  
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃              ┃              ┃        ┃ Checks        ┃            ┃          ┃
┃              ┃              ┃        ┃ (ReturnCode,  ┃            ┃          ┃
┃              ┃              ┃        ┃ Regex,        ┃            ┃          ┃
┃ Builder      ┃ executor     ┃ status ┃ Runtime)      ┃ ReturnCode ┃ Runtime  ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ timelimit_mi │ generic.loc… │ FAIL   │ False False   │ 2          │ 0.015386 │
│ n_max/482220 │              │        │ False         │            │          │
│ d0           │              │        │               │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ timelimit_mi │ generic.loc… │ FAIL   │ False False   │ 2          │ 0.01259  │
│ n/8e48177a   │              │        │ False         │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ timelimit_ma │ generic.loc… │ PASS   │ False False   │ 2          │ 0.004452 │
│ x/4330feab   │              │        │ True          │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ timelimit_mi │ generic.loc… │ FAIL   │ False False   │ 2          │ 0.014496 │
│ n_fail/bab68 │              │        │ False         │            │          │
│ a56          │              │        │               │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ timelimit_ma │ generic.loc… │ PASS   │ False False   │ 2          │ 0.011478 │
│ x_fail/0b4a5 │              │        │ True          │            │          │
│ 45a          │              │        │               │            │          │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘



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/buildt
est/checkouts/devel/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/logs/buildtest_l5lcofmc.log

If we look at the test results, we expect the first three tests timelimit_min, timelimit_max, timelimit_min_max will pass while the last two tests fail because it fails to comply with runtime property.

$ buildtest report --filter buildspec=tutorials/runtime_status_test.yml --format name,id,state,runtime --latest
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                            s/devel/var/report.json                             
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ name                           ┃ id             ┃ state      ┃ runtime       ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
│ timelimit_min_max              │ 482220d0       │ FAIL       │ 0.015386      │
├────────────────────────────────┼────────────────┼────────────┼───────────────┤
│ timelimit_min                  │ 8e48177a       │ FAIL       │ 0.01259       │
├────────────────────────────────┼────────────────┼────────────┼───────────────┤
│ timelimit_max                  │ 4330feab       │ PASS       │ 0.004452      │
├────────────────────────────────┼────────────────┼────────────┼───────────────┤
│ timelimit_min_fail             │ bab68a56       │ FAIL       │ 0.014496      │
├────────────────────────────────┼────────────────┼────────────┼───────────────┤
│ timelimit_max_fail             │ 0b4a545a       │ PASS       │ 0.011478      │
└────────────────────────────────┴────────────────┴────────────┴───────────────┘

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.

version: "1.0"
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/explicit_state.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-15773998-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2022/01/14 16:19:44                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest                                             │
│ buildtest version:  0.12.0                                                   │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/envs/devel/bin/python3                                                    │
│ python version:     3.7.12                                                   │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/buildtest/settings/config.yml                             │
│ Test Directory:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/var/tests                                                 │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest build -b tutorials/explicit_state.yml       │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                   ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ║
╚══════════════════════════════════════════════════════════════════════════════╝
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutor
ials/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         ┃ description       ┃ buildspecs        ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ always_pass/6138f │ generic.local.sh │ This test will    │ /home/docs/checko │
│ 29b               │                  │ always 'PASS'     │ uts/readthedocs.o │
│                   │                  │                   │ rg/user_builds/bu │
│                   │                  │                   │ ildtest/checkouts │
│                   │                  │                   │ /devel/tutorials/ │
│                   │                  │                   │ explicit_state.ym │
│                   │                  │                   │ l                 │
├───────────────────┼──────────────────┼───────────────────┼───────────────────┤
│ always_fail/60442 │ generic.local.sh │ This test will    │ /home/docs/checko │
│ 052               │                  │ always 'FAIL'     │ uts/readthedocs.o │
│                   │                  │                   │ rg/user_builds/bu │
│                   │                  │                   │ ildtest/checkouts │
│                   │                  │                   │ /devel/tutorials/ │
│                   │                  │                   │ explicit_state.ym │
│                   │                  │                   │ l                 │
├───────────────────┼──────────────────┼───────────────────┼───────────────────┤
│ test_fail_returnc │ generic.local.sh │ This test will    │ /home/docs/checko │
│ ode_match/536f2d3 │                  │ 'FAIL' even if we │ uts/readthedocs.o │
│ 7                 │                  │ have returncode   │ rg/user_builds/bu │
│                   │                  │ match             │ ildtest/checkouts │
│                   │                  │                   │ /devel/tutorials/ │
│                   │                  │                   │ explicit_state.ym │
│                   │                  │                   │ l                 │
├───────────────────┼──────────────────┼───────────────────┼───────────────────┤
│ test_pass_returnc │ generic.local.sh │ This test will    │ /home/docs/checko │
│ ode_mismatch/4b28 │                  │ 'PASS' even if we │ uts/readthedocs.o │
│ 7c0a              │                  │ have returncode   │ rg/user_builds/bu │
│                   │                  │ mismatch          │ ildtest/checkouts │
│                   │                  │                   │ /devel/tutorials/ │
│                   │                  │                   │ explicit_state.ym │
│                   │                  │                   │ l                 │
└───────────────────┴──────────────────┴───────────────────┴───────────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
always_pass/6138f29b: Creating test directory: /home/docs/checkouts/readthedocs.
org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/explicit_st
ate/always_pass/6138f29b
always_pass/6138f29b: Creating the stage directory: /home/docs/checkouts/readthe
docs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/explic
it_state/always_pass/6138f29b/stage
always_pass/6138f29b: Writing build script: /home/docs/checkouts/readthedocs.org
/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/explicit_state
/always_pass/6138f29b/always_pass_build.sh
always_fail/60442052: Creating test directory: /home/docs/checkouts/readthedocs.
org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/explicit_st
ate/always_fail/60442052
always_fail/60442052: Creating the stage directory: /home/docs/checkouts/readthe
docs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/explic
it_state/always_fail/60442052/stage
always_fail/60442052: Writing build script: /home/docs/checkouts/readthedocs.org
/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/explicit_state
/always_fail/60442052/always_fail_build.sh
test_fail_returncode_match/536f2d37: Creating test directory: /home/docs/checkou
ts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local
.sh/explicit_state/test_fail_returncode_match/536f2d37
test_fail_returncode_match/536f2d37: Creating the stage directory: /home/docs/ch
eckouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.
local.sh/explicit_state/test_fail_returncode_match/536f2d37/stage
test_fail_returncode_match/536f2d37: Writing build script: /home/docs/checkouts/
readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh
/explicit_state/test_fail_returncode_match/536f2d37/test_fail_returncode_match_b
uild.sh
test_pass_returncode_mismatch/4b287c0a: Creating test directory: /home/docs/chec
kouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.lo
cal.sh/explicit_state/test_pass_returncode_mismatch/4b287c0a
test_pass_returncode_mismatch/4b287c0a: Creating the stage directory: /home/docs
/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/gener
ic.local.sh/explicit_state/test_pass_returncode_mismatch/4b287c0a/stage
test_pass_returncode_mismatch/4b287c0a: Writing build script: /home/docs/checkou
ts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local
.sh/explicit_state/test_pass_returncode_mismatch/4b287c0a/test_pass_returncode_m
ismatch_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
______________________________
Launching test: always_pass/6138f29b
______________________________
Launching test: always_fail/60442052
______________________________
Launching test: test_fail_returncode_match/536f2d37
______________________________
Launching test: test_pass_returncode_mismatch/4b287c0a
always_pass/6138f29b: Running Test via command: sh --norc --noprofile -eo 
pipefail always_pass_build.sh
always_fail/60442052: Running Test via command: sh --norc --noprofile -eo 
pipefail always_fail_build.sh
always_fail/60442052: Test completed with returncode: 2
always_fail/60442052: Test completed in 0.013502 seconds
always_pass/6138f29b: Test completed with returncode: 2
always_fail/60442052: Writing output file -  /home/docs/checkouts/readthedocs.or
g/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/explicit_stat
e/always_fail/60442052/always_fail.out
always_pass/6138f29b: Test completed in 0.018165 seconds
always_fail/60442052: Writing error file - /home/docs/checkouts/readthedocs.org/
user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/explicit_state/
always_fail/60442052/always_fail.err
always_pass/6138f29b: Writing output file -  /home/docs/checkouts/readthedocs.or
g/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/explicit_stat
e/always_pass/6138f29b/always_pass.out
test_fail_returncode_match/536f2d37: Running Test via command: sh --norc 
--noprofile -eo pipefail test_fail_returncode_match_build.sh
always_pass/6138f29b: Writing error file - /home/docs/checkouts/readthedocs.org/
user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/explicit_state/
always_pass/6138f29b/always_pass.err
test_pass_returncode_mismatch/4b287c0a: Running Test via command: sh --norc 
--noprofile -eo pipefail test_pass_returncode_mismatch_build.sh
test_fail_returncode_match/536f2d37: Test completed with returncode: 2
test_fail_returncode_match/536f2d37: Test completed in 0.004307 seconds
test_fail_returncode_match/536f2d37: Writing output file -  /home/docs/checkouts
/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.s
h/explicit_state/test_fail_returncode_match/536f2d37/test_fail_returncode_match.
out
test_fail_returncode_match/536f2d37: Writing error file - /home/docs/checkouts/r
eadthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/
explicit_state/test_fail_returncode_match/536f2d37/test_fail_returncode_match.er
r
test_fail_returncode_match/536f2d37: Checking returncode - 2 is matched in list 
[1]
test_pass_returncode_mismatch/4b287c0a: Test completed with returncode: 2
test_pass_returncode_mismatch/4b287c0a: Test completed in 0.010277 seconds
test_pass_returncode_mismatch/4b287c0a: Writing output file -  /home/docs/checko
uts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.loca
l.sh/explicit_state/test_pass_returncode_mismatch/4b287c0a/test_pass_returncode_
mismatch.out
test_pass_returncode_mismatch/4b287c0a: Writing error file - /home/docs/checkout
s/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.
sh/explicit_state/test_pass_returncode_mismatch/4b287c0a/test_pass_returncode_mi
smatch.err
test_pass_returncode_mismatch/4b287c0a: Checking returncode - 2 is matched in 
list [2]
                                  Test Summary                                  
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃              ┃              ┃        ┃ Checks        ┃            ┃          ┃
┃              ┃              ┃        ┃ (ReturnCode,  ┃            ┃          ┃
┃              ┃              ┃        ┃ Regex,        ┃            ┃          ┃
┃ Builder      ┃ executor     ┃ status ┃ Runtime)      ┃ ReturnCode ┃ Runtime  ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ always_pass/ │ generic.loc… │ PASS   │ False False   │ 2          │ 0.018165 │
│ 6138f29b     │              │        │ False         │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ always_fail/ │ generic.loc… │ FAIL   │ False False   │ 2          │ 0.013502 │
│ 60442052     │              │        │ False         │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ test_fail_re │ generic.loc… │ FAIL   │ False False   │ 2          │ 0.004307 │
│ turncode_mat │              │        │ False         │            │          │
│ ch/536f2d37  │              │        │               │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ test_pass_re │ generic.loc… │ PASS   │ True False    │ 2          │ 0.010277 │
│ turncode_mis │              │        │ False         │            │          │
│ match/4b287c │              │        │               │            │          │
│ 0a           │              │        │               │            │          │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘



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/buildt
est/checkouts/devel/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/logs/buildtest_dd2dueju.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.

version: "1.0"
buildspecs:
  string_tag:
    type: script
    executor: generic.local.bash
    description: tags can be a string
    tags: network
    run: hostname

  list_of_strings_tags:
    type: script
    executor: generic.local.bash
    description: tags can be a list of strings
    tags: [network, ping]
    run: ping -c 4 www.google.com

Each item in tags must be a string and no duplicates are allowed, for example in this test, we define a duplicate tag network which is not allowed.

version: "1.0"
buildspecs:
  duplicate_string_tags:
    type: script
    executor: generic.local.bash
    description: duplicate strings in tags list is not allowed
    tags: [network, network]
    run: hostname

If we run this test and inspect the logs we will see an error message in schema validation:

2020-09-29 10:56:43,175 [parser.py:179 - _validate() ] - [INFO] Validating test - 'duplicate_string_tags' with schemafile: script-v1.0.schema.json
2020-09-29 10:56:43,175 [buildspec.py:397 - parse_buildspecs() ] - [ERROR] ['network', 'network'] is not valid under any of the given schemas

Failed validating 'oneOf' in schema['properties']['tags']:
    {'oneOf': [{'type': 'string'},
               {'$ref': '#/definitions/list_of_strings'}]}

On instance['tags']:
    ['network', 'network']

If tags is a list, it must contain one item, therefore an empty list (i.e tags: []) is invalid.

Customize Shell

Shell Type

buildtest will default to bash shell when running test, but we can configure shell option using the shell field. The shell field is defined in schema as follows:

"shell": {
  "type": "string",
  "description": "Specify a shell launcher to use when running jobs. This sets the shebang line in your test script. The ``shell`` key can be used with ``run`` section to describe content of script and how its executed",
  "pattern": "^(/bin/bash|/bin/sh|/bin/csh|/bin/tcsh|/bin/zsh|bash|sh|csh|tcsh|zsh|python).*"
},

The shell pattern is a regular expression where one can specify a shell name along with shell options. The shell will configure the shebang in the test-script. In this example, we illustrate a few tests using different shell field.

version: "1.0"
buildspecs:
  _bin_sh_shell:
    executor: generic.local.sh
    type: script
    description: "/bin/sh shell example"
    shell: /bin/sh
    tags: [tutorials]
    run: "bzip2 --help"

  _bin_bash_shell:
    executor: generic.local.bash
    type: script
    description: "/bin/bash shell example"
    shell: /bin/bash
    tags: [tutorials]
    run: "bzip2 -h"

  bash_shell:
    executor: generic.local.bash
    type: script
    description: "bash shell example"
    shell: bash
    tags: [tutorials]
    run: "echo $SHELL"

  sh_shell:
    executor: generic.local.sh
    type: script
    description: "sh shell example"
    shell: sh
    tags: [tutorials]
    run: "echo $SHELL"

  shell_options:
    executor: generic.local.sh
    type: script
    description: "shell options"
    shell: "sh -x"
    tags: [tutorials]
    run: |
      echo $SHELL
      hostname

The generated test-script for buildspec _bin_sh_shell will specify shebang /bin/sh because we specified shell: /bin/sh:

#!/bin/sh
# Content of run section
bzip2 --help

If you don’t specify a shell path such as shell: sh, then buildtest will resolve path by looking in $PATH and build the shebang line.

In test shell_options we specify shell: "sh -x", buildtest will tack on the shell options into the called script as follows:

#!/bin/bash


############# START VARIABLE DECLARATION ########################
export BUILDTEST_TEST_NAME=shell_options
export BUILDTEST_TEST_ROOT=/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.sh/shell_examples/shell_options/0
export BUILDTEST_BUILDSPEC_DIR=/Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials
export BUILDTEST_STAGE_DIR=/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.sh/shell_examples/shell_options/0/stage
export BUILDTEST_TEST_ID=95c11f54-bbb1-4154-849d-44313e4417c2
############# END VARIABLE DECLARATION   ########################


# source executor startup script
source /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/executor/generic.local.sh/before_script.sh
# Run generated script
sh -x /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.sh/shell_examples/shell_options/0/stage/shell_options.sh
# Get return code
returncode=$?
# Exit with return code
exit $returncode

If you prefer csh or tcsh for writing scripts just set shell: csh or shell: tcsh, note you will need to match this with appropriate executor. For now use executor: generic.local.csh to run your csh/tcsh scripts. In this example below we define a script using csh, take note of run section we can write csh style.

version: "1.0"
buildspecs:
  csh_shell:
    executor: generic.local.csh
    type: script
    description: "csh shell example"
    shell: csh
    tags: [tutorials]
    vars:
      file: "/etc/csh.cshrc"
    run: |
      if (-e $file) then
        echo "$file file found"
      else
        echo "$file file not found"
        exit 1
      endif

Customize Shebang

You may customize the shebang line in testscript using shebang field. This takes precedence over the shell property which automatically detects the shebang based on shell path.

In next example we have two tests bash_login_shebang and bash_nonlogin_shebang which tests if shell is Login or Non-Login. The #!/bin/bash -l indicates we want to run in login shell and expects an output of Login Shell while test bash_nonlogin_shebang should run in default behavior which is non-login shell and expects output Not Login Shell. We match this with regular expression with stdout stream.

version: "1.0"
buildspecs:
  bash_login_shebang:
    type: script
    executor: generic.local.bash
    shebang: "#!/bin/bash -l"
    description: customize shebang line with bash login shell
    tags: tutorials
    run: shopt -q login_shell && echo 'Login Shell' || echo 'Not Login Shell'
    status:
      regex:
        exp: "^Login Shell$"
        stream: stdout

  bash_nonlogin_shebang:
    type: script
    executor: generic.local.bash
    shebang: "#!/bin/bash"
    description: customize shebang line with default bash (nonlogin) shell
    tags: tutorials
    run: shopt -q login_shell && echo 'Login Shell' || echo 'Not Login Shell'
    status:
      regex:
        exp: "^Not Login Shell$"
        stream: stdout

Now let’s run this test as we see the following.

$ buildtest build -b tutorials/shebang.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-15773998-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2022/01/14 16:19:44                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest                                             │
│ buildtest version:  0.12.0                                                   │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/envs/devel/bin/python3                                                    │
│ python version:     3.7.12                                                   │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/buildtest/settings/config.yml                             │
│ Test Directory:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/var/tests                                                 │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest build -b tutorials/shebang.yml              │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                   ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ║
╚══════════════════════════════════════════════════════════════════════════════╝
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutor
ials/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          ┃ description      ┃ buildspecs        ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ bash_login_sheban │ generic.local.bas │ customize        │ /home/docs/checko │
│ g/5dd6d2b1        │ h                 │ shebang line     │ uts/readthedocs.o │
│                   │                   │ with bash login  │ rg/user_builds/bu │
│                   │                   │ shell            │ ildtest/checkouts │
│                   │                   │                  │ /devel/tutorials/ │
│                   │                   │                  │ shebang.yml       │
├───────────────────┼───────────────────┼──────────────────┼───────────────────┤
│ bash_nonlogin_she │ generic.local.bas │ customize        │ /home/docs/checko │
│ bang/e78886a2     │ h                 │ shebang line     │ uts/readthedocs.o │
│                   │                   │ with default     │ rg/user_builds/bu │
│                   │                   │ bash (nonlogin)  │ ildtest/checkouts │
│                   │                   │ shell            │ /devel/tutorials/ │
│                   │                   │                  │ shebang.yml       │
└───────────────────┴───────────────────┴──────────────────┴───────────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
bash_login_shebang/5dd6d2b1: Creating test directory: /home/docs/checkouts/readt
hedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/sh
ebang/bash_login_shebang/5dd6d2b1
bash_login_shebang/5dd6d2b1: Creating the stage directory: /home/docs/checkouts/
readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.ba
sh/shebang/bash_login_shebang/5dd6d2b1/stage
bash_login_shebang/5dd6d2b1: Writing build script: /home/docs/checkouts/readthed
ocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/sheba
ng/bash_login_shebang/5dd6d2b1/bash_login_shebang_build.sh
bash_nonlogin_shebang/e78886a2: Creating test directory: /home/docs/checkouts/re
adthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash
/shebang/bash_nonlogin_shebang/e78886a2
bash_nonlogin_shebang/e78886a2: Creating the stage directory: /home/docs/checkou
ts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local
.bash/shebang/bash_nonlogin_shebang/e78886a2/stage
bash_nonlogin_shebang/e78886a2: Writing build script: /home/docs/checkouts/readt
hedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/sh
ebang/bash_nonlogin_shebang/e78886a2/bash_nonlogin_shebang_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
______________________________
Launching test: bash_login_shebang/5dd6d2b1
______________________________
Launching test: bash_nonlogin_shebang/e78886a2
bash_login_shebang/5dd6d2b1: Running Test via command: bash --norc --noprofile 
-eo pipefail bash_login_shebang_build.sh
bash_nonlogin_shebang/e78886a2: Running Test via command: bash --norc 
--noprofile -eo pipefail bash_nonlogin_shebang_build.sh
bash_nonlogin_shebang/e78886a2: Test completed with returncode: 0
bash_nonlogin_shebang/e78886a2: Test completed in 0.023716 seconds
bash_login_shebang/5dd6d2b1: Test completed with returncode: 0
bash_nonlogin_shebang/e78886a2: Writing output file -  /home/docs/checkouts/read
thedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/s
hebang/bash_nonlogin_shebang/e78886a2/bash_nonlogin_shebang.out
bash_login_shebang/5dd6d2b1: Test completed in 0.027214 seconds
bash_nonlogin_shebang/e78886a2: Writing error file - /home/docs/checkouts/readth
edocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/she
bang/bash_nonlogin_shebang/e78886a2/bash_nonlogin_shebang.err
bash_nonlogin_shebang/e78886a2: performing regular expression - '^Not Login 
Shell$' on file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/chec
kouts/devel/var/tests/generic.local.bash/shebang/bash_nonlogin_shebang/e78886a2/
bash_nonlogin_shebang.out
bash_login_shebang/5dd6d2b1: Writing output file -  /home/docs/checkouts/readthe
docs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/sheb
ang/bash_login_shebang/5dd6d2b1/bash_login_shebang.out
bash_nonlogin_shebang/e78886a2: Regular Expression Match - Success!
bash_login_shebang/5dd6d2b1: Writing error file - /home/docs/checkouts/readthedo
cs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/sheban
g/bash_login_shebang/5dd6d2b1/bash_login_shebang.err
bash_login_shebang/5dd6d2b1: performing regular expression - '^Login Shell$' on 
file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel
/var/tests/generic.local.bash/shebang/bash_login_shebang/5dd6d2b1/bash_login_she
bang.out
bash_login_shebang/5dd6d2b1: Regular Expression Match - Success!
                                  Test Summary                                  
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃              ┃              ┃        ┃ Checks        ┃            ┃          ┃
┃              ┃              ┃        ┃ (ReturnCode,  ┃            ┃          ┃
┃              ┃              ┃        ┃ Regex,        ┃            ┃          ┃
┃ Builder      ┃ executor     ┃ status ┃ Runtime)      ┃ ReturnCode ┃ Runtime  ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ bash_login_s │ generic.loc… │ PASS   │ False True    │ 0          │ 0.027214 │
│ hebang/5dd6d │              │        │ False         │            │          │
│ 2b1          │              │        │               │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ bash_nonlogi │ generic.loc… │ PASS   │ False True    │ 0          │ 0.023716 │
│ n_shebang/e7 │              │        │ False         │            │          │
│ 8886a2       │              │        │               │            │          │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘



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/buildt
est/checkouts/devel/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/logs/buildtest_cwbp08j_.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

version: "1.0"
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.

version: "1.0"
buildspecs:
  skip:
    type: script
    executor: generic.local.bash
    description: This test is skipped
    skip: Yes
    tags: [tutorials]
    run: hostname

  unskipped:
    type: script
    executor: generic.local.bash
    description: This test is not skipped
    skip: No
    tags: [tutorials]
    run: hostname

The first test skip will be ignored by buildtest because skip: true is defined while unskipped will be processed as usual.

Note

YAML and JSON have different representation for boolean. For json schema valid values are true and false see https://json-schema.org/understanding-json-schema/reference/boolean.html however YAML has many more representation for boolean see https://yaml.org/type/bool.html. You may use any of the YAML boolean, however it’s best to stick with json schema values true and false.

Here is an example build, notice message [skip] test is skipped during the build stage

$ buildtest build -b tutorials/skip_tests.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-15773998-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2022/01/14 16:19:45                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest                                             │
│ buildtest version:  0.12.0                                                   │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/envs/devel/bin/python3                                                    │
│ python version:     3.7.12                                                   │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/buildtest/settings/config.yml                             │
│ Test Directory:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/var/tests                                                 │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest build -b tutorials/skip_tests.yml           │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                   ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ║
╚══════════════════════════════════════════════════════════════════════════════╝
────────────────────────────── Parsing Buildspecs ──────────────────────────────
skip: skipping test due to 'skip' property.
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutor
ials/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          ┃ description      ┃ buildspecs        ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ unskipped/2af97e6 │ generic.local.bas │ This test is not │ /home/docs/checko │
│ c                 │ h                 │ skipped          │ uts/readthedocs.o │
│                   │                   │                  │ rg/user_builds/bu │
│                   │                   │                  │ ildtest/checkouts │
│                   │                   │                  │ /devel/tutorials/ │
│                   │                   │                  │ skip_tests.yml    │
└───────────────────┴───────────────────┴──────────────────┴───────────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
unskipped/2af97e6c: Creating test directory: /home/docs/checkouts/readthedocs.or
g/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/skip_tests/
unskipped/2af97e6c
unskipped/2af97e6c: Creating the stage directory: /home/docs/checkouts/readthedo
cs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/skip_t
ests/unskipped/2af97e6c/stage
unskipped/2af97e6c: Writing build script: /home/docs/checkouts/readthedocs.org/u
ser_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/skip_tests/uns
kipped/2af97e6c/unskipped_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
______________________________
Launching test: unskipped/2af97e6c
unskipped/2af97e6c: Running Test via command: bash --norc --noprofile -eo 
pipefail unskipped_build.sh
unskipped/2af97e6c: Test completed with returncode: 0
unskipped/2af97e6c: Test completed in 0.008031 seconds
unskipped/2af97e6c: Writing output file -  /home/docs/checkouts/readthedocs.org/
user_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/skip_tests/un
skipped/2af97e6c/unskipped.out
unskipped/2af97e6c: Writing error file - /home/docs/checkouts/readthedocs.org/us
er_builds/buildtest/checkouts/devel/var/tests/generic.local.bash/skip_tests/unsk
ipped/2af97e6c/unskipped.err
                                  Test Summary                                  
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃              ┃              ┃        ┃ Checks        ┃            ┃          ┃
┃              ┃              ┃        ┃ (ReturnCode,  ┃            ┃          ┃
┃              ┃              ┃        ┃ Regex,        ┃            ┃          ┃
┃ Builder      ┃ executor     ┃ status ┃ Runtime)      ┃ ReturnCode ┃ Runtime  ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ unskipped/2a │ generic.loc… │ PASS   │ N/A N/A N/A   │ 0          │ 0.008031 │
│ f97e6c       │              │        │               │            │          │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘



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/buildt
est/checkouts/devel/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/logs/buildtest_7mi94uv0.log

Defining Metrics

buildtest provides a method to define test metrics in the buildspecs which can be used to store arbitrary content from the output/error file into named metric. A metric is defined using the metrics property where each element under the metrics property is the name of the metric which must be a unique name. A metric can apply regular expression on stdout, stderr like in this example below. The metrics are captured in the test report which can be queried via buildtest report or buildtest inspect. Shown below is an example where we define two metrics named hpcg_rating and hpcg_state.

version: "1.0"
buildspecs:
  metric_regex_example:
    executor: generic.local.sh
    type: script
    description: capture result metric from output
    run: echo "HPCG result is VALID with a GFLOP/s rating of=63.6515"
    tags: tutorials
    metrics:
      hpcg_rating:
        regex:
          exp: 'rating of=(\d+\.\d+)$'
          stream: stdout

      hpcg_state:
        regex:
          exp: '(VALID)'
          stream: stdout

The metrics will not impact behavior of test, it will only impact the test report. By default a metric will be an empty dictionary if there is no metrics property. If we fail to match a regular expression, the metric will be defined as an empty string.

Note

If your regular expression contains an escape character \ you must surround your string in single quotes ' as pose to double quotes "

Let’s build this test.

$ buildtest build -b tutorials/metrics_regex.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-15773998-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2022/01/14 16:19:45                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest                                             │
│ buildtest version:  0.12.0                                                   │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/envs/devel/bin/python3                                                    │
│ python version:     3.7.12                                                   │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/buildtest/settings/config.yml                             │
│ Test Directory:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/var/tests                                                 │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest build -b tutorials/metrics_regex.yml        │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                   ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ║
╚══════════════════════════════════════════════════════════════════════════════╝
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutor
ials/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         ┃ description       ┃ buildspecs        ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ metric_regex_exam │ generic.local.sh │ capture result    │ /home/docs/checko │
│ ple/9ddec71c      │                  │ metric from       │ uts/readthedocs.o │
│                   │                  │ output            │ rg/user_builds/bu │
│                   │                  │                   │ ildtest/checkouts │
│                   │                  │                   │ /devel/tutorials/ │
│                   │                  │                   │ metrics_regex.yml │
└───────────────────┴──────────────────┴───────────────────┴───────────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
metric_regex_example/9ddec71c: Creating test directory: /home/docs/checkouts/rea
dthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/me
trics_regex/metric_regex_example/9ddec71c
metric_regex_example/9ddec71c: Creating the stage directory: /home/docs/checkout
s/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.
sh/metrics_regex/metric_regex_example/9ddec71c/stage
metric_regex_example/9ddec71c: Writing build script: /home/docs/checkouts/readth
edocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/metri
cs_regex/metric_regex_example/9ddec71c/metric_regex_example_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
______________________________
Launching test: metric_regex_example/9ddec71c
metric_regex_example/9ddec71c: Running Test via command: sh --norc --noprofile 
-eo pipefail metric_regex_example_build.sh
metric_regex_example/9ddec71c: Test completed with returncode: 2
metric_regex_example/9ddec71c: Test completed in 0.003871 seconds
metric_regex_example/9ddec71c: Writing output file -  /home/docs/checkouts/readt
hedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/metr
ics_regex/metric_regex_example/9ddec71c/metric_regex_example.out
metric_regex_example/9ddec71c: Writing error file - /home/docs/checkouts/readthe
docs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/metric
s_regex/metric_regex_example/9ddec71c/metric_regex_example.err
                                  Test Summary                                  
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃              ┃              ┃        ┃ Checks        ┃            ┃          ┃
┃              ┃              ┃        ┃ (ReturnCode,  ┃            ┃          ┃
┃              ┃              ┃        ┃ Regex,        ┃            ┃          ┃
┃ Builder      ┃ executor     ┃ status ┃ Runtime)      ┃ ReturnCode ┃ Runtime  ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ metric_regex │ generic.loc… │ FAIL   │ N/A N/A N/A   │ 2          │ 0.003871 │
│ _example/9dd │              │        │               │            │          │
│ ec71c        │              │        │               │            │          │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘



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/buildt
est/checkouts/devel/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/logs/buildtest_49wmqksy.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
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                            s/devel/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.

version: "1.0"
buildspecs:
  metric_variable_assignment:
    executor: generic.local.sh
    type: script
    description: capture result metric based on variables and environment variable
    vars:
      GFLOPS: "63.6515"
    env:
      FOO: BAR
    run: |
      echo $GFLOPS
      echo $FOO
    tags: tutorials
    metrics:
       gflops:
         vars: "GFLOPS"
       foo:
         env: "FOO"

Now let’s build the test.

$ buildtest build -b tutorials/metrics_variable.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-15773998-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2022/01/14 16:19:46                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest                                             │
│ buildtest version:  0.12.0                                                   │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/envs/devel/bin/python3                                                    │
│ python version:     3.7.12                                                   │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/buildtest/settings/config.yml                             │
│ Test Directory:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/var/tests                                                 │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest build -b tutorials/metrics_variable.yml     │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                   ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ║
╚══════════════════════════════════════════════════════════════════════════════╝
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutor
ials/metrics_variable.yml: VALID
Total builder objects created: 1
Total compiler builder: 0
Total script builder: 1
Total spack builder: 0
                             Script Builder Details                             
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ Builder           ┃ Executor         ┃ description       ┃ buildspecs        ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ metric_variable_a │ generic.local.sh │ capture result    │ /home/docs/checko │
│ ssignment/651e669 │                  │ metric based on   │ uts/readthedocs.o │
│ 5                 │                  │ variables and     │ rg/user_builds/bu │
│                   │                  │ environment       │ ildtest/checkouts │
│                   │                  │ variable          │ /devel/tutorials/ │
│                   │                  │                   │ metrics_variable. │
│                   │                  │                   │ yml               │
└───────────────────┴──────────────────┴───────────────────┴───────────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
metric_variable_assignment/651e6695: Creating test directory: /home/docs/checkou
ts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local
.sh/metrics_variable/metric_variable_assignment/651e6695
metric_variable_assignment/651e6695: Creating the stage directory: /home/docs/ch
eckouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.
local.sh/metrics_variable/metric_variable_assignment/651e6695/stage
metric_variable_assignment/651e6695: Writing build script: /home/docs/checkouts/
readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh
/metrics_variable/metric_variable_assignment/651e6695/metric_variable_assignment
_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
______________________________
Launching test: metric_variable_assignment/651e6695
metric_variable_assignment/651e6695: Running Test via command: sh --norc 
--noprofile -eo pipefail metric_variable_assignment_build.sh
metric_variable_assignment/651e6695: Test completed with returncode: 2
metric_variable_assignment/651e6695: Test completed in 0.00393 seconds
metric_variable_assignment/651e6695: Writing output file -  /home/docs/checkouts
/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.s
h/metrics_variable/metric_variable_assignment/651e6695/metric_variable_assignmen
t.out
metric_variable_assignment/651e6695: Writing error file - /home/docs/checkouts/r
eadthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.sh/
metrics_variable/metric_variable_assignment/651e6695/metric_variable_assignment.
err
                                  Test Summary                                  
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┓
┃               ┃              ┃        ┃ Checks        ┃            ┃         ┃
┃               ┃              ┃        ┃ (ReturnCode,  ┃            ┃         ┃
┃               ┃              ┃        ┃ Regex,        ┃            ┃         ┃
┃ Builder       ┃ executor     ┃ status ┃ Runtime)      ┃ ReturnCode ┃ Runtime ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━┩
│ metric_variab │ generic.loc… │ FAIL   │ N/A N/A N/A   │ 2          │ 0.00393 │
│ le_assignment │              │        │               │            │         │
│ /651e6695     │              │        │               │            │         │
└───────────────┴──────────────┴────────┴───────────────┴────────────┴─────────┘



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/buildt
est/checkouts/devel/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/logs/buildtest_z9lu_fly.log

Now if we query the previous test, we will see the two metrics gflops and foo are captured in the test.

$ buildtest report --filter buildspec=tutorials/metrics_variable.yml --format name,metrics
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                            s/devel/var/report.json                             
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ name                                     ┃ metrics                           ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ metric_variable_assignment               │ gflops=63.6515,foo=BAR            │
└──────────────────────────────────────────┴───────────────────────────────────┘

You can also define metrics with the compiler schema which works slightly different when it comes to variable and environment assignment. Since you can define vars and env in defaults or config section. Let’s take a look at this next example where we compile an openmp code that will use the OMP_NUM_THREADS environment as the metric that is assigned to name openmp_threads. Since we have defined OMP_NUM_THREADS under the defaults and config section we will use the environment variable that corresponds to each compiler.

version: "1.0"
buildspecs:
  metrics_variable_compiler:
    type: compiler
    description: define metrics with compiler schema
    executor: generic.local.bash
    tags: [tutorials, compile]
    source: "src/hello_omp.c"
    compilers:
      name: ["^(builtin_gcc|gcc)"]
      default:
        gcc:
          cflags: -fopenmp
          env:
            OMP_NUM_THREADS: 4
      config:
        builtin_gcc:
          env:
            OMP_NUM_THREADS: 1
        gcc_6.5.0:
          env:
            OMP_NUM_THREADS: 2

    metrics:
      openmp_threads:
        env: "OMP_NUM_THREADS"

Note

This test uses a custom site configuration that defines gcc multiple compilers.

Let’s build this test as follows

$ buildtest -c config/laptop.yml build -b tutorials/compilers/metrics_openmp.yml


User:  siddiq90
Hostname:  DOE-7086392.local
Platform:  Darwin
Current Time:  2021/07/24 00:14:33
buildtest path: /Users/siddiq90/Documents/GitHubDesktop/buildtest/bin/buildtest
buildtest version:  0.10.0
python path: /Users/siddiq90/.local/share/virtualenvs/buildtest-KLOcDrW0/bin/python
python version:  3.7.3
Test Directory:  /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests
Configuration File:  /Users/siddiq90/Documents/GitHubDesktop/buildtest/config/laptop.yml
Command: /Users/siddiq90/Documents/GitHubDesktop/buildtest/bin/buildtest -c config/laptop.yml build -b tutorials/compilers/metrics_openmp.yml

+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+

+------------------------------------------------------------------------------------------+
| Discovered Buildspecs                                                                    |
+==========================================================================================+
| /Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/compilers/metrics_openmp.yml |
+------------------------------------------------------------------------------------------+
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1

+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+

 schemafile                | validstate   | buildspec
---------------------------+--------------+------------------------------------------------------------------------------------------
 compiler-v1.0.schema.json | True         | /Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/compilers/metrics_openmp.yml



name                       description
-------------------------  -----------------------------------
metrics_variable_compiler  define metrics with compiler schema
metrics_variable_compiler  define metrics with compiler schema
metrics_variable_compiler  define metrics with compiler schema

+----------------------+
| Stage: Building Test |
+----------------------+





 name                      | id       | type     | executor           | tags                     | compiler           | testpath
---------------------------+----------+----------+--------------------+--------------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------
 metrics_variable_compiler | e45976b8 | compiler | generic.local.bash | ['tutorials', 'compile'] | builtin_gcc        | /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/metrics_openmp/metrics_variable_compiler/11/metrics_variable_compiler_build.sh
 metrics_variable_compiler | 8bc71f19 | compiler | generic.local.bash | ['tutorials', 'compile'] | gcc/9.3.0-n7p74fd  | /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/metrics_openmp/metrics_variable_compiler/12/metrics_variable_compiler_build.sh
 metrics_variable_compiler | 7127eb46 | compiler | generic.local.bash | ['tutorials', 'compile'] | gcc/10.2.0-37fmsw7 | /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/metrics_openmp/metrics_variable_compiler/13/metrics_variable_compiler_build.sh

+---------------------+
| Stage: Running Test |
+---------------------+

 name                      | id       | executor           | status   |   returncode
---------------------------+----------+--------------------+----------+--------------
 metrics_variable_compiler | e45976b8 | generic.local.bash | FAIL     |          127
 metrics_variable_compiler | 8bc71f19 | generic.local.bash | PASS     |            0
 metrics_variable_compiler | 7127eb46 | generic.local.bash | PASS     |            0

+----------------------+
| Stage: Test Summary  |
+----------------------+

Passed Tests: 2/3 Percentage: 66.667%
Failed Tests: 1/3 Percentage: 33.333%


Writing Logfile to: /Users/siddiq90/buildtest/buildtest_0a04808e.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log -  /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest.log

Now if we filter the results, notice that builtin_gcc got metrics openmp_threads=1 since that is the value set under the builtin_gcc compiler instance under the config section. The gcc/9.3.0-n7p74fd compiler got value of 2 because we have an entry defined under the config section while gcc/10.2.0-37fmsw7 compiler got the value of 4 from the default section that is inherited for all gcc compilers.

$ buildtest report --filter buildspec=tutorials/compilers/metrics_openmp.yml --format name,compiler,metrics
Reading report file: /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/report.json

+---------------------------+--------------------+------------------+
| name                      | compiler           | metrics          |
+===========================+====================+==================+
| metrics_variable_compiler | builtin_gcc        | openmp_threads=1 |
+---------------------------+--------------------+------------------+
| metrics_variable_compiler | gcc/9.3.0-n7p74fd  | openmp_threads=2 |
+---------------------------+--------------------+------------------+
| metrics_variable_compiler | gcc/10.2.0-37fmsw7 | openmp_threads=4 |
+---------------------------+--------------------+------------------+

Running test across multiple executors

The executor property can support regular expression to search for compatible executors, this can be used if you want to run a test across multiple executors. In buildtest, we use re.fullmatch with the input pattern defined by executor property against a list of available executors defined in configuration file. You can retrieve a list of executors by running buildtest config executors.

In example below we will run this test on generic.local.bash and generic.local.sh executor based on the regular expression.

version: "1.0"
buildspecs:
  executor_regex_script_schema:
    type: script
    executor: 'generic.local.(bash|sh)'
    description: regular expression test with executor using script schema
    tags: [tutorials]
    run: date

If we build this test, notice that there are two tests, one for each executor.

$ buildtest build -b tutorials/executor_regex_script.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-15773998-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2022/01/14 16:19:47                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest                                             │
│ buildtest version:  0.12.0                                                   │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/envs/devel/bin/python3                                                    │
│ python version:     3.7.12                                                   │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/buildtest/settings/config.yml                             │
│ Test Directory:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/var/tests                                                 │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest build -b                                    │
│ tutorials/executor_regex_script.yml                                          │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                   ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ║
╚══════════════════════════════════════════════════════════════════════════════╝
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutor
ials/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          ┃ description      ┃ buildspecs        ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ executor_regex_sc │ generic.local.bas │ regular          │ /home/docs/checko │
│ ript_schema/7024a │ h                 │ expression test  │ uts/readthedocs.o │
│ 1b7               │                   │ with executor    │ rg/user_builds/bu │
│                   │                   │ using script     │ ildtest/checkouts │
│                   │                   │ schema           │ /devel/tutorials/ │
│                   │                   │                  │ executor_regex_sc │
│                   │                   │                  │ ript.yml          │
├───────────────────┼───────────────────┼──────────────────┼───────────────────┤
│ executor_regex_sc │ generic.local.sh  │ regular          │ /home/docs/checko │
│ ript_schema/702ab │                   │ expression test  │ uts/readthedocs.o │
│ a2b               │                   │ with executor    │ rg/user_builds/bu │
│                   │                   │ using script     │ ildtest/checkouts │
│                   │                   │ schema           │ /devel/tutorials/ │
│                   │                   │                  │ executor_regex_sc │
│                   │                   │                  │ ript.yml          │
└───────────────────┴───────────────────┴──────────────────┴───────────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
executor_regex_script_schema/7024a1b7: Creating test directory: /home/docs/check
outs/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.loc
al.bash/executor_regex_script/executor_regex_script_schema/7024a1b7
executor_regex_script_schema/7024a1b7: Creating the stage directory: /home/docs/
checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generi
c.local.bash/executor_regex_script/executor_regex_script_schema/7024a1b7/stage
executor_regex_script_schema/7024a1b7: Writing build script: /home/docs/checkout
s/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.
bash/executor_regex_script/executor_regex_script_schema/7024a1b7/executor_regex_
script_schema_build.sh
executor_regex_script_schema/702aba2b: Creating test directory: /home/docs/check
outs/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.loc
al.sh/executor_regex_script/executor_regex_script_schema/702aba2b
executor_regex_script_schema/702aba2b: Creating the stage directory: /home/docs/
checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generi
c.local.sh/executor_regex_script/executor_regex_script_schema/702aba2b/stage
executor_regex_script_schema/702aba2b: Writing build script: /home/docs/checkout
s/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.
sh/executor_regex_script/executor_regex_script_schema/702aba2b/executor_regex_sc
ript_schema_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
______________________________
Launching test: executor_regex_script_schema/7024a1b7
______________________________
Launching test: executor_regex_script_schema/702aba2b
executor_regex_script_schema/702aba2b: Running Test via command: sh --norc 
--noprofile -eo pipefail executor_regex_script_schema_build.sh
executor_regex_script_schema/7024a1b7: Running Test via command: bash --norc 
--noprofile -eo pipefail executor_regex_script_schema_build.sh
executor_regex_script_schema/702aba2b: Test completed with returncode: 2
executor_regex_script_schema/702aba2b: Test completed in 0.005476 seconds
executor_regex_script_schema/702aba2b: Writing output file -  /home/docs/checkou
ts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local
.sh/executor_regex_script/executor_regex_script_schema/702aba2b/executor_regex_s
cript_schema.out
executor_regex_script_schema/702aba2b: Writing error file - /home/docs/checkouts
/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.s
h/executor_regex_script/executor_regex_script_schema/702aba2b/executor_regex_scr
ipt_schema.err
executor_regex_script_schema/7024a1b7: Test completed with returncode: 0
executor_regex_script_schema/7024a1b7: Test completed in 0.018337 seconds
executor_regex_script_schema/7024a1b7: Writing output file -  /home/docs/checkou
ts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local
.bash/executor_regex_script/executor_regex_script_schema/7024a1b7/executor_regex
_script_schema.out
executor_regex_script_schema/7024a1b7: Writing error file - /home/docs/checkouts
/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.b
ash/executor_regex_script/executor_regex_script_schema/7024a1b7/executor_regex_s
cript_schema.err
                                  Test Summary                                  
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃              ┃              ┃        ┃ Checks        ┃            ┃          ┃
┃              ┃              ┃        ┃ (ReturnCode,  ┃            ┃          ┃
┃              ┃              ┃        ┃ Regex,        ┃            ┃          ┃
┃ Builder      ┃ executor     ┃ status ┃ Runtime)      ┃ ReturnCode ┃ Runtime  ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ executor_reg │ generic.loc… │ PASS   │ N/A N/A N/A   │ 0          │ 0.018337 │
│ ex_script_sc │              │        │               │            │          │
│ hema/7024a1b │              │        │               │            │          │
│ 7            │              │        │               │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ executor_reg │ generic.loc… │ FAIL   │ N/A N/A N/A   │ 2          │ 0.005476 │
│ ex_script_sc │              │        │               │            │          │
│ hema/702aba2 │              │        │               │            │          │
│ b            │              │        │               │            │          │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘



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/buildt
est/checkouts/devel/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/logs/buildtest_hp8p66nm.log

Multiple Executors

Note

This feature is in active development

Note

This feature is compatible with type: script and type: spack.

The executors property can be used to define executor specific configuration for each test, currently this field can be used with vars, env , scheduler directives: sbatch, bsub, pbs, cobalt and cray burst buffer/data warp. The executors field is a JSON object that expects name of executor followed by property set per executor. In this next example, we define variables X, Y and environment SHELL based on executors generic.local.sh and generic.local.bash.

version: "1.0"
buildspecs:
  executors_vars_env_declaration:
    type: script
    executor: 'generic.local.(bash|sh)'
    description: Declaring env and vars by executors section
    tags: [tutorials]
    run: |
      echo "X:" $X
      echo "Y:" $Y
      echo $SHELL

    executors:
      generic.local.bash:
        vars:
          X: 1
          Y: 3
        env:
          SHELL: bash
      generic.local.sh:
        vars:
          X: 2
          Y: 4
        env:
          SHELL: sh

Let’s build this test.

$ buildtest build -b tutorials/script/multiple_executors.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-15773998-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2022/01/14 16:19:48                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest                                             │
│ buildtest version:  0.12.0                                                   │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/envs/devel/bin/python3                                                    │
│ python version:     3.7.12                                                   │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/buildtest/settings/config.yml                             │
│ Test Directory:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/var/tests                                                 │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest build -b                                    │
│ tutorials/script/multiple_executors.yml                                      │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                   ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ║
╚══════════════════════════════════════════════════════════════════════════════╝
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutor
ials/script/multiple_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          ┃ description      ┃ buildspecs        ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ executors_vars_en │ generic.local.bas │ Declaring env    │ /home/docs/checko │
│ v_declaration/904 │ h                 │ and vars by      │ uts/readthedocs.o │
│ 1ba0e             │                   │ executors        │ rg/user_builds/bu │
│                   │                   │ section          │ ildtest/checkouts │
│                   │                   │                  │ /devel/tutorials/ │
│                   │                   │                  │ script/multiple_e │
│                   │                   │                  │ xecutors.yml      │
├───────────────────┼───────────────────┼──────────────────┼───────────────────┤
│ executors_vars_en │ generic.local.sh  │ Declaring env    │ /home/docs/checko │
│ v_declaration/77c │                   │ and vars by      │ uts/readthedocs.o │
│ 14466             │                   │ executors        │ rg/user_builds/bu │
│                   │                   │ section          │ ildtest/checkouts │
│                   │                   │                  │ /devel/tutorials/ │
│                   │                   │                  │ script/multiple_e │
│                   │                   │                  │ xecutors.yml      │
└───────────────────┴───────────────────┴──────────────────┴───────────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
executors_vars_env_declaration/9041ba0e: Creating test directory: /home/docs/che
ckouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.l
ocal.bash/multiple_executors/executors_vars_env_declaration/9041ba0e
executors_vars_env_declaration/9041ba0e: Creating the stage directory: /home/doc
s/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/gene
ric.local.bash/multiple_executors/executors_vars_env_declaration/9041ba0e/stage
executors_vars_env_declaration/9041ba0e: Writing build script: /home/docs/checko
uts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.loca
l.bash/multiple_executors/executors_vars_env_declaration/9041ba0e/executors_vars
_env_declaration_build.sh
executors_vars_env_declaration/77c14466: Creating test directory: /home/docs/che
ckouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.l
ocal.sh/multiple_executors/executors_vars_env_declaration/77c14466
executors_vars_env_declaration/77c14466: Creating the stage directory: /home/doc
s/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/gene
ric.local.sh/multiple_executors/executors_vars_env_declaration/77c14466/stage
executors_vars_env_declaration/77c14466: Writing build script: /home/docs/checko
uts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.loca
l.sh/multiple_executors/executors_vars_env_declaration/77c14466/executors_vars_e
nv_declaration_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
______________________________
Launching test: executors_vars_env_declaration/9041ba0e
______________________________
Launching test: executors_vars_env_declaration/77c14466
executors_vars_env_declaration/77c14466: Running Test via command: sh --norc 
--noprofile -eo pipefail executors_vars_env_declaration_build.sh
executors_vars_env_declaration/9041ba0e: Running Test via command: bash --norc 
--noprofile -eo pipefail executors_vars_env_declaration_build.sh
executors_vars_env_declaration/77c14466: Test completed with returncode: 2
executors_vars_env_declaration/77c14466: Test completed in 0.008954 seconds
executors_vars_env_declaration/77c14466: Writing output file -  /home/docs/check
outs/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.loc
al.sh/multiple_executors/executors_vars_env_declaration/77c14466/executors_vars_
env_declaration.out
executors_vars_env_declaration/77c14466: Writing error file - /home/docs/checkou
ts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local
.sh/multiple_executors/executors_vars_env_declaration/77c14466/executors_vars_en
v_declaration.err
executors_vars_env_declaration/9041ba0e: Test completed with returncode: 0
executors_vars_env_declaration/9041ba0e: Test completed in 0.020409 seconds
executors_vars_env_declaration/9041ba0e: Writing output file -  /home/docs/check
outs/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.loc
al.bash/multiple_executors/executors_vars_env_declaration/9041ba0e/executors_var
s_env_declaration.out
executors_vars_env_declaration/9041ba0e: Writing error file - /home/docs/checkou
ts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local
.bash/multiple_executors/executors_vars_env_declaration/9041ba0e/executors_vars_
env_declaration.err
                                  Test Summary                                  
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃              ┃              ┃        ┃ Checks        ┃            ┃          ┃
┃              ┃              ┃        ┃ (ReturnCode,  ┃            ┃          ┃
┃              ┃              ┃        ┃ Regex,        ┃            ┃          ┃
┃ Builder      ┃ executor     ┃ status ┃ Runtime)      ┃ ReturnCode ┃ Runtime  ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ executors_va │ generic.loc… │ PASS   │ N/A N/A N/A   │ 0          │ 0.020409 │
│ rs_env_decla │              │        │               │            │          │
│ ration/9041b │              │        │               │            │          │
│ a0e          │              │        │               │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ executors_va │ generic.loc… │ FAIL   │ N/A N/A N/A   │ 2          │ 0.008954 │
│ rs_env_decla │              │        │               │            │          │
│ ration/77c14 │              │        │               │            │          │
│ 466          │              │        │               │            │          │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘



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/buildt
est/checkouts/devel/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/logs/buildtest_uk632q2s.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/
───── executors_vars_env_declaration/9041ba0e-0ded-4572-ae74-d129564b9a9c ──────
Executor: generic.local.bash
Description: Declaring env and vars by executors section
State: PASS
Returncode: 0
Runtime: 0.020409 sec
Starttime: 2022/01/14 16:19:48
Endtime: 2022/01/14 16:19:48
Command: bash --norc --noprofile -eo pipefail 
executors_vars_env_declaration_build.sh
Test Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/devel/var/tests/generic.local.bash/multiple_executors/executors_vars_env_decla
ration/9041ba0e/executors_vars_env_declaration.sh
Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkou
ts/devel/var/tests/generic.local.bash/multiple_executors/executors_vars_env_decl
aration/9041ba0e/executors_vars_env_declaration_build.sh
Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/devel/var/tests/generic.local.bash/multiple_executors/executors_vars_env_decla
ration/9041ba0e/executors_vars_env_declaration.out
Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts
/devel/var/tests/generic.local.bash/multiple_executors/executors_vars_env_declar
ation/9041ba0e/executors_vars_env_declaration.err
Log File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/d
evel/var/logs/buildtest_uk632q2s.log
─ Test File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/check… ─
   1 #!/usr/bin/bash                                                            
   2 # Declare environment variables                                            
   3 export SHELL=bash                                                          
   4                                                                            
   5                                                                            
   6 # Declare environment variables                                            
   7 export X=1                                                                 
   8 export Y=3                                                                 
   9                                                                            
  10                                                                            
  11 # Content of run section                                                   
  12 echo "X:" $X                                                               
  13 echo "Y:" $Y                                                               
  14 echo $SHELL                                                                
  15                                                                            
───── executors_vars_env_declaration/77c14466-2bb1-4cc0-96ee-0b3d8448c185 ──────
Executor: generic.local.sh
Description: Declaring env and vars by executors section
State: FAIL
Returncode: 2
Runtime: 0.008954 sec
Starttime: 2022/01/14 16:19:48
Endtime: 2022/01/14 16:19:48
Command: sh --norc --noprofile -eo pipefail 
executors_vars_env_declaration_build.sh
Test Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/devel/var/tests/generic.local.sh/multiple_executors/executors_vars_env_declara
tion/77c14466/executors_vars_env_declaration.sh
Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkou
ts/devel/var/tests/generic.local.sh/multiple_executors/executors_vars_env_declar
ation/77c14466/executors_vars_env_declaration_build.sh
Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/devel/var/tests/generic.local.sh/multiple_executors/executors_vars_env_declara
tion/77c14466/executors_vars_env_declaration.out
Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts
/devel/var/tests/generic.local.sh/multiple_executors/executors_vars_env_declarat
ion/77c14466/executors_vars_env_declaration.err
Log File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/d
evel/var/logs/buildtest_uk632q2s.log
─ Test File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/check… ─
   1 #!/usr/bin/bash                                                            
   2 # Declare environment variables                                            
   3 export SHELL=sh                                                            
   4                                                                            
   5                                                                            
   6 # Declare environment variables                                            
   7 export X=2                                                                 
   8 export Y=4                                                                 
   9                                                                            
  10                                                                            
  11 # Content of run section                                                   
  12 echo "X:" $X                                                               
  13 echo "Y:" $Y                                                               
  14 echo $SHELL                                                                
  15

Scheduler Directives

We can also define scheduler directives based on executor type, in this example we define sbatch property per executor type. Note that sbatch property in the executors section will override the sbatch property defined in the top-level file otherwise it will use the default.

version: "1.0"
buildspecs:
  executors_sbatch_declaration:
    type: script
    executor: 'generic.local.(bash|sh)'
    description: Declaring env and vars by executors section
    tags: [tutorials]
    run: hostname
    sbatch: ["-N 4"]
    executors:
      generic.local.bash:
        sbatch: ["-n 4", "-N 1", "-t 30"]
      generic.local.sh:
        sbatch: ["-n 8", "-N 1", "-t 60"]
$ buildtest build -b tutorials/script/executor_scheduler.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-15773998-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2022/01/14 16:19:49                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest                                             │
│ buildtest version:  0.12.0                                                   │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/envs/devel/bin/python3                                                    │
│ python version:     3.7.12                                                   │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/buildtest/settings/config.yml                             │
│ Test Directory:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/var/tests                                                 │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest build -b                                    │
│ tutorials/script/executor_scheduler.yml                                      │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                   ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ║
╚══════════════════════════════════════════════════════════════════════════════╝
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutor
ials/script/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          ┃ description      ┃ buildspecs        ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ executors_sbatch_ │ generic.local.bas │ Declaring env    │ /home/docs/checko │
│ declaration/2552e │ h                 │ and vars by      │ uts/readthedocs.o │
│ 63e               │                   │ executors        │ rg/user_builds/bu │
│                   │                   │ section          │ ildtest/checkouts │
│                   │                   │                  │ /devel/tutorials/ │
│                   │                   │                  │ script/executor_s │
│                   │                   │                  │ cheduler.yml      │
├───────────────────┼───────────────────┼──────────────────┼───────────────────┤
│ executors_sbatch_ │ generic.local.sh  │ Declaring env    │ /home/docs/checko │
│ declaration/e4a72 │                   │ and vars by      │ uts/readthedocs.o │
│ e5b               │                   │ executors        │ rg/user_builds/bu │
│                   │                   │ section          │ ildtest/checkouts │
│                   │                   │                  │ /devel/tutorials/ │
│                   │                   │                  │ script/executor_s │
│                   │                   │                  │ cheduler.yml      │
└───────────────────┴───────────────────┴──────────────────┴───────────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
executors_sbatch_declaration/2552e63e: Creating test directory: /home/docs/check
outs/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.loc
al.bash/executor_scheduler/executors_sbatch_declaration/2552e63e
executors_sbatch_declaration/2552e63e: Creating the stage directory: /home/docs/
checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generi
c.local.bash/executor_scheduler/executors_sbatch_declaration/2552e63e/stage
executors_sbatch_declaration/2552e63e: Writing build script: /home/docs/checkout
s/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.
bash/executor_scheduler/executors_sbatch_declaration/2552e63e/executors_sbatch_d
eclaration_build.sh
executors_sbatch_declaration/e4a72e5b: Creating test directory: /home/docs/check
outs/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.loc
al.sh/executor_scheduler/executors_sbatch_declaration/e4a72e5b
executors_sbatch_declaration/e4a72e5b: Creating the stage directory: /home/docs/
checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generi
c.local.sh/executor_scheduler/executors_sbatch_declaration/e4a72e5b/stage
executors_sbatch_declaration/e4a72e5b: Writing build script: /home/docs/checkout
s/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.
sh/executor_scheduler/executors_sbatch_declaration/e4a72e5b/executors_sbatch_dec
laration_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
______________________________
Launching test: executors_sbatch_declaration/2552e63e
______________________________
Launching test: executors_sbatch_declaration/e4a72e5b
executors_sbatch_declaration/e4a72e5b: Running Test via command: sh --norc 
--noprofile -eo pipefail executors_sbatch_declaration_build.sh
executors_sbatch_declaration/2552e63e: Running Test via command: bash --norc 
--noprofile -eo pipefail executors_sbatch_declaration_build.sh
executors_sbatch_declaration/e4a72e5b: Test completed with returncode: 2
executors_sbatch_declaration/e4a72e5b: Test completed in 0.005216 seconds
executors_sbatch_declaration/e4a72e5b: Writing output file -  /home/docs/checkou
ts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local
.sh/executor_scheduler/executors_sbatch_declaration/e4a72e5b/executors_sbatch_de
claration.out
executors_sbatch_declaration/e4a72e5b: Writing error file - /home/docs/checkouts
/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.s
h/executor_scheduler/executors_sbatch_declaration/e4a72e5b/executors_sbatch_decl
aration.err
executors_sbatch_declaration/2552e63e: Test completed with returncode: 0
executors_sbatch_declaration/2552e63e: Test completed in 0.018873 seconds
executors_sbatch_declaration/2552e63e: Writing output file -  /home/docs/checkou
ts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local
.bash/executor_scheduler/executors_sbatch_declaration/2552e63e/executors_sbatch_
declaration.out
executors_sbatch_declaration/2552e63e: Writing error file - /home/docs/checkouts
/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local.b
ash/executor_scheduler/executors_sbatch_declaration/2552e63e/executors_sbatch_de
claration.err
                                  Test Summary                                  
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃              ┃              ┃        ┃ Checks        ┃            ┃          ┃
┃              ┃              ┃        ┃ (ReturnCode,  ┃            ┃          ┃
┃              ┃              ┃        ┃ Regex,        ┃            ┃          ┃
┃ Builder      ┃ executor     ┃ status ┃ Runtime)      ┃ ReturnCode ┃ Runtime  ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ executors_sb │ generic.loc… │ PASS   │ N/A N/A N/A   │ 0          │ 0.018873 │
│ atch_declara │              │        │               │            │          │
│ tion/2552e63 │              │        │               │            │          │
│ e            │              │        │               │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ executors_sb │ generic.loc… │ FAIL   │ N/A N/A N/A   │ 2          │ 0.005216 │
│ atch_declara │              │        │               │            │          │
│ tion/e4a72e5 │              │        │               │            │          │
│ b            │              │        │               │            │          │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘



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/buildt
est/checkouts/devel/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/logs/buildtest_kupzw4iy.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/
────── executors_sbatch_declaration/2552e63e-ebf0-4f99-9ffa-6d6471a38278 ───────
Executor: generic.local.bash
Description: Declaring env and vars by executors section
State: PASS
Returncode: 0
Runtime: 0.018873 sec
Starttime: 2022/01/14 16:19:49
Endtime: 2022/01/14 16:19:49
Command: bash --norc --noprofile -eo pipefail 
executors_sbatch_declaration_build.sh
Test Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/devel/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declara
tion/2552e63e/executors_sbatch_declaration.sh
Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkou
ts/devel/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declar
ation/2552e63e/executors_sbatch_declaration_build.sh
Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/devel/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declara
tion/2552e63e/executors_sbatch_declaration.out
Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts
/devel/var/tests/generic.local.bash/executor_scheduler/executors_sbatch_declarat
ion/2552e63e/executors_sbatch_declaration.err
Log File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/d
evel/var/logs/buildtest_kupzw4iy.log
─ Test File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/check… ─
   1 #!/usr/bin/bash                                                            
   2 ####### START OF SCHEDULER DIRECTIVES #######                              
   3 #SBATCH -n 4                                                               
   4 #SBATCH -N 1                                                               
   5 #SBATCH -t 30                                                              
   6 #SBATCH --job-name=executors_sbatch_declaration                            
   7 #SBATCH --output=executors_sbatch_declaration.out                          
   8 #SBATCH --error=executors_sbatch_declaration.err                           
   9 ####### END OF SCHEDULER DIRECTIVES   #######                              
  10 # Content of run section                                                   
  11 hostname                                                                   
────── executors_sbatch_declaration/e4a72e5b-d109-4eca-ad84-b6e095d790fb ───────
Executor: generic.local.sh
Description: Declaring env and vars by executors section
State: FAIL
Returncode: 2
Runtime: 0.005216 sec
Starttime: 2022/01/14 16:19:49
Endtime: 2022/01/14 16:19:49
Command: sh --norc --noprofile -eo pipefail 
executors_sbatch_declaration_build.sh
Test Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/devel/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declarati
on/e4a72e5b/executors_sbatch_declaration.sh
Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkou
ts/devel/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declarat
ion/e4a72e5b/executors_sbatch_declaration_build.sh
Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/devel/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declarati
on/e4a72e5b/executors_sbatch_declaration.out
Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts
/devel/var/tests/generic.local.sh/executor_scheduler/executors_sbatch_declaratio
n/e4a72e5b/executors_sbatch_declaration.err
Log File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/d
evel/var/logs/buildtest_kupzw4iy.log
─ Test File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/check… ─
   1 #!/usr/bin/bash                                                            
   2 ####### START OF SCHEDULER DIRECTIVES #######                              
   3 #SBATCH -n 8                                                               
   4 #SBATCH -N 1                                                               
   5 #SBATCH -t 60                                                              
   6 #SBATCH --job-name=executors_sbatch_declaration                            
   7 #SBATCH --output=executors_sbatch_declaration.out                          
   8 #SBATCH --error=executors_sbatch_declaration.err                           
   9 ####### END OF SCHEDULER DIRECTIVES   #######                              
  10 # Content of run section                                                   
  11 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.

version: "1.0"
buildspecs:
  create_burst_buffer_multiple_executors:
    type: script
    executor: "generic.local.(sh|bash)"
    sbatch: ["-N 1", "-t 10", "-C knl"]
    description: Create a burst buffer for multiple executors
    tags: [jobs]
    executors:
      generic.local.sh:
        BB:
          - create_persistent name=buffer1 capacity=10GB access_mode=striped type=scratch
        DW:
          - persistentdw name=buffer1
      generic.local.bash:
        BB:
        - create_persistent name=buffer2 capacity=10GB access_mode=striped type=scratch
        DW:
          - persistentdw name=buffer2
    run: hostname

Status and Metrics Field

The status and metrics field are supported in executors which can be defined within the named executor. In this next example, we will define generic.local.bash to match test based on returncode 0 or 2 and define metrics named firstname that is assigned the value from variable FIRST. The second test using generic.local.sh will match returncode of 1 and define a metrics named lastname that will store the value defined by variable LAST.

version: "1.0"
buildspecs:
  status_returncode_by_executors:
    type: script
    executor: "generic.local.(bash|sh)"
    description: define status and metrics per executor type.
    tags: [tutorials]
    vars:
      FIRST: Michael
      LAST: Jackson
    run: echo "my name is $FIRST $LAST"

    executors:
      generic.local.bash:
        status:
          returncode: [0, 2]
        metrics:
          firstname:
            vars: "FIRST"
      generic.local.sh:
        status:
          returncode: 1
        metrics:
          lastname:
            vars: "LAST"

Now let’s run this test and we will see the test using generic.local.sh will fail because we have a returncode mismatch even though both tests got a 0 returncode as its actual value.

$ buildtest build -b tutorials/script/status_by_executors.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-15773998-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2022/01/14 16:19:50                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest                                             │
│ buildtest version:  0.12.0                                                   │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/envs/devel/bin/python3                                                    │
│ python version:     3.7.12                                                   │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/buildtest/settings/config.yml                             │
│ Test Directory:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/var/tests                                                 │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest build -b                                    │
│ tutorials/script/status_by_executors.yml                                     │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                   ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ║
╚══════════════════════════════════════════════════════════════════════════════╝
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutor
ials/script/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          ┃ description      ┃ buildspecs        ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ status_returncode │ generic.local.bas │ define status    │ /home/docs/checko │
│ _by_executors/51b │ h                 │ and metrics per  │ uts/readthedocs.o │
│ c4e23             │                   │ executor type.   │ rg/user_builds/bu │
│                   │                   │                  │ ildtest/checkouts │
│                   │                   │                  │ /devel/tutorials/ │
│                   │                   │                  │ script/status_by_ │
│                   │                   │                  │ executors.yml     │
├───────────────────┼───────────────────┼──────────────────┼───────────────────┤
│ status_returncode │ generic.local.sh  │ define status    │ /home/docs/checko │
│ _by_executors/6b7 │                   │ and metrics per  │ uts/readthedocs.o │
│ d83e9             │                   │ executor type.   │ rg/user_builds/bu │
│                   │                   │                  │ ildtest/checkouts │
│                   │                   │                  │ /devel/tutorials/ │
│                   │                   │                  │ script/status_by_ │
│                   │                   │                  │ executors.yml     │
└───────────────────┴───────────────────┴──────────────────┴───────────────────┘
──────────────────────────────── Building Test ─────────────────────────────────
status_returncode_by_executors/51bc4e23: Creating test directory: /home/docs/che
ckouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.l
ocal.bash/status_by_executors/status_returncode_by_executors/51bc4e23
status_returncode_by_executors/51bc4e23: Creating the stage directory: /home/doc
s/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/gene
ric.local.bash/status_by_executors/status_returncode_by_executors/51bc4e23/stage
status_returncode_by_executors/51bc4e23: Writing build script: /home/docs/checko
uts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.loca
l.bash/status_by_executors/status_returncode_by_executors/51bc4e23/status_return
code_by_executors_build.sh
status_returncode_by_executors/6b7d83e9: Creating test directory: /home/docs/che
ckouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.l
ocal.sh/status_by_executors/status_returncode_by_executors/6b7d83e9
status_returncode_by_executors/6b7d83e9: Creating the stage directory: /home/doc
s/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/gene
ric.local.sh/status_by_executors/status_returncode_by_executors/6b7d83e9/stage
status_returncode_by_executors/6b7d83e9: Writing build script: /home/docs/checko
uts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.loca
l.sh/status_by_executors/status_returncode_by_executors/6b7d83e9/status_returnco
de_by_executors_build.sh
──────────────────────────────── Running Tests ─────────────────────────────────
______________________________
Launching test: status_returncode_by_executors/51bc4e23
______________________________
Launching test: status_returncode_by_executors/6b7d83e9
status_returncode_by_executors/51bc4e23: Running Test via command: bash --norc 
--noprofile -eo pipefail status_returncode_by_executors_build.sh
status_returncode_by_executors/6b7d83e9: Running Test via command: sh --norc 
--noprofile -eo pipefail status_returncode_by_executors_build.sh
status_returncode_by_executors/6b7d83e9: Test completed with returncode: 2
status_returncode_by_executors/6b7d83e9: Test completed in 0.005519 seconds
status_returncode_by_executors/6b7d83e9: Writing output file -  /home/docs/check
outs/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.loc
al.sh/status_by_executors/status_returncode_by_executors/6b7d83e9/status_returnc
ode_by_executors.out
status_returncode_by_executors/6b7d83e9: Writing error file - /home/docs/checkou
ts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local
.sh/status_by_executors/status_returncode_by_executors/6b7d83e9/status_returncod
e_by_executors.err
status_returncode_by_executors/6b7d83e9: Checking returncode - 2 is matched in 
list [1]
status_returncode_by_executors/51bc4e23: Test completed with returncode: 0
status_returncode_by_executors/51bc4e23: Test completed in 0.018005 seconds
status_returncode_by_executors/51bc4e23: Writing output file -  /home/docs/check
outs/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.loc
al.bash/status_by_executors/status_returncode_by_executors/51bc4e23/status_retur
ncode_by_executors.out
status_returncode_by_executors/51bc4e23: Writing error file - /home/docs/checkou
ts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/tests/generic.local
.bash/status_by_executors/status_returncode_by_executors/51bc4e23/status_returnc
ode_by_executors.err
status_returncode_by_executors/51bc4e23: Checking returncode - 0 is matched in 
list [0, 2]
                                  Test Summary                                  
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃              ┃              ┃        ┃ Checks        ┃            ┃          ┃
┃              ┃              ┃        ┃ (ReturnCode,  ┃            ┃          ┃
┃              ┃              ┃        ┃ Regex,        ┃            ┃          ┃
┃ Builder      ┃ executor     ┃ status ┃ Runtime)      ┃ ReturnCode ┃ Runtime  ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ status_retur │ generic.loc… │ PASS   │ True False    │ 0          │ 0.018005 │
│ ncode_by_exe │              │        │ False         │            │          │
│ cutors/51bc4 │              │        │               │            │          │
│ e23          │              │        │               │            │          │
├──────────────┼──────────────┼────────┼───────────────┼────────────┼──────────┤
│ status_retur │ generic.loc… │ FAIL   │ False False   │ 2          │ 0.005519 │
│ ncode_by_exe │              │        │ False         │            │          │
│ cutors/6b7d8 │              │        │               │            │          │
│ 3e9          │              │        │               │            │          │
└──────────────┴──────────────┴────────┴───────────────┴────────────┴──────────┘



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/buildt
est/checkouts/devel/var/report.json
Writing Logfile to: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/var/logs/buildtest__4nqfu34.log

Now let’s see the test results by inspecting the metrics field using buildtest report. We see one test has the metrics name firstname=Michael and second test has lastname=Jackson.

$ buildtest report --format id,name,metrics --filter name=status_returncode_by_executors
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                            s/devel/var/report.json                             
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ id          ┃ name                                   ┃ metrics               ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ 51bc4e23    │ status_returncode_by_executors         │ firstname=Michael     │
├─────────────┼────────────────────────────────────────┼───────────────────────┤
│ 6b7d83e9    │ status_returncode_by_executors         │ lastname=Jackson      │
└─────────────┴────────────────────────────────────────┴───────────────────────┘

run_only

The run_only property is used for running test given a specific condition has met. For example, you may want a test to run only if its particular system (Linux, Darwin), operating system, scheduler, etc…

run_only - user

buildtest will skip test if any of the conditions are not met. Let’s take an example in this buildspec we define a test name run_only_as_root that requires root user to run test. The run_only is a property of key/value pairs and user is one of the field. buildtest will only build & run test if current user matches user field. We detect current user using $USER and match with input field user. buildtest will skip test if there is no match.

version: "1.0"
buildspecs:
  run_only_as_root:
    description: "This test will only run if current user is root"
    executor: generic.local.bash
    type: script
    tags: ["tutorials"]
    run_only:
      user: root
    run: echo $USER

Now if we run this test we see buildtest will skip test run_only_as_root because current user is not root.

$ buildtest build -b tutorials/root_user.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-15773998-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2022/01/14 16:19:51                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest                                             │
│ buildtest version:  0.12.0                                                   │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/envs/devel/bin/python3                                                    │
│ python version:     3.7.12                                                   │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/buildtest/settings/config.yml                             │
│ Test Directory:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/var/tests                                                 │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest build -b tutorials/root_user.yml            │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                   ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ║
╚══════════════════════════════════════════════════════════════════════════════╝
────────────────────────────── Parsing Buildspecs ──────────────────────────────
[run_only_as_root][/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutorials/root_user.yml]: test is skipped because this test is expected to run as user: root but detected user: None.
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutor
ials/root_user.yml: VALID
                            Buildspecs Filtered out                             
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Buildspecs                                                                   ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… │
└──────────────────────────────────────────────────────────────────────────────┘

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/devel/var/buildtest.log

run_only - platform

Similarly, we can run test if it matches target platform. In this example we have two tests run_only_platform_darwin and run_only_platform_linux that are run if target platform is Darwin or Linux. This is configured using platform field which is a property of run_only object. buildtest will match target platform using platform.system() with field platform, if there is no match buildtest will skip test. In this test, we define a python shell using shell: python and run platform.system(). We expect the output of each test to have Darwin and Linux which we match with stdout using regular expression.

version: "1.0"
buildspecs:
  run_only_platform_darwin:
    description: "This test will only run if target platform is Darwin"
    executor: generic.local.bash
    type: script
    tags: ["tutorials"]
    run_only:
      platform: Darwin
    shell: python
    run: |
      import platform
      print(platform.system())
    status:
      regex:
        stream: stdout
        exp: "^Darwin$"

  run_only_platform_linux:
    description: "This test will only run if target platform is Linux"
    executor: generic.local.bash
    type: script
    tags: ["tutorials"]
    run_only:
      platform: Linux
    shell: python
    run: |
      import platform
      print(platform.system())
    status:
      regex:
        stream: stdout
        exp: "^Linux"

This test was ran on a MacOS (Darwin) so we expect test run_only_platform_linux to be skipped.

 bash-3.2$ buildtest build -b tutorials/run_only_platform.yml
╭───────────────────────────────────────────────── buildtest summary ──────────────────────────────────────────────────╮
│                                                                                                                      │
│ User:               siddiq90                                                                                         │
│ Hostname:           DOE-7086392.local                                                                                │
│ Platform:           Darwin                                                                                           │
│ Current Time:       2021/12/07 22:51:45                                                                              │
│ buildtest path:     /Users/siddiq90/Documents/GitHubDesktop/buildtest/bin/buildtest                                  │
│ buildtest version:  0.11.0                                                                                           │
│ python path:        /Users/siddiq90/.local/share/virtualenvs/buildtest-KLOcDrW0/bin/python                           │
│ python version:     3.7.3                                                                                            │
│ Configuration File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest/settings/config.yml                  │
│ Test Directory:     /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests                                      │
│ Command:            /Users/siddiq90/Documents/GitHubDesktop/buildtest/bin/buildtest build -b                         │
│ tutorials/run_only_platform.yml                                                                                      │
│                                                                                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
───────────────────────────────────────────────  Discovering Buildspecs ────────────────────────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                                Discovered buildspecs
╔═══════════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                        ║
╟───────────────────────────────────────────────────────────────────────────────────╢
║ /Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/run_only_platform.yml ║
╚═══════════════════════════════════════════════════════════════════════════════════╝
────────────────────────────────────────────────── Parsing Buildspecs ──────────────────────────────────────────────────
[run_only_platform_linux][/Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/run_only_platform.yml]: test is skipped because this test is expected to run on platform: Linux but detected platform: Darwin.
Valid Buildspecs: 1
Invalid Buildspecs: 0
/Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/run_only_platform.yml: VALID


Total builder objects created: 1


                                                    Builder Details
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Builder                        ┃ Executor           ┃ description                   ┃ buildspecs                     ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ run_only_platform_darwin/9bc44 │ generic.local.bash │ This test will only run if    │ /Users/siddiq90/Documents/GitH │
│ 2db                            │                    │ target platform is Darwin     │ ubDesktop/buildtest/tutorials/ │
│                                │                    │                               │ run_only_platform.yml          │
└────────────────────────────────┴────────────────────┴───────────────────────────────┴────────────────────────────────┘
──────────────────────────────────────────────────── Building Test ─────────────────────────────────────────────────────
[22:51:45] run_only_platform_darwin/9bc442db: Creating test directory: /Users/siddiq90/Documents/GitHubDeskt base.py:421
           op/buildtest/var/tests/generic.local.bash/run_only_platform/run_only_platform_darwin/9bc442db
           run_only_platform_darwin/9bc442db: Creating the stage directory: /Users/siddiq90/Documents/GitHub base.py:432
           Desktop/buildtest/var/tests/generic.local.bash/run_only_platform/run_only_platform_darwin/9bc442d
           b/stage
           run_only_platform_darwin/9bc442db: Writing build script: /Users/siddiq90/Documents/GitHubDesktop/ base.py:550
           buildtest/var/tests/generic.local.bash/run_only_platform/run_only_platform_darwin/9bc442db/run_on
           ly_platform_darwin_build.sh
──────────────────────────────────────────────────── Running Tests ─────────────────────────────────────────────────────
______________________________
Launching test: run_only_platform_darwin/9bc442db
run_only_platform_darwin/9bc442db: Running Test via command: bash --norc --noprofile -eo pipefail
run_only_platform_darwin_build.sh
run_only_platform_darwin/9bc442db: Test completed with returncode: 0
run_only_platform_darwin/9bc442db: Test completed in 0.281197 seconds
run_only_platform_darwin/9bc442db: Writing output file -  /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/ge
neric.local.bash/run_only_platform/run_only_platform_darwin/9bc442db/run_only_platform_darwin.out
run_only_platform_darwin/9bc442db: Writing error file - /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/gene
ric.local.bash/run_only_platform/run_only_platform_darwin/9bc442db/run_only_platform_darwin.err
run_only_platform_darwin/9bc442db: performing regular expression - '^Darwin$' on file: /Users/siddiq90/Documents/GitHubD
esktop/buildtest/var/tests/generic.local.bash/run_only_platform/run_only_platform_darwin/9bc442db/run_only_platform_darw
in.out
run_only_platform_darwin/9bc442db: Regular Expression Match - Success!
                                                      Test Summary
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Builder                       ┃ executor           ┃ status ┃ Checks (ReturnCode, Regex,     ┃ ReturnCode ┃ Runtime  ┃
┃                               ┃                    ┃        ┃ Runtime)                       ┃            ┃          ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ run_only_platform_darwin/9bc4 │ generic.local.bash │ PASS   │ False True False               │ 0          │ 0.281197 │
│ 42db                          │                    │        │                                │            │          │
└───────────────────────────────┴────────────────────┴────────┴────────────────────────────────┴────────────┴──────────┘



Passed Tests: 1/1 Percentage: 100.000%
Failed Tests: 0/1 Percentage: 0.000%


Writing Logfile to: /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/logs/buildtest_1edlfmz_.log

run_only - scheduler

buildtest can run test if a particular scheduler is available. In this example, we introduce a new field scheduler that is part of run_only property. This field expects one of the following values: [lsf, slurm, cobalt, pbs] and buildtest will check if target system supports detects the scheduler. In this example we require lsf scheduler because this test runs bmgroup which is a LSF binary.

Note

buildtest assumes scheduler binaries are available in $PATH, if no scheduler is found buildtest sets this to an empty list

version: "1.0"
buildspecs:
  show_host_groups:
    type: script
    executor: generic.local.bash
    description: Show information about host groups using bmgroup
    tags: lsf
    run_only:
      scheduler: lsf
    run: bmgroup

If we build this test on a target system without LSF notice that buildtest skips test show_host_groups.

$ buildtest build -b general_tests/sched/lsf/bmgroups.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-15773998-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2022/01/14 16:19:51                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest                                             │
│ buildtest version:  0.12.0                                                   │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/envs/devel/bin/python3                                                    │
│ python version:     3.7.12                                                   │
│ Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/buildtest/settings/config.yml                             │
│ Test Directory:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/var/tests                                                 │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ st/checkouts/devel/bin/buildtest build -b                                    │
│ general_tests/sched/lsf/bmgroups.yml                                         │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                   ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ║
╚══════════════════════════════════════════════════════════════════════════════╝
────────────────────────────── Parsing Buildspecs ──────────────────────────────
[show_host_groups][/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/general_tests/sched/lsf/bmgroups.yml]: test is skipped because ['run_only']['scheduler'] got value: lsf but detected scheduler: [].
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/gener
al_tests/sched/lsf/bmgroups.yml: VALID
                            Buildspecs Filtered out                             
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Buildspecs                                                                   ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… │
└──────────────────────────────────────────────────────────────────────────────┘

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/devel/var/buildtest.log

run_only - linux_distro

buildtest can run test if it matches a Linux distro, this is configured using linux_distro field that is a list of Linux distros that is returned via distro.id(). In this example, we run test only if host distro is darwin.

version: "1.0"
buildspecs:
  run_only_macos_distro:
    type: script
    executor: generic.local.bash
    description: "Run test only if distro is darwin."
    tags: [mac]
    run_only:
      linux_distro:
        - darwin
    run: uname
    status:
      regex:
        stream: stdout
        exp: "^Darwin$"

  run_only_linux_distro:
    type: script
    executor: generic.local.bash
    description: "Run test only if distro is CentOS."
    tags: [mac]
    run_only:
      linux_distro:
        - centos
    run: uname

This test will run successfully because this was ran on a Mac OS (darwin) system.

bash-3.2$ buildtest build -b tutorials/run_only_distro.yml
╭───────────────────────────────────────────────── buildtest summary ──────────────────────────────────────────────────╮
│                                                                                                                      │
│ User:               siddiq90                                                                                         │
│ Hostname:           DOE-7086392.local                                                                                │
│ Platform:           Darwin                                                                                           │
│ Current Time:       2021/12/07 22:50:22                                                                              │
│ buildtest path:     /Users/siddiq90/Documents/GitHubDesktop/buildtest/bin/buildtest                                  │
│ buildtest version:  0.11.0                                                                                           │
│ python path:        /Users/siddiq90/.local/share/virtualenvs/buildtest-KLOcDrW0/bin/python                           │
│ python version:     3.7.3                                                                                            │
│ Configuration File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest/settings/config.yml                  │
│ Test Directory:     /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests                                      │
│ Command:            /Users/siddiq90/Documents/GitHubDesktop/buildtest/bin/buildtest build -b                         │
│ tutorials/run_only_distro.yml                                                                                        │
│                                                                                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
───────────────────────────────────────────────  Discovering Buildspecs ────────────────────────────────────────────────
Discovered Buildspecs:  1
Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
                               Discovered buildspecs
╔═════════════════════════════════════════════════════════════════════════════════╗
║ Buildspecs                                                                      ║
╟─────────────────────────────────────────────────────────────────────────────────╢
║ /Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/run_only_distro.yml ║
╚═════════════════════════════════════════════════════════════════════════════════╝
────────────────────────────────────────────────── Parsing Buildspecs ──────────────────────────────────────────────────
[run_only_linux_distro][/Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/run_only_distro.yml]: test is skipped because this test is expected to run on linux distro: ['centos'] but detected linux distro: darwin.
Valid Buildspecs: 1
Invalid Buildspecs: 0
/Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials/run_only_distro.yml: VALID


Total builder objects created: 1


                                                    Builder Details
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Builder                        ┃ Executor           ┃ description                    ┃ buildspecs                    ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ run_only_macos_distro/6c9a59e7 │ generic.local.bash │ Run test only if distro is     │ /Users/siddiq90/Documents/Git │
│                                │                    │ darwin.                        │ HubDesktop/buildtest/tutorial │
│                                │                    │                                │ s/run_only_distro.yml         │
└────────────────────────────────┴────────────────────┴────────────────────────────────┴───────────────────────────────┘
──────────────────────────────────────────────────── Building Test ─────────────────────────────────────────────────────
[22:50:22] run_only_macos_distro/6c9a59e7: Creating test directory: /Users/siddiq90/Documents/GitHubDesktop/ base.py:421
           buildtest/var/tests/generic.local.bash/run_only_distro/run_only_macos_distro/6c9a59e7
           run_only_macos_distro/6c9a59e7: Creating the stage directory: /Users/siddiq90/Documents/GitHubDes base.py:432
           ktop/buildtest/var/tests/generic.local.bash/run_only_distro/run_only_macos_distro/6c9a59e7/stage
           run_only_macos_distro/6c9a59e7: Writing build script: /Users/siddiq90/Documents/GitHubDesktop/bui base.py:550
           ldtest/var/tests/generic.local.bash/run_only_distro/run_only_macos_distro/6c9a59e7/run_only_macos
           _distro_build.sh
──────────────────────────────────────────────────── Running Tests ─────────────────────────────────────────────────────
______________________________
Launching test: run_only_macos_distro/6c9a59e7
run_only_macos_distro/6c9a59e7: Running Test via command: bash --norc --noprofile -eo pipefail
run_only_macos_distro_build.sh
run_only_macos_distro/6c9a59e7: Test completed with returncode: 0
run_only_macos_distro/6c9a59e7: Test completed in 0.104622 seconds
run_only_macos_distro/6c9a59e7: Writing output file -  /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/gener
ic.local.bash/run_only_distro/run_only_macos_distro/6c9a59e7/run_only_macos_distro.out
run_only_macos_distro/6c9a59e7: Writing error file - /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic
.local.bash/run_only_distro/run_only_macos_distro/6c9a59e7/run_only_macos_distro.err
run_only_macos_distro/6c9a59e7: performing regular expression - '^Darwin$' on file: /Users/siddiq90/Documents/GitHubDesk
top/buildtest/var/tests/generic.local.bash/run_only_distro/run_only_macos_distro/6c9a59e7/run_only_macos_distro.out
run_only_macos_distro/6c9a59e7: Regular Expression Match - Success!
                                                      Test Summary
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Builder                        ┃ executor           ┃ status ┃ Checks (ReturnCode, Regex,    ┃ ReturnCode ┃ Runtime  ┃
┃                                ┃                    ┃        ┃ Runtime)                      ┃            ┃          ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ run_only_macos_distro/6c9a59e7 │ generic.local.bash │ PASS   │ False True False              │ 0          │ 0.104622 │
└────────────────────────────────┴────────────────────┴────────┴───────────────────────────────┴────────────┴──────────┘



Passed Tests: 1/1 Percentage: 100.000%
Failed Tests: 0/1 Percentage: 0.000%


Writing Logfile to: /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/logs/buildtest_h1bbn_wt.log