Summary of buildtest


HPC System and Software Stack are tightly integrated with underlying architecture which makes them highly sensitive to changes in system such as OS, kernel, driver, or vendor updates. We need a testing framework to automate acceptance testing of an HPC system so that HPC Support Teams can increase confidence of their HPC system throughout the system lifecycle.


There are many build automations tools for compiling source code into binary code, the most used tool is the make utility found in most Linux systems. Build scripts like configure, cmake and autoconf can generate files used by make for installing the software. Makefile is a file used by make program that shows how to compile and link a program which is the basis for building a software package. One can invoke make test which will run the target named test in Makefile that dictates how tests are compiled and run. Makefile is hard to interpret and requires in-depth experience with shell-scripting and strong understanding of how package is built and tested. Note that package maintainers must provide the source files, headers, and additional libraries to test the software and make test simply the test compilation and execution. Tools like configure, cmake and autoconf are insufficient for testing because HPC software stack consist of applications packaged in many formats and some are make-incompatible.

We wanted a framework that hides the complexity for compiling source code and provide an easy markup language to define test configuration to create the test. This leads to buildtest, which is a testing framework that generates test-scripts using YAML that is validated with JSON Schemas. YAML was picked given its ease-of-use and it lowers the barrier for writing tests.

Inception of buildtest

buildtest was founded by Shahzeb Siddiqui in 2017 when he was at Pfizer tasked for testing software stack for a data center migration.

Shahzeb was tasked with testing the software ecosystem by focusing on the most important application due to time constraints. During this period, several dozen test scripts were developed in shell-script that targeted core HPC tools such as compilers, MPI, R, Python, etc. A single master script was used to run all the tests which led to buildtest.

Preview of buildtest

You can run buildtest help followed by name of command and it will provide an overview of the buildtest.

Building Test

$ buildtest help build
                              Building buildspecs                               
┃ Command                              ┃ Description                           ┃
│ buildtest build -b <file>            │ Build a single buildspec file         │
│ buildtest build -b <dir>             │ Build all buildspecs recursively in a │
│                                      │ given directory                       │
│ buildtest build -b <file> -b <dir>   │ Build buildspecs by file and          │
│                                      │ directory                             │
│ buildtest build -b <file> -b <dir>   │ Exclude files and directory when      │
│ -x <file> -x <dir>                   │ building buildspecs                   │
│ buildtest build -t pass -t python    │ Build buildspecs by tagname 'pass'    │
│                                      │ and 'python'                          │
│ buildtest build -e <executor1> -e    │ Building buildspecs by executor       │
│ <executor2>                          │                                       │
│ buildtest build -b <file> -t         │ Building buildspecs with file,        │
│ <tagname1> -e <executor1>            │ directory, tags, and executors        │
│ buildtest build -b tutorials         │ Build all tests in directory          │
│ --filter type=script                 │ 'tutorials' and filter tests by       │
│                                      │ type='script'                         │
│ buildtest build -b tutorials         │ Build all tests in directory          │
│ --filter tags=pass                   │ 'tutorials' and filter tests by       │
│                                      │ tags='pass'                           │
│ buildtest build -b tutorials         │ Build all tests in directory          │
│ --filter maintainers=@bob            │ 'tutorials' and filter tests by       │
│                                      │ maintainers='@bob'                    │
│ buildtest build --helpfilter         │ Show list of filter fields used with  │
│                                      │ --filter option                       │
│ buildtest -c config.yml build -b     │ Use buildtest configuration file      │
│ <file>                               │ 'config.yml'                          │
│ buildtest build -b <file> --rebuild  │ Rebuild a test 5 times                │
│ 5                                    │                                       │
│ buildtest build -b <file> --testdir  │ Write tests in /tmp                   │
│ /tmp                                 │                                       │
│ buildtest build -b /tmp/hostname.yml │ Set Poll Interval to 10sec and Max    │
│ --maxpendtime 120 --pollinterval 10  │ Pend Time to 120 sec when submitting  │
│                                      │ batch job.                            │
│ buildtest build --rerun              │ Run last successful 'buildtest build' │
│                                      │ command                               │

Buildspec Interface

$ buildtest help buildspec
                               Finding Buildspecs                               
┃ Command                               ┃ Description                          ┃
│ buildtest buildspec find              │ Discover and validate all buildspecs │
│                                       │ and load all validated buildspecs in │
│                                       │ cache                                │
│ buildtest buildspec find --rebuild    │ Rebuild cache file                   │
│ buildtest buildspec find --root /tmp  │ Discover buildspecs in /tmp and      │
│ --rebuild                             │ rebuild buildspec cache              │
│ buildtest buildspec find --paths      │ Print all root directories for       │
│                                       │ buildspecs                           │
│ buildtest buildspec find --buildspec  │ List all available buildspecs from   │
│                                       │ cache                                │
│ buildtest buildspec find --executors  │ List all unique executors from cache │
│ buildtest buildspec find              │ List all maintainers from cache      │
│ --maintainers                         │                                      │
│ buildtest buildspec find              │ Show breakdown of all buildspecs by  │
│ --maintainers-by-buildspecs           │ maintainer names                     │
│ buildtest buildspec find --filter     │ Filter buildspec cache based on      │
│ type=script,tags=pass                 │ type=script and  tags='pass'         │
│ buildtest buildspec find --filter     │ Filter cache by buildspec file       │
│ buildspec=<path>                      │                                      │
│ buildtest buildspec find --format     │ Format table columns by field:       │
│ name,description                      │ 'name', and 'description'            │
│ buildtest buildspec find              │ Group tests by tag name              │
│ --group-by-tags                       │                                      │
│ buildtest buildspec find              │ Group tests by executor name         │
│ --group-by-executor                   │                                      │
│ buildtest buildspec find --helpfilter │ Show all filter fields               │
│ buildtest buildspec find --helpformat │ Show all format fields               │
│ buildtest buildspec find --terse      │ Display output in terse format       │
│ buildtest buildspec find invalid      │ Show invalid buildspecs              │
│ buildtest buildspec find invalid      │ Show invalid buildspecs with error   │
│ --error                               │ messages                             │
                             Validating Buildspecs                              
┃ Command                               ┃ Description                          ┃
│ buildtest buildspec validate -b       │ Validate a buildspec with JSON       │
│ <file>                                │ Schema                               │
│ buildtest buildspec validate -b /tmp/ │ Validate all buildspecs in directory │
│ -x /tmp/network                       │ /tmp but exclude /tmp/network        │
│ buildtest buildspec validate -t       │ Validate all buildspecs for tagname  │
│ python -t mac                         │ 'python' and 'mac'                   │
│ buildtest buildspec validate -e       │ Validate all buildspecs for executor │
│ generic.local.bash                    │ 'generic.local.bash'                 │
                       Additional Features of Buildspecs                        
┃ Command                               ┃ Description                          ┃
│ buildtest buildspec summary           │ Show summary of buildspec cache file │
│ buildtest buildspec show python_hello │ Show content of buildspec based on   │
│                                       │ test name 'python_hello'             │
│ buildtest buildspec edit python_hello │ Open test 'python_hello' in editor   │
│                                       │ and validate file upon closing       │
│ buildtest buildspec edit-file         │ Open file                            │
│ $BUILDTEST_ROOT/tutorials/sleep.yml   │ $BUILDTEST_ROOT/tutorials/sleep.yml  │
│                                       │ in editor and validate file upon     │
│                                       │ closing                              │

Query Report

$ buildtest help report
                              Viewing Test Report                               
┃ Command                              ┃ Description                           ┃
│ buildtest report                     │ Display all test results              │
│ buildtest report --filter            │ Filter test results by returncode=0   │
│ returncode=0                         │                                       │
│ buildtest report --filter            │ Filter test by filter fields 'state', │
│ state=PASS,tags=python               │ 'tags'.                               │
│ buildtest report --filter            │ Filter report by buildspec file       │
│ buildspec=tutorials/vars.yml         │ 'tutorials/vars.yml                   │
│ buildtest report --format            │ Format report table by field 'name',  │
│ name,state,buildspec                 │ 'state', 'buildspec'                  │
│ buildtest report --helpfilter        │ List all filter fields                │
│ buildtest report --helpformat        │ List all format fields                │
│ buildtest report --latest            │ Retrieve latest record for all tests  │
│ buildtest -r /tmp/result.json report │ Read report file /tmp/result.json and │
│                                      │ display result                        │
│ buildtest report --terse             │ Print report in terse format          │
│ buildtest report list                │ List all report files                 │
│ buildtest report clear               │ Remove content of default report file │
│ buildtest report summary             │ Show summary of test report           │

Inspect Tests

$ buildtest help inspect
                               Inspecting a test                                
┃ Command                              ┃ Description                           ┃
│ buildtest inspect list               │ Display all test names, ids, and      │
│                                      │ corresponding buildspec file          │
│ buildtest inspect list -t            │ Show output in terse format           │
│ buildtest inspect name hello         │ Display last run for test name        │
│                                      │ 'hello'                               │
│ buildtest inspect name hello/9ac     │ Display record for test 'hello/9ac'   │
│ bar/ac9                              │ and 'bar/ac9'. Will find first match  │
│                                      │ for each test ID                      │
│ buildtest inspect buildspec          │ Fetch latest runs for all tests in    │
│ tutorials/vars.yml                   │ buildspec file 'tutorials/vars.yml'   │
│ buildtest inspect query -o hello     │ Display content of output file for    │
│                                      │ test name 'hello'                     │
│ buildtest inspect query -e hello     │ Display content of error file for     │
│                                      │ test name 'hello'                     │
│ buildtest inspect query -d first -o  │ Display first record of tests 'foo',  │
│ -e foo bar                           │ 'bar', and show output and error file │
│ buildtest inspect query -o hello     │ Display all runs for tests 'foo'      │

Buildtest Configuration

$ buildtest help config
                             Configuring Buildtest                              
┃ Command                              ┃ Description                           ┃
│ buildtest config view                │ View content of configuration file    │
│ buildtest config validate            │ Validate configuration file with JSON │
│                                      │ schema                                │
│ buildtest config edit                │ Edit configuration file in your       │
│                                      │ preferred editor                      │
│ buildtest config executors           │ List all executors in flat listing    │
│                                      │ from configuration file               │
│ buildtest config executors --yaml    │ Show executor configuration in YAML   │
│                                      │ format                                │
│ buildtest config executors --json    │ Show executor configuration in JSON   │
│                                      │ format                                │
│ buildtest config executors           │ List all disabled executors           │
│ --disabled                           │                                       │
│ buildtest config executors --json    │ List all invalid executors            │
│ buildtest config systems             │ List all available system entries in  │
│                                      │ configuration file                    │
│ buildtest -c /tmp/config.yml config  │ Validate configuration file           │
│ validate                             │ /tmp/config.yml                       │
│ buildtest config compilers           │ List all compilers from configuration │
│                                      │ file in flat listing                  │
│ buildtest config compilers find      │ Detect compilers and update           │
│                                      │ configuration file                    │

Target Audience & Use Case

buildtest target audience is HPC Staff that wants to perform acceptance & regression testing of their HPC system.

buildtest is not

  • replacement for make, cmake, autoconf, ctest

  • a software build framework (easybuild, spack, nix , guix)

  • a replacement for benchmark tools or test suite from upstream package

  • a replacement for writing tests, you will need to write your tests defined by buildtest schemas, however you can copy/paste & adapt tests from other sites that are applicable to you.

Typical use-case:

  • Run your test suite during system maintenance

  • Perform daily tests for testing various system components. These tests should be short

  • Run weekly/biweekly test on medium/large workload including micro-benchmark

  • Run tests for newly installed software package typically requested by user.

If you are interested trying out buildtest check out Buildtest Tutorial and Join Slack Channel.





Mar 18th 2022


Remove version property from buildspec structure and all schema files. Add support for test dependencies using needs property. Several new options to buildtest build such as --rerun, --executor-type, --modules, --module-purge, --unload-modules. Add --pager option for several buildtest commands for PAGING output.

Jan 20th 2022


Add options --proc and --nodes to buildtest build to specify arbitrary process and node count for batch jobs. Add new commands buildtest unittests and buildtest stylecheck. Allow one to specify alternate python wrapper via environment BUILDTEST_PYTHON.

Dec 17th 2021


Make use of rich library for printing output for various buildtest commands. Add new commands such buildtest debugreport and buildtest config edit. We removed few commands including buildtest config summary, buildtest inspect id.

Sep 9th 2021


Re-implement core implementation of running and polling jobs using asynchronous job submission. In addition we added several new commands including: buildtest cd, buildtest path and buildtest path and we enable alias for sub-commands.

Aug 16th 2021


Add support for multi executor support in buildspec via executors property. Add new commands buildtest report summary for summary of report file. The buildtest buildspec show command shows content of buildspec file given a test name. The buildtest edit command can be used to edit buildspec and validate with JSON schema upon closing file. In this release, we added buildtest inspect buildspec command to view records based on buildspec file.

Jul 30th 2021


Add new commands buildtest buildspec summary, buildtest buildspec invalid to show summary of buildspec cache and invalid buildspecs. Add buildtest build --filter to filter buildspecs during build. Add --terse option for several commands including buildtest history list, buildtest report, buildtest buildspec find. Add new command buildtest inspect query for querying test records. Added support for metrics property for defining arbitrary metrics in buildspec based on environment variable, variables or regular expression on stdout/stderr

Jul 13th 2021


In this release we added spack support in buildtest by creating a new schema to write buildspecs that will generate spack commands. For more details see buildtest spack integration. We added bash completion for buildtest commands which is enabled when installing buildtest. We added a new command buildtest buildspec validate that can be used for validating buildspecs with JSON Schema.

Jun 11th 2021


Added buildtest CDASH integration using buildtest cdash to upload test results. In this release we added buildtest history command to retrieve build history and query logfiles. Add global option -c in buildtest to specify alternate configuration file.

Mar 31th 2021


Add support for PBS scheduler and reimplement buildtest inspect command

Mar 14th 2021


Introduced major change in buildtest configuration file (settings.schema.json) to define multiple HPC systems in configuration file. This lead to change in how executors are referenced in buildspec file.

Feb 22nd 2021


Change Copyright details for project to include LBNL. We added dependabot for managing dependencies, added OLCF facility pipelines for running regression test.

Jan 12th 2021


Contains major refactor to compiler-v1.0-schema.json for writing compiler test using regular expression to search for compilers that are defined in configuration file.

Nov 24st 2020


Added support for Cobalt Scheduler.

Sep 3rd 2020


Introduced JSON Schema for validating buildspec. Add support for Slurm and LSF scheduler for job submission. Add support for building buildspecs by file, directory and tagname and command line interface to schema.

Sep 11th 2018


buildtest was ported from Python 2 to 3.

Aug 20th 2017


buildtest was converted from bash to Python and project was moved into github

Feb 18th 2017


Start of project