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 which will provide an overview of buildtest commands.

$ buildtest help

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> -x <file> -x <dir>       Exclude files and directory when building buildspecs
buildtest build -t pass  -t python                          Build buildspecs by tagname 'pass' and 'python'
buildtest build -e <executor1> -e <executor2>               Building buildspecs by executor
buildtest build -b <file> -t <tagname1> -e <executor1>      Building buildspecs with file, directory, tags, and executors
buildtest build -b tutorials  --filter type=script          Build all tests in directory 'tutorials' and filter tests by type='script'
buildtest build -b tutorials  --filter tags=pass            Build all tests in directory 'tutorials' and filter tests by tags='pass'
buildtest build -b tutorials  --filter maintainers=@bob     Build all tests in directory 'tutorials' and filter tests by maintainers='@bob'
buildtest -c config.yml build -b <file>                     Use buildtest configuration file 'config.yml' 
buildtest build -b <file> --rebuild 5                       Rebuild a test 5 times
buildtest build -b <file> --testdir /tmp                    Write tests in /tmp

View Test Report 

Command                                                     Description

buildtest report                                            Display all tests results
buildtest report --filter returncode=0                      Filter test results by returncode=0
buildtest report --filter state=PASS,tags=python            Filter test by multiple filter fields.
buildtest report --filter buildspec=tutorials/vars.yml      Filter report by buildspec file 'tutorials/vars.yml
buildtest report --format name,state,buildspec              Format report table by field 'name', 'state', 'buildspec'
buildtest report --helpfilter                               List all filter fields
buildtest report --helpformat                               List all format fields
buildtest report --oldest                                   Retrieve oldest record for all tests 
buildtest report --latest                                   Retrieve latest record for all tests 
buildtest report -r <report-file>                           Specify alternate report file to display test results
buildtest report list                                       List all report files
buildtest report clear                                      Remove content of report file

Inspecting a Test

Command                                                     Description

buildtest inspect name hello                                Display all tests results
buildtest inspect name foo bar                              Display record of test name 'foo' and 'bar'
buildtest inspect list                                      Display all test names and ids
buildtest inspect id <ID>                                   Display record of test by unique identifer
buildtest query -o hello                                    Display content of output file for test name 'hello'
buildtest query -e hello                                    Display content of error file for test name 'hello'
buildtest query -d -o -e first hello foo  bar               Display first record of tests 'hello', 'foo', 'bar' and show output and error file 

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 --rebuild              Discover buildspecs in /tmp and 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 --tags                             List all unique tags from cache
buildtest buildspec find --executors                        List all unique executors from cache
buildtest buildspec find --maintainers                      List all maintainers from cache
buildtest buildspec find --maintainers-by-buildspecs        Show breakdown of all buildspecs by maintainer names.
buildtest buildspec find --filter type=script,tags=pass     Filter buildspec cache based on type=script and  tags='pass'
buildtest buildspec find --filter buildspec=<path>          Filter cache by buildspec file    
buildtest buildspec find --format name,description          Format table columns by field: 'name' and 'description 
buildtest buildspec find --group-by-tags                    Group tests by tag name
buildtest buildspec find --group-by-executor                Group tests by executor name            
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 --error                    Show invalid buildspecs with error messages

Buildspec Summary

Command                                                     Description

buildtest buildspec summary                                 Show summary of buildspec cache file 
Validate buildspecs
Command                                                     Description

buildtest buildspec validate -b <file>                      Validate a buildspec with JSON Schema 
buildtest buildspec validate -b /tmp/ -x /tmp/network       Validate all buildspecs in directory /tmp but exclude /tmp/network
buildtest buildspec validate -t python -t mac               Validate all buildspecs for tagname 'python' and 'mac'
buildtest buildspec validate -e generic.local.bash          Validate all buildspecs for executor 'generic.local.bash'
Build History

Command                                                     Description

buildtest history list                                      List all build history files 
buildtest history query 0                                   Query content of history build identifier '0' 
buildtest history query 0 --log                             Open logfile for build identifier '0'

Buildtest Configuration 

Command                                                     Description

buildtest config view                                       View content of configuration file
buildtest config validate                                   Validate configuration file with JSON schema
buildtest config executors                                  List all executors from configuration file
buildtest config systems                                    List all available system entries in configuration file
buildtest -c /tmp/config.yml config validate                Validate configuration file /tmp/config.yml

CDASH Support

Command                                                     Description

buildtest cdash upload DEMO                                 Upload all tests to cdash with build name 'DEMO' 
buildtest cdash upload 'DAILY_CHECK' --report result.json   Upload all tests from report file result.json with build name 'DAILY_CHECK'
buildtest cdash upload --site laptop DEMO                   Upload tests to CDASH with site named called 'laptop' 
buildtest cdash upload -r /tmp/nightly.json nightly         Upload tests from /tmp/nightly.json to CDASH with buildname 'nightly'
buildtest cdash view                                        Open CDASH project in web-browser
buildtest cdash view --url <url>                            Open CDASH project in web-browser with a specified url

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 Getting Started and Join Slack Channel.





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 Spack Schema. 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