Command Line Tutorial

For this session, we assume you have installed buildtest on your system. You can check if buildtest command is available by running:

$ buildtest --help

If you receive an error please go back and re-install buildtest.

If you are new to buildtest you can review the quick start guide to learn the basics of buildtest.

Building Test

The buildtest build command is used for running a test on your system given a buildspec file (YAML). The most common way to build a test is specifying a file path via buildtest build -b <path>. To get started, let’s build our first test by running the following.

buildtest build -b $BUILDTEST_ROOT/tutorials/hello_world.yml
$ buildtest build -b $BUILDTEST_ROOT/tutorials/hello_world.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-24186293-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2024/04/25 15:41:44                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version:  2.0                                                      │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version:     3.8.18                                                   │
│ Configuration File: /tmp/tmp0ns2hqkt/config.yml                              │
│ Test Directory:     /tmp/tmp0ns2hqkt/var/tests                               │
│ Report File:        /tmp/tmp0ns2hqkt/var/report.json                         │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec                                                                    ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/t ║
║ utorials/hello_world.yml                                                     ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ Total: 1                                                                     ║
╚══════════════════════════════════════════════════════════════════════════════╝


Total Discovered Buildspecs:  1
Total Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutorials/hello_world.yml: VALID
Total builder objects created: 1
                            Builders by type=script                             
┏━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┓
┃          ┃        ┃          ┃          ┃       ┃       ┃ descript ┃ buildsp ┃
┃ builder  ┃ type   ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ ion      ┃ ecs     ┃
┡━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━┩
│ hello_wo │ script │ generic. │ None     │ None  │ None  │ hello    │ /home/d │
│ rld/a985 │        │ local.ba │          │       │       │ world    │ ocs/che │
│ cbf9     │        │ sh       │          │       │       │ example  │ ckouts/ │
│          │        │          │          │       │       │          │ readthe │
│          │        │          │          │       │       │          │ docs.or │
│          │        │          │          │       │       │          │ g/user_ │
│          │        │          │          │       │       │          │ builds/ │
│          │        │          │          │       │       │          │ buildte │
│          │        │          │          │       │       │          │ st/chec │
│          │        │          │          │       │       │          │ kouts/d │
│          │        │          │          │       │       │          │ evel/tu │
│          │        │          │          │       │       │          │ torials │
│          │        │          │          │       │       │          │ /hello_ │
│          │        │          │          │       │       │          │ world.y │
│          │        │          │          │       │       │          │ ml      │
└──────────┴────────┴──────────┴──────────┴───────┴───────┴──────────┴─────────┘
──────────────────────────────── Building Test ─────────────────────────────────
hello_world/a985cbf9: Creating Test Directory: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/hello_world/hello_world/a985cbf9
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
hello_world/a985cbf9 does not have any dependencies adding test to queue
Builders Eligible to Run
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ Builder              ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ hello_world/a985cbf9 │
└──────────────────────┘
hello_world/a985cbf9: Current Working Directory : /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/hello_world/hello_world/a985cbf9/stage
hello_world/a985cbf9: Running Test via command: bash hello_world_build.sh
hello_world/a985cbf9: Test completed in 0.005768 seconds with returncode: 0
hello_world/a985cbf9: Writing output file -  /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/hello_world/hello_world/a985cbf9/hello_world.out
hello_world/a985cbf9: Writing error file - /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/hello_world/hello_world/a985cbf9/hello_world.err
                                Test Summary                                 
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┓
┃ builder              ┃ executor           ┃ status ┃ returncode ┃ runtime ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━┩
│ hello_world/a985cbf9 │ generic.local.bash │ PASS   │ 0          │ 0.006   │
└──────────────────────┴────────────────────┴────────┴────────────┴─────────┘



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


Adding 1 test results to report file: /tmp/tmp0ns2hqkt/var/report.json
Writing Logfile to /tmp/tmp0ns2hqkt/var/logs/buildtest_sa5twhu9.log

The -b option can be specified multiple times and it can be used with directory path. buildtest will recursively search for all .yml extensions and attempt to build all tests.

Let’s try running the following command, where we will build by file and directory.

buildtest build -b $BUILDTEST_ROOT/tutorials/hello_world.yml -b $BUILDTEST_ROOT/general_tests/configuration
$ buildtest build -b $BUILDTEST_ROOT/tutorials/hello_world.yml -b $BUILDTEST_ROOT/general_tests/configuration
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-24186293-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2024/04/25 15:41:44                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version:  2.0                                                      │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version:     3.8.18                                                   │
│ Configuration File: /tmp/tmp0ns2hqkt/config.yml                              │
│ Test Directory:     /tmp/tmp0ns2hqkt/var/tests                               │
│ Report File:        /tmp/tmp0ns2hqkt/var/report.json                         │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec                                                                    ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/t ║
║ utorials/hello_world.yml                                                     ║
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/g ║
║ eneral_tests/configuration/systemd-default-target.yml                        ║
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/g ║
║ eneral_tests/configuration/ulimits.yml                                       ║
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/g ║
║ eneral_tests/configuration/kernel_state.yml                                  ║
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/g ║
║ eneral_tests/configuration/disk_usage.yml                                    ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ Total: 5                                                                     ║
╚══════════════════════════════════════════════════════════════════════════════╝


Total Discovered Buildspecs:  5
Total Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  5
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 5
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutorials/hello_world.yml: VALID
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/general_tests/configuration/systemd-default-target.yml: VALID
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/general_tests/configuration/ulimits.yml: VALID
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/general_tests/configuration/kernel_state.yml: VALID
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/general_tests/configuration/disk_usage.yml: VALID
Total builder objects created: 10
                            Builders by type=script                             
┏━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┓
┃          ┃        ┃          ┃          ┃       ┃       ┃ descript ┃ buildsp ┃
┃ builder  ┃ type   ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ ion      ┃ ecs     ┃
┡━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━┩
│ hello_wo │ script │ generic. │ None     │ None  │ None  │ hello    │ /home/d │
│ rld/5322 │        │ local.ba │          │       │       │ world    │ ocs/che │
│ 4311     │        │ sh       │          │       │       │ example  │ ckouts/ │
│          │        │          │          │       │       │          │ readthe │
│          │        │          │          │       │       │          │ docs.or │
│          │        │          │          │       │       │          │ g/user_ │
│          │        │          │          │       │       │          │ builds/ │
│          │        │          │          │       │       │          │ buildte │
│          │        │          │          │       │       │          │ st/chec │
│          │        │          │          │       │       │          │ kouts/d │
│          │        │          │          │       │       │          │ evel/tu │
│          │        │          │          │       │       │          │ torials │
│          │        │          │          │       │       │          │ /hello_ │
│          │        │          │          │       │       │          │ world.y │
│          │        │          │          │       │       │          │ ml      │
├──────────┼────────┼──────────┼──────────┼───────┼───────┼──────────┼─────────┤
│ systemd_ │ script │ generic. │ None     │ None  │ None  │ check if │ /home/d │
│ default_ │        │ local.ba │          │       │       │ default  │ ocs/che │
│ target/5 │        │ sh       │          │       │       │ target   │ ckouts/ │
│ 3d7b468  │        │          │          │       │       │ is       │ readthe │
│          │        │          │          │       │       │ multi-us │ docs.or │
│          │        │          │          │       │       │ er.targe │ g/user_ │
│          │        │          │          │       │       │ t        │ builds/ │
│          │        │          │          │       │       │          │ buildte │
│          │        │          │          │       │       │          │ st/chec │
│          │        │          │          │       │       │          │ kouts/d │
│          │        │          │          │       │       │          │ evel/ge │
│          │        │          │          │       │       │          │ neral_t │
│          │        │          │          │       │       │          │ ests/co │
│          │        │          │          │       │       │          │ nfigura │
│          │        │          │          │       │       │          │ tion/sy │
│          │        │          │          │       │       │          │ stemd-d │
│          │        │          │          │       │       │          │ efault- │
│          │        │          │          │       │       │          │ target. │
│          │        │          │          │       │       │          │ yml     │
├──────────┼────────┼──────────┼──────────┼───────┼───────┼──────────┼─────────┤
│ ulimit_f │ script │ generic. │ None     │ None  │ None  │ Check if │ /home/d │
│ ilelock_ │        │ local.ba │          │       │       │ file     │ ocs/che │
│ unlimite │        │ sh       │          │       │       │ lock is  │ ckouts/ │
│ d/fd70c2 │        │          │          │       │       │ set to   │ readthe │
│ 10       │        │          │          │       │       │ unlimite │ docs.or │
│          │        │          │          │       │       │ d in     │ g/user_ │
│          │        │          │          │       │       │ ulimits  │ builds/ │
│          │        │          │          │       │       │          │ buildte │
│          │        │          │          │       │       │          │ st/chec │
│          │        │          │          │       │       │          │ kouts/d │
│          │        │          │          │       │       │          │ evel/ge │
│          │        │          │          │       │       │          │ neral_t │
│          │        │          │          │       │       │          │ ests/co │
│          │        │          │          │       │       │          │ nfigura │
│          │        │          │          │       │       │          │ tion/ul │
│          │        │          │          │       │       │          │ imits.y │
│          │        │          │          │       │       │          │ ml      │
├──────────┼────────┼──────────┼──────────┼───────┼───────┼──────────┼─────────┤
│ ulimit_c │ script │ generic. │ None     │ None  │ None  │ Check if │ /home/d │
│ putime_u │        │ local.ba │          │       │       │ cputime  │ ocs/che │
│ nlimited │        │ sh       │          │       │       │ is set   │ ckouts/ │
│ /8999ac1 │        │          │          │       │       │ to       │ readthe │
│ a        │        │          │          │       │       │ unlimite │ docs.or │
│          │        │          │          │       │       │ d in     │ g/user_ │
│          │        │          │          │       │       │ ulimits  │ builds/ │
│          │        │          │          │       │       │          │ buildte │
│          │        │          │          │       │       │          │ st/chec │
│          │        │          │          │       │       │          │ kouts/d │
│          │        │          │          │       │       │          │ evel/ge │
│          │        │          │          │       │       │          │ neral_t │
│          │        │          │          │       │       │          │ ests/co │
│          │        │          │          │       │       │          │ nfigura │
│          │        │          │          │       │       │          │ tion/ul │
│          │        │          │          │       │       │          │ imits.y │
│          │        │          │          │       │       │          │ ml      │
├──────────┼────────┼──────────┼──────────┼───────┼───────┼──────────┼─────────┤
│ ulimit_s │ script │ generic. │ None     │ None  │ None  │ Check if │ /home/d │
│ tacksize │        │ local.ba │          │       │       │ stack    │ ocs/che │
│ _unlimit │        │ sh       │          │       │       │ size is  │ ckouts/ │
│ ed/615e9 │        │          │          │       │       │ set to   │ readthe │
│ a3d      │        │          │          │       │       │ unlimite │ docs.or │
│          │        │          │          │       │       │ d in     │ g/user_ │
│          │        │          │          │       │       │ ulimits  │ builds/ │
│          │        │          │          │       │       │          │ buildte │
│          │        │          │          │       │       │          │ st/chec │
│          │        │          │          │       │       │          │ kouts/d │
│          │        │          │          │       │       │          │ evel/ge │
│          │        │          │          │       │       │          │ neral_t │
│          │        │          │          │       │       │          │ ests/co │
│          │        │          │          │       │       │          │ nfigura │
│          │        │          │          │       │       │          │ tion/ul │
│          │        │          │          │       │       │          │ imits.y │
│          │        │          │          │       │       │          │ ml      │
├──────────┼────────┼──────────┼──────────┼───────┼───────┼──────────┼─────────┤
│ ulimit_v │ script │ generic. │ None     │ None  │ None  │ Check    │ /home/d │
│ msize_un │        │ local.ba │          │       │       │ virtual  │ ocs/che │
│ limited/ │        │ sh       │          │       │       │ memory   │ ckouts/ │
│ 13a3573f │        │          │          │       │       │ size and │ readthe │
│          │        │          │          │       │       │ check if │ docs.or │
│          │        │          │          │       │       │ its set  │ g/user_ │
│          │        │          │          │       │       │ to       │ builds/ │
│          │        │          │          │       │       │ unlimite │ buildte │
│          │        │          │          │       │       │ d        │ st/chec │
│          │        │          │          │       │       │          │ kouts/d │
│          │        │          │          │       │       │          │ evel/ge │
│          │        │          │          │       │       │          │ neral_t │
│          │        │          │          │       │       │          │ ests/co │
│          │        │          │          │       │       │          │ nfigura │
│          │        │          │          │       │       │          │ tion/ul │
│          │        │          │          │       │       │          │ imits.y │
│          │        │          │          │       │       │          │ ml      │
├──────────┼────────┼──────────┼──────────┼───────┼───────┼──────────┼─────────┤
│ ulimit_f │ script │ generic. │ None     │ None  │ None  │ Check if │ /home/d │
│ iledescr │        │ local.ba │          │       │       │ open     │ ocs/che │
│ iptor_40 │        │ sh       │          │       │       │ file     │ ckouts/ │
│ 96/2879f │        │          │          │       │       │ descript │ readthe │
│ bd0      │        │          │          │       │       │ ors      │ docs.or │
│          │        │          │          │       │       │ limit is │ g/user_ │
│          │        │          │          │       │       │ set to   │ builds/ │
│          │        │          │          │       │       │ 4096     │ buildte │
│          │        │          │          │       │       │          │ st/chec │
│          │        │          │          │       │       │          │ kouts/d │
│          │        │          │          │       │       │          │ evel/ge │
│          │        │          │          │       │       │          │ neral_t │
│          │        │          │          │       │       │          │ ests/co │
│          │        │          │          │       │       │          │ nfigura │
│          │        │          │          │       │       │          │ tion/ul │
│          │        │          │          │       │       │          │ imits.y │
│          │        │          │          │       │       │          │ ml      │
├──────────┼────────┼──────────┼──────────┼───────┼───────┼──────────┼─────────┤
│ ulimit_m │ script │ generic. │ None     │ None  │ None  │ Check    │ /home/d │
│ ax_user_ │        │ local.ba │          │       │       │ max      │ ocs/che │
│ process_ │        │ sh       │          │       │       │ number   │ ckouts/ │
│ 2048/836 │        │          │          │       │       │ of user  │ readthe │
│ 1aa78    │        │          │          │       │       │ process  │ docs.or │
│          │        │          │          │       │       │ limit is │ g/user_ │
│          │        │          │          │       │       │ set to   │ builds/ │
│          │        │          │          │       │       │ 2048     │ buildte │
│          │        │          │          │       │       │          │ st/chec │
│          │        │          │          │       │       │          │ kouts/d │
│          │        │          │          │       │       │          │ evel/ge │
│          │        │          │          │       │       │          │ neral_t │
│          │        │          │          │       │       │          │ ests/co │
│          │        │          │          │       │       │          │ nfigura │
│          │        │          │          │       │       │          │ tion/ul │
│          │        │          │          │       │       │          │ imits.y │
│          │        │          │          │       │       │          │ ml      │
├──────────┼────────┼──────────┼──────────┼───────┼───────┼──────────┼─────────┤
│ kernel_s │ script │ generic. │ None     │ None  │ None  │ Retrieve │ /home/d │
│ wapusage │        │ local.ba │          │       │       │ Kernel   │ ocs/che │
│ /9428f47 │        │ sh       │          │       │       │ Swap     │ ckouts/ │
│ 0        │        │          │          │       │       │ Usage    │ readthe │
│          │        │          │          │       │       │          │ docs.or │
│          │        │          │          │       │       │          │ g/user_ │
│          │        │          │          │       │       │          │ builds/ │
│          │        │          │          │       │       │          │ buildte │
│          │        │          │          │       │       │          │ st/chec │
│          │        │          │          │       │       │          │ kouts/d │
│          │        │          │          │       │       │          │ evel/ge │
│          │        │          │          │       │       │          │ neral_t │
│          │        │          │          │       │       │          │ ests/co │
│          │        │          │          │       │       │          │ nfigura │
│          │        │          │          │       │       │          │ tion/ke │
│          │        │          │          │       │       │          │ rnel_st │
│          │        │          │          │       │       │          │ ate.yml │
├──────────┼────────┼──────────┼──────────┼───────┼───────┼──────────┼─────────┤
│ root_dis │ script │ generic. │ None     │ None  │ None  │ Check    │ /home/d │
│ k_usage/ │        │ local.ba │          │       │       │ root     │ ocs/che │
│ e0b58766 │        │ sh       │          │       │       │ disk     │ ckouts/ │
│          │        │          │          │       │       │ usage    │ readthe │
│          │        │          │          │       │       │ and      │ docs.or │
│          │        │          │          │       │       │ report   │ g/user_ │
│          │        │          │          │       │       │ if it    │ builds/ │
│          │        │          │          │       │       │ exceeds  │ buildte │
│          │        │          │          │       │       │ threshol │ st/chec │
│          │        │          │          │       │       │ d        │ kouts/d │
│          │        │          │          │       │       │          │ evel/ge │
│          │        │          │          │       │       │          │ neral_t │
│          │        │          │          │       │       │          │ ests/co │
│          │        │          │          │       │       │          │ nfigura │
│          │        │          │          │       │       │          │ tion/di │
│          │        │          │          │       │       │          │ sk_usag │
│          │        │          │          │       │       │          │ e.yml   │
└──────────┴────────┴──────────┴──────────┴───────┴───────┴──────────┴─────────┘
──────────────────────────────── Building Test ─────────────────────────────────
hello_world/53224311: Creating Test Directory: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/hello_world/hello_world/53224311
systemd_default_target/53d7b468: Creating Test Directory: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/systemd-default-target/systemd_default_target/53d7b468
ulimit_filelock_unlimited/fd70c210: Creating Test Directory: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_filelock_unlimited/fd70c210
ulimit_cputime_unlimited/8999ac1a: Creating Test Directory: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_cputime_unlimited/8999ac1a
ulimit_stacksize_unlimited/615e9a3d: Creating Test Directory: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_stacksize_unlimited/615e9a3d
ulimit_vmsize_unlimited/13a3573f: Creating Test Directory: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_vmsize_unlimited/13a3573f
ulimit_filedescriptor_4096/2879fbd0: Creating Test Directory: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_filedescriptor_4096/2879fbd0
ulimit_max_user_process_2048/8361aa78: Creating Test Directory: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_max_user_process_2048/8361aa78
kernel_swapusage/9428f470: Creating Test Directory: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/kernel_state/kernel_swapusage/9428f470
root_disk_usage/e0b58766: Creating Test Directory: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/disk_usage/root_disk_usage/e0b58766
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
root_disk_usage/e0b58766 does not have any dependencies adding test to queue
ulimit_vmsize_unlimited/13a3573f does not have any dependencies adding test to queue
ulimit_cputime_unlimited/8999ac1a does not have any dependencies adding test to queue
ulimit_filedescriptor_4096/2879fbd0 does not have any dependencies adding test to queue
ulimit_max_user_process_2048/8361aa78 does not have any dependencies adding test to queue
ulimit_filelock_unlimited/fd70c210 does not have any dependencies adding test to queue
kernel_swapusage/9428f470 does not have any dependencies adding test to queue
ulimit_stacksize_unlimited/615e9a3d does not have any dependencies adding test to queue
systemd_default_target/53d7b468 does not have any dependencies adding test to queue
hello_world/53224311 does not have any dependencies adding test to queue
        Builders Eligible to Run         
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Builder                               ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ root_disk_usage/e0b58766              │
│ ulimit_vmsize_unlimited/13a3573f      │
│ ulimit_cputime_unlimited/8999ac1a     │
│ ulimit_filedescriptor_4096/2879fbd0   │
│ ulimit_max_user_process_2048/8361aa78 │
│ ulimit_filelock_unlimited/fd70c210    │
│ kernel_swapusage/9428f470             │
│ ulimit_stacksize_unlimited/615e9a3d   │
│ systemd_default_target/53d7b468       │
│ hello_world/53224311                  │
└───────────────────────────────────────┘
root_disk_usage/e0b58766: Current Working Directory : /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/disk_usage/root_disk_usage/e0b58766/stage
root_disk_usage/e0b58766: Running Test via command: bash root_disk_usage_build.sh
root_disk_usage/e0b58766: Test completed in 0.036925 seconds with returncode: 0
root_disk_usage/e0b58766: Writing output file -  /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/disk_usage/root_disk_usage/e0b58766/root_disk_usage.out
root_disk_usage/e0b58766: Writing error file - /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/disk_usage/root_disk_usage/e0b58766/root_disk_usage.err
ulimit_vmsize_unlimited/13a3573f: Current Working Directory : /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_vmsize_unlimited/13a3573f/stage
ulimit_vmsize_unlimited/13a3573f: Running Test via command: bash ulimit_vmsize_unlimited_build.sh
ulimit_vmsize_unlimited/13a3573f: Test completed in 0.005945 seconds with returncode: 0
ulimit_vmsize_unlimited/13a3573f: Writing output file -  /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_vmsize_unlimited/13a3573f/ulimit_vmsize_unlimited.out
ulimit_vmsize_unlimited/13a3573f: Writing error file - /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_vmsize_unlimited/13a3573f/ulimit_vmsize_unlimited.err
ulimit_vmsize_unlimited/13a3573f: performing regular expression - '^unlimited$' on file: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_vmsize_unlimited/13a3573f/ulimit_vmsize_unlimited.out
ulimit_vmsize_unlimited/13a3573f: Regular Expression Match - Success!
ulimit_cputime_unlimited/8999ac1a: Current Working Directory : /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_cputime_unlimited/8999ac1a/stage
ulimit_cputime_unlimited/8999ac1a: Running Test via command: bash ulimit_cputime_unlimited_build.sh
ulimit_cputime_unlimited/8999ac1a: Test completed in 0.005586 seconds with returncode: 0
ulimit_cputime_unlimited/8999ac1a: Writing output file -  /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_cputime_unlimited/8999ac1a/ulimit_cputime_unlimited.out
ulimit_cputime_unlimited/8999ac1a: Writing error file - /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_cputime_unlimited/8999ac1a/ulimit_cputime_unlimited.err
ulimit_cputime_unlimited/8999ac1a: performing regular expression - '^unlimited$' on file: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_cputime_unlimited/8999ac1a/ulimit_cputime_unlimited.out
ulimit_cputime_unlimited/8999ac1a: Regular Expression Match - Success!
ulimit_filedescriptor_4096/2879fbd0: Current Working Directory : /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_filedescriptor_4096/2879fbd0/stage
ulimit_filedescriptor_4096/2879fbd0: Running Test via command: bash ulimit_filedescriptor_4096_build.sh
ulimit_filedescriptor_4096/2879fbd0: Test completed in 0.005665 seconds with returncode: 0
ulimit_filedescriptor_4096/2879fbd0: Writing output file -  /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_filedescriptor_4096/2879fbd0/ulimit_filedescriptor_4096.out
ulimit_filedescriptor_4096/2879fbd0: Writing error file - /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_filedescriptor_4096/2879fbd0/ulimit_filedescriptor_4096.err
ulimit_filedescriptor_4096/2879fbd0: performing regular expression - '^4096$' on file: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_filedescriptor_4096/2879fbd0/ulimit_filedescriptor_4096.out
ulimit_filedescriptor_4096/2879fbd0: Regular Expression Match - Failed!
ulimit_max_user_process_2048/8361aa78: Current Working Directory : /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_max_user_process_2048/8361aa78/stage
ulimit_max_user_process_2048/8361aa78: Running Test via command: bash ulimit_max_user_process_2048_build.sh
ulimit_max_user_process_2048/8361aa78: Test completed in 0.005702 seconds with returncode: 0
ulimit_max_user_process_2048/8361aa78: Writing output file -  /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_max_user_process_2048/8361aa78/ulimit_max_user_process_2048.out
ulimit_max_user_process_2048/8361aa78: Writing error file - /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_max_user_process_2048/8361aa78/ulimit_max_user_process_2048.err
ulimit_max_user_process_2048/8361aa78: performing regular expression - '^2048$' on file: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_max_user_process_2048/8361aa78/ulimit_max_user_process_2048.out
ulimit_max_user_process_2048/8361aa78: Regular Expression Match - Failed!
ulimit_filelock_unlimited/fd70c210: Current Working Directory : /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_filelock_unlimited/fd70c210/stage
ulimit_filelock_unlimited/fd70c210: Running Test via command: bash ulimit_filelock_unlimited_build.sh
ulimit_filelock_unlimited/fd70c210: Test completed in 0.006085 seconds with returncode: 0
ulimit_filelock_unlimited/fd70c210: Writing output file -  /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_filelock_unlimited/fd70c210/ulimit_filelock_unlimited.out
ulimit_filelock_unlimited/fd70c210: Writing error file - /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_filelock_unlimited/fd70c210/ulimit_filelock_unlimited.err
ulimit_filelock_unlimited/fd70c210: performing regular expression - '^unlimited$' on file: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_filelock_unlimited/fd70c210/ulimit_filelock_unlimited.out
ulimit_filelock_unlimited/fd70c210: Regular Expression Match - Success!
kernel_swapusage/9428f470: Current Working Directory : /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/kernel_state/kernel_swapusage/9428f470/stage
kernel_swapusage/9428f470: Running Test via command: bash kernel_swapusage_build.sh
kernel_swapusage/9428f470: failed to submit job with returncode: 255
───────────────── Error Message for kernel_swapusage/9428f470 ──────────────────
sysctl: cannot stat /proc/sys/kernel/swapusage: No such file or directory

kernel_swapusage/9428f470: Detected failure in running test, will attempt to retry test: 1 times
kernel_swapusage/9428f470: Run - 1/1
kernel_swapusage/9428f470: Running Test via command: bash kernel_swapusage_build.sh
kernel_swapusage/9428f470: failed to submit job with returncode: 255
kernel_swapusage/9428f470: Test completed in 0.099329 seconds with returncode: 255
kernel_swapusage/9428f470: Writing output file -  /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/kernel_state/kernel_swapusage/9428f470/kernel_swapusage.out
kernel_swapusage/9428f470: Writing error file - /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/kernel_state/kernel_swapusage/9428f470/kernel_swapusage.err
ulimit_stacksize_unlimited/615e9a3d: Current Working Directory : /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_stacksize_unlimited/615e9a3d/stage
ulimit_stacksize_unlimited/615e9a3d: Running Test via command: bash ulimit_stacksize_unlimited_build.sh
ulimit_stacksize_unlimited/615e9a3d: Test completed in 0.006264 seconds with returncode: 0
ulimit_stacksize_unlimited/615e9a3d: Writing output file -  /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_stacksize_unlimited/615e9a3d/ulimit_stacksize_unlimited.out
ulimit_stacksize_unlimited/615e9a3d: Writing error file - /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_stacksize_unlimited/615e9a3d/ulimit_stacksize_unlimited.err
ulimit_stacksize_unlimited/615e9a3d: performing regular expression - '^unlimited$' on file: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/ulimits/ulimit_stacksize_unlimited/615e9a3d/ulimit_stacksize_unlimited.out
ulimit_stacksize_unlimited/615e9a3d: Regular Expression Match - Failed!
systemd_default_target/53d7b468: Current Working Directory : /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/systemd-default-target/systemd_default_target/53d7b468/stage
systemd_default_target/53d7b468: Running Test via command: bash systemd_default_target_build.sh
systemd_default_target/53d7b468: failed to submit job with returncode: 1
────────────── Error Message for systemd_default_target/53d7b468 ───────────────

systemd_default_target/53d7b468: Detected failure in running test, will attempt to retry test: 1 times
systemd_default_target/53d7b468: Run - 1/1
systemd_default_target/53d7b468: Running Test via command: bash systemd_default_target_build.sh
systemd_default_target/53d7b468: failed to submit job with returncode: 1
systemd_default_target/53d7b468: Test completed in 0.116063 seconds with returncode: 1
systemd_default_target/53d7b468: Writing output file -  /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/systemd-default-target/systemd_default_target/53d7b468/systemd_default_target.out
systemd_default_target/53d7b468: Writing error file - /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/systemd-default-target/systemd_default_target/53d7b468/systemd_default_target.err
hello_world/53224311: Current Working Directory : /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/hello_world/hello_world/53224311/stage
hello_world/53224311: Running Test via command: bash hello_world_build.sh
hello_world/53224311: Test completed in 0.006115 seconds with returncode: 0
hello_world/53224311: Writing output file -  /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/hello_world/hello_world/53224311/hello_world.out
hello_world/53224311: Writing error file - /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/hello_world/hello_world/53224311/hello_world.err
                                  Test Summary                                  
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┓
┃ builder                 ┃ executor           ┃ status ┃ returncode ┃ runtime ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━┩
│ ulimit_filelock_unlimit │ generic.local.bash │ PASS   │ 0          │ 0.006   │
│ ed/fd70c210             │                    │        │            │         │
├─────────────────────────┼────────────────────┼────────┼────────────┼─────────┤
│ root_disk_usage/e0b5876 │ generic.local.bash │ PASS   │ 0          │ 0.037   │
│ 6                       │                    │        │            │         │
├─────────────────────────┼────────────────────┼────────┼────────────┼─────────┤
│ kernel_swapusage/9428f4 │ generic.local.bash │ FAIL   │ 255        │ 0.099   │
│ 70                      │                    │        │            │         │
├─────────────────────────┼────────────────────┼────────┼────────────┼─────────┤
│ ulimit_stacksize_unlimi │ generic.local.bash │ FAIL   │ 0          │ 0.006   │
│ ted/615e9a3d            │                    │        │            │         │
├─────────────────────────┼────────────────────┼────────┼────────────┼─────────┤
│ ulimit_max_user_process │ generic.local.bash │ FAIL   │ 0          │ 0.006   │
│ _2048/8361aa78          │                    │        │            │         │
├─────────────────────────┼────────────────────┼────────┼────────────┼─────────┤
│ systemd_default_target/ │ generic.local.bash │ FAIL   │ 1          │ 0.116   │
│ 53d7b468                │                    │        │            │         │
├─────────────────────────┼────────────────────┼────────┼────────────┼─────────┤
│ ulimit_vmsize_unlimited │ generic.local.bash │ PASS   │ 0          │ 0.006   │
│ /13a3573f               │                    │        │            │         │
├─────────────────────────┼────────────────────┼────────┼────────────┼─────────┤
│ ulimit_cputime_unlimite │ generic.local.bash │ PASS   │ 0          │ 0.006   │
│ d/8999ac1a              │                    │        │            │         │
├─────────────────────────┼────────────────────┼────────┼────────────┼─────────┤
│ hello_world/53224311    │ generic.local.bash │ PASS   │ 0          │ 0.006   │
├─────────────────────────┼────────────────────┼────────┼────────────┼─────────┤
│ ulimit_filedescriptor_4 │ generic.local.bash │ FAIL   │ 0          │ 0.006   │
│ 096/2879fbd0            │                    │        │            │         │
└─────────────────────────┴────────────────────┴────────┴────────────┴─────────┘



Passed Tests: 5/10 Percentage: 50.000%
Failed Tests: 5/10 Percentage: 50.000%


Adding 10 test results to report file: /tmp/tmp0ns2hqkt/var/report.json
Writing Logfile to /tmp/tmp0ns2hqkt/var/logs/buildtest_wx0_h99x.log

The -x option can be used to exclude buildspecs which works similar to -b where it can be a file or directory path. In the next example try running the following commands:

buildtest build -b general_tests/configuration -x general_tests/configuration/ulimits.yml
buildtest build -b general_tests/configuration -x general_tests/configuration

You will notice in the second command when buildtest has no buildspecs to build it will terminate immediately.

Buildtest supports test timeout which can be used if you don’t want to wait indefinitely for test to complete. You can use --timeout option which will terminate test if it exceeds the timelimit. The timeout is in number of seconds. Let’s try running the following example and take note of how timeout affects the test status:

buildtest build -b tutorials/sleep.yml
buildtest build -b tutorials/sleep.yml --timeout=1
buildtest build -b tutorials/sleep.yml --timeout=5

Buildtest supports test discovery based on tags via buildtest build --tags or short option -t. Let’s try running the following test, take note of the output as buildtest will show discovered buildspecs based on tag names

buildtest build -t network
$ buildtest build -t network
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│                                                                              │
│ User:               docs                                                     │
│ Hostname:           build-24186293-project-280831-buildtest                  │
│ Platform:           Linux                                                    │
│ Current Time:       2024/04/25 15:41:46                                      │
│ buildtest path:     /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version:  2.0                                                      │
│ python path:        /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version:     3.8.18                                                   │
│ Configuration File: /tmp/tmp0ns2hqkt/config.yml                              │
│ Test Directory:     /tmp/tmp0ns2hqkt/var/tests                               │
│ Report File:        /tmp/tmp0ns2hqkt/var/report.json                         │
│ Command:            /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
───────────────────────────  Discovering Buildspecs ────────────────────────────
                             Discovered buildspecs                              
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec                                                                    ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/t ║
║ utorials/tags_example.yml                                                    ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ Total: 1                                                                     ║
╚══════════════════════════════════════════════════════════════════════════════╝
                           Buildspecs By Tag=network                            
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec                                                                    ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/t ║
║ utorials/tags_example.yml                                                    ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ Total: 1                                                                     ║
╚══════════════════════════════════════════════════════════════════════════════╝


Total Discovered Buildspecs:  1
Total Excluded Buildspecs:  0
Detected Buildspecs after exclusion:  1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutorials/tags_example.yml: VALID
Total builder objects created: 2
                            Builders by type=script                             
┏━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┓
┃          ┃        ┃          ┃          ┃       ┃       ┃ descript ┃ buildsp ┃
┃ builder  ┃ type   ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ ion      ┃ ecs     ┃
┡━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━┩
│ string_t │ script │ generic. │ None     │ None  │ None  │ tags can │ /home/d │
│ ag/ca9f1 │        │ local.ba │          │       │       │ be a     │ ocs/che │
│ bb6      │        │ sh       │          │       │       │ string   │ ckouts/ │
│          │        │          │          │       │       │          │ readthe │
│          │        │          │          │       │       │          │ docs.or │
│          │        │          │          │       │       │          │ g/user_ │
│          │        │          │          │       │       │          │ builds/ │
│          │        │          │          │       │       │          │ buildte │
│          │        │          │          │       │       │          │ st/chec │
│          │        │          │          │       │       │          │ kouts/d │
│          │        │          │          │       │       │          │ evel/tu │
│          │        │          │          │       │       │          │ torials │
│          │        │          │          │       │       │          │ /tags_e │
│          │        │          │          │       │       │          │ xample. │
│          │        │          │          │       │       │          │ yml     │
├──────────┼────────┼──────────┼──────────┼───────┼───────┼──────────┼─────────┤
│ list_of_ │ script │ generic. │ None     │ None  │ None  │ tags can │ /home/d │
│ strings_ │        │ local.ba │          │       │       │ be a     │ ocs/che │
│ tags/97b │        │ sh       │          │       │       │ list of  │ ckouts/ │
│ a5e93    │        │          │          │       │       │ strings  │ readthe │
│          │        │          │          │       │       │          │ docs.or │
│          │        │          │          │       │       │          │ g/user_ │
│          │        │          │          │       │       │          │ builds/ │
│          │        │          │          │       │       │          │ buildte │
│          │        │          │          │       │       │          │ st/chec │
│          │        │          │          │       │       │          │ kouts/d │
│          │        │          │          │       │       │          │ evel/tu │
│          │        │          │          │       │       │          │ torials │
│          │        │          │          │       │       │          │ /tags_e │
│          │        │          │          │       │       │          │ xample. │
│          │        │          │          │       │       │          │ yml     │
└──────────┴────────┴──────────┴──────────┴───────┴───────┴──────────┴─────────┘
──────────────────────────────── Building Test ─────────────────────────────────
string_tag/ca9f1bb6: Creating Test Directory: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/tags_example/string_tag/ca9f1bb6
list_of_strings_tags/97ba5e93: Creating Test Directory: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/tags_example/list_of_strings_tags/97ba5e93
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
string_tag/ca9f1bb6 does not have any dependencies adding test to queue
list_of_strings_tags/97ba5e93 does not have any dependencies adding test to queue
    Builders Eligible to Run     
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Builder                       ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ string_tag/ca9f1bb6           │
│ list_of_strings_tags/97ba5e93 │
└───────────────────────────────┘
string_tag/ca9f1bb6: Current Working Directory : /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/tags_example/string_tag/ca9f1bb6/stage
string_tag/ca9f1bb6: Running Test via command: bash string_tag_build.sh
string_tag/ca9f1bb6: Test completed in 0.006583 seconds with returncode: 0
string_tag/ca9f1bb6: Writing output file -  /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/tags_example/string_tag/ca9f1bb6/string_tag.out
string_tag/ca9f1bb6: Writing error file - /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/tags_example/string_tag/ca9f1bb6/string_tag.err
list_of_strings_tags/97ba5e93: Current Working Directory : /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/tags_example/list_of_strings_tags/97ba5e93/stage
list_of_strings_tags/97ba5e93: Running Test via command: bash list_of_strings_tags_build.sh
list_of_strings_tags/97ba5e93: Test completed in 3.029036 seconds with returncode: 0
list_of_strings_tags/97ba5e93: Writing output file -  /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/tags_example/list_of_strings_tags/97ba5e93/list_of_strings_tags.out
list_of_strings_tags/97ba5e93: Writing error file - /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/tags_example/list_of_strings_tags/97ba5e93/list_of_strings_tags.err
                                  Test Summary                                  
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┓
┃ builder                 ┃ executor           ┃ status ┃ returncode ┃ runtime ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━┩
│ string_tag/ca9f1bb6     │ generic.local.bash │ PASS   │ 0          │ 0.007   │
├─────────────────────────┼────────────────────┼────────┼────────────┼─────────┤
│ list_of_strings_tags/97 │ generic.local.bash │ PASS   │ 0          │ 3.029   │
│ ba5e93                  │                    │        │            │         │
└─────────────────────────┴────────────────────┴────────┴────────────┴─────────┘



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


Adding 2 test results to report file: /tmp/tmp0ns2hqkt/var/report.json
Writing Logfile to /tmp/tmp0ns2hqkt/var/logs/buildtest__ruc1fvx.log

To learn more about how to run tests, please refer to Building Test (buildtest build) guide.

Querying Test Report

Buildtest will keep track of all tests in a report file (JSON) that can be used to display content of all test runs and query metadata specific to test. To fetch all test runs you can use buildtest report command which will displays output in a table format.

You can fetch the path to report file by running:

buildtest report path

Buildtest can write test results to alternate report file if buildtest --report is used, you can list all report files by running:

buildtest report list

buildtest rt is an alias for buildtest report command for those that hate typing :-)

We can fetch all pass and failed tests via --fail and --pass. Let’s try running the following:

buildtest rt --fail
buildtest rt --pass

Now let’s assume you want to know total failed tests in report file, you can use --row-count option which displays total row count. Let’s run the following and see total fail count:

buildtest rt --fail --row-count

The buildtest rt summary can be useful if you want to summary of report file.

Buildtest supports paging support with buildtest rt which can be useful when you have lots of tests. To enable pagination you can run:

buildtest rt --pager

Finally we can filter test records and format table columns via --filter and --format option. Let’s try running the following command

buildtest rt --filter tags=network --format name,id,tags
$ buildtest rt --filter tags=network --format name,id,tags
                 Report File: /tmp/tmp0ns2hqkt/var/report.json                  
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ name                                ┃ id              ┃ tags                 ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ string_tag                          │ ca9f1bb6        │ network              │
├─────────────────────────────────────┼─────────────────┼──────────────────────┤
│ list_of_strings_tags                │ 97ba5e93        │ network ping         │
└─────────────────────────────────────┴─────────────────┴──────────────────────┘

The --format option are comma separated list of format fields while --filter option are key=value pair. To see list of available format and filter fields you can run:

buildtest rt --helpfilter
buildtest rt --helpformat

Inspecting Test

The buildtest inspect command can be used to query test details and display metadata for one or more test. First you will want to see all available test and their corresponding unique identifiers. Let’s run the following

buildtest inspect list
$ buildtest inspect list
                      Test Summary by id, name, buildspec                       
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ id                      ┃ name                     ┃ buildspec               ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 1814633f-34a8-4a59-bf2e │ variables_bash           │ /home/docs/checkouts/re │
│ -6ec30f357282           │                          │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ devel/tutorials/vars.ym │
│                         │                          │ l                       │
│ 400d5ee2-c3ce-4380-a662 │ unskipped                │ /home/docs/checkouts/re │
│ -bee9ef4b90eb           │                          │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ devel/tutorials/skip_te │
│                         │                          │ sts.yml                 │
│ a985cbf9-507c-4036-b309 │ hello_world              │ /home/docs/checkouts/re │
│ -181d8799743f           │                          │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ devel/tutorials/hello_w │
│                         │                          │ orld.yml                │
│ 53224311-5941-4fc1-9209 │ hello_world              │ /home/docs/checkouts/re │
│ -55eef45af93f           │                          │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ devel/tutorials/hello_w │
│                         │                          │ orld.yml                │
│ fd70c210-34ad-43b7-82fc │ ulimit_filelock_unlimite │ /home/docs/checkouts/re │
│ -799c86a61df5           │ d                        │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ devel/general_tests/con │
│                         │                          │ figuration/ulimits.yml  │
│ 615e9a3d-9c3b-4768-8e42 │ ulimit_stacksize_unlimit │ /home/docs/checkouts/re │
│ -e69a7ab5ef9c           │ ed                       │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ devel/general_tests/con │
│                         │                          │ figuration/ulimits.yml  │
│ 8361aa78-feda-412f-aecb │ ulimit_max_user_process_ │ /home/docs/checkouts/re │
│ -a8de3e46d037           │ 2048                     │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ devel/general_tests/con │
│                         │                          │ figuration/ulimits.yml  │
│ 13a3573f-46a1-4d50-9d75 │ ulimit_vmsize_unlimited  │ /home/docs/checkouts/re │
│ -f3f7f7efb826           │                          │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ devel/general_tests/con │
│                         │                          │ figuration/ulimits.yml  │
│ 8999ac1a-f208-4216-9c01 │ ulimit_cputime_unlimited │ /home/docs/checkouts/re │
│ -624d746c81bd           │                          │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ devel/general_tests/con │
│                         │                          │ figuration/ulimits.yml  │
│ 2879fbd0-4b10-43fa-b3ae │ ulimit_filedescriptor_40 │ /home/docs/checkouts/re │
│ -a2cabace64b0           │ 96                       │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ devel/general_tests/con │
│                         │                          │ figuration/ulimits.yml  │
│ e0b58766-861f-4d7a-bdc6 │ root_disk_usage          │ /home/docs/checkouts/re │
│ -b93a1fce95da           │                          │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ devel/general_tests/con │
│                         │                          │ figuration/disk_usage.y │
│                         │                          │ ml                      │
│ 9428f470-fe9b-4b0d-866d │ kernel_swapusage         │ /home/docs/checkouts/re │
│ -8c42711be8de           │                          │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ devel/general_tests/con │
│                         │                          │ figuration/kernel_state │
│                         │                          │ .yml                    │
│ 53d7b468-bee0-4de8-8245 │ systemd_default_target   │ /home/docs/checkouts/re │
│ -bef37dd8b200           │                          │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ devel/general_tests/con │
│                         │                          │ figuration/systemd-defa │
│                         │                          │ ult-target.yml          │
│ ca9f1bb6-dc77-49af-9a3f │ string_tag               │ /home/docs/checkouts/re │
│ -53bc6edfbbd4           │                          │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ devel/tutorials/tags_ex │
│                         │                          │ ample.yml               │
│ 97ba5e93-db80-4354-8364 │ list_of_strings_tags     │ /home/docs/checkouts/re │
│ -357319a8b2c3           │                          │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ devel/tutorials/tags_ex │
│                         │                          │ ample.yml               │
└─────────────────────────┴──────────────────────────┴─────────────────────────┘

In buildtest, test are referred as builders which is in format <name>/<ID> where each test has a unique identifier separated by backslash / character. To see all builders you can run:

buildtest inspect list -b

The buildtest it command is an alias for buildtest inspect command, so we will use this command going forward. We will be using the builder notation when querying test via buildtest it name and buildtest it query. The command buildtest it name will display raw JSON record from the report file for a given test. The test names can be positional arguments so you can query multiple tests simultaneously.

Let’s run the following:

buildtest it name hello_world

The buildtest it query is used to query test records in human readable format. This command is useful once you run test via buildtest build and you want to inspect test result. buildtest can display test content, output and error file and support multiple test queries including regular expression!!

Let’s try running the following

buildtest it query -o -e -t hello_world
$ buildtest it query -o -e -t hello_world
─────────────── hello_world/53224311-5941-4fc1-9209-55eef45af93f ───────────────
Executor: generic.local.bash
Description: hello world example
State: PASS
Returncode: 0
Runtime: 0.006115 sec
Starttime: 2024/04/25 15:41:45
Endtime: 2024/04/25 15:41:45
Command: bash hello_world_build.sh
Test Script: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/hello_world/hello_world/53224311/hello_world.sh
Build Script: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/hello_world/hello_world/53224311/hello_world_build.sh
Output File: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/hello_world/hello_world/53224311/hello_world.out
Error File: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/hello_world/hello_world/53224311/hello_world.err
Log File: /tmp/tmp0ns2hqkt/var/logs/buildtest_wx0_h99x.log
─ Output File: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/hello_world/hell… ─
hello world!                                                                    
                                                                                
─ Error File: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/hello_world/hello… ─
                                                                                
─ Test File: /tmp/tmp0ns2hqkt/var/tests/generic.local.bash/hello_world/hello_… ─
#!/usr/bin/bash                                                                 
set -eo pipefail                                                                
# Content of run section                                                        
echo "hello world!"

You can retrieve paths to given test via buildtest path that can be useful if you want to navigate to directory or list contents. By default buildtest path will retrieve root directory of test. You can retrieve output and error via buildtest path -o and buildtest path -e. Let’s try running:

buildtest path hello_world
buildtest path -o hello_world
buildtest path -e hello_world

We encourage you review Query Test Report for a detailed guide on how to query test in buildtest.

Interacting with Buildspecs

Buildtest supports several ways to interact with buildspecs, such as querying buildspec cache, validating buildspecs, showing content of buildspecs, and editing buildspecs in editor. The buildtest buildspec command contains several subcommands that we will discuss in this session. To learn more we encourage you see Buildspecs Interface for detailed guide.

The buildtest show command can be used to provide a brief help message for each subcommand and usage. This command can be useful if you want to understand how a particular command works. Let’s run buildtest show buildspec which will summarize the buildtest buildspec command.

buildtest show buildspec
$ buildtest show 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 --pager      │ Paginate output of buildspec cache   │
│ buildtest buildspec find --root /tmp  │ Discover buildspecs in /tmp and      │
│ --rebuild                             │ rebuild buildspec cache              │
│ buildtest buildspec find --quiet      │ Rebuild cache file but don't display │
│ --rebuild                             │ output of 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 --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 --row-count  │ Print total count of records from    │
│                                       │ the table                            │
│ buildtest buildspec find --count=5    │ Limit output of buildspec cache to 5 │
│                                       │ elements                             │
│ buildtest buildspec find invalid      │ Show invalid buildspecs              │
│ buildtest buildspec find invalid      │ Show invalid buildspecs with error   │
│ --error                               │ messages                             │
│ buildtest buildspec find invalid      │ Print total count of records from    │
│ --row-count                           │ the table                            │
└───────────────────────────────────────┴──────────────────────────────────────┘
                             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 summary --pager   │ Paginate the output of summary for   │
│                                       │ buildspec cache                      │
│ buildtest buildspec show python_hello │ Show content of buildspec based on   │
│                                       │ test name 'python_hello'             │
│ buildtest buildspec show python_hello │ Use color theme 'emacs' for showing  │
│ --theme emacs                         │ content of test                      │
│ buildtest buildspec show-fail         │ Show content of buildspec on all     │
│                                       │ failed tests                         │
│ buildtest buildspec show-fail         │ Show content of test 'exit1_fail'    │
│ exit1_fail                            │                                      │
│ buildtest buildspec edit-test         │ Open test 'python_hello' in editor   │
│ python_hello                          │ 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                              │
│ buildtest buildspec maintainers find  │ Find buildspec with maintainer name  │
│ johndoe                               │ 'johndoe'                            │
│ buildtest buildspec maintainers       │ List all maintainers from buildspec  │
│                                       │ cache                                │
│ buildtest buildspec maintainers       │ Print total count of records from    │
│ --row-count                           │ the table                            │
│ buildtest buildspec maintainers       │ List all maintainers in machine      │
│ --terse --no-header                   │ readable format without header       │
│ buildtest buildspec maintainers       │ Show breakdown of maintainers by     │
│ --breakdown                           │ buildspecs                           │
└───────────────────────────────────────┴──────────────────────────────────────┘

To build the buildspec cache you will need to run the following:

buildtest buildspec find --rebuild -q

The --rebuild option will rebuild the cache and -q will supress output. If you want to see all valid buildspecs in cache you can run:

buildtest buildspec find

To retrieve all tags you can run:

buildtest buildspec find --tags

We can filter tests via --filter option which expects a key=value pair. Let’s filter by tagname python by running:

buildtest buildspec find --filter tags=python

We can format the columns using --format option where each field is comma separated. Let’s format by fields name, tags, description

buildtest buildspec find --filter tags=python --format name,tags,description

To see all filter and format fields you can use --helpfilter and --helpformat to list all fields and their description.

If you want to see a summary of the buildspec cache you can run:

buildtest buildspec summary

Buildtest has an alias buildtest bc for buildtest buildspec command so let’s use this going forward.

To validate a buildspec you can use buildtest bc validate command there are several options analogous to buildtest build for discovering buildspecs such as -b, -x, -t, -e. For instance let’s validate the following buildspecs:

buildtest bc validate -b tutorials/hello_world.yml -b general_tests/configuration
buildtest bc validate -t python

Let’s try validating an invalid buildspec so you can see what happens

buildtest bc validate -b tutorials/invalid_executor.yml
$ buildtest bc validate -b tutorials/invalid_executor.yml
─ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/… ─
"[/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/devel/tutorials/invalid_executor.yml]: Unable to find executor: badexecutor in ['generic.local.bash', 'generic.local.sh', 'generic.local.csh', 'generic.local.zsh']"


1 buildspecs failed to validate

To see content of buildspec you can use buildtest bc show which expects name of test. Note tab completion is supported.

Let’s run the following:

buildtest bc show sleep hello_world

Buildtest uses rich python library for coloring which is used extensively throughout the buildtest output. Rich supports several built-in themes that can be used for your preference. The buildtest bc show --theme <THEME> can be used select a color theme.

Currently, buildtest supports the following themes, feel free to tab complete:

   buildtest bc show --theme
abap                borland             emacs               gruvbox-dark        lovelace            native              paraiso-light       sas                 stata-dark          vs
algol               bw                  friendly            gruvbox-light       manni               nord                pastie              solarized-dark      stata-light         xcode
algol_nu            colorful            friendly_grayscale  igor                material            nord-darker         perldoc             solarized-light     tango               zenburn
arduino             default             fruity              inkpot              monokai             one-dark            rainbow_dash        staroffice          trac
autumn              dracula             github-dark         lilypond            murphy              paraiso-dark        rrt                 stata               vim

Let’s try running the same example with emacs theme:

buildtest bc show --theme emacs sleep

If you want to see list of invalid buildspecs you can run:

buildtest bc find invalid

Note, if you fix your invalid buildspec, buildtest will have no way of knowing if buildspec is valid until you rebuild the buildspec cache buildtest bc find --rebuild.

Query Details from Buildtest Configuration

In order to use buildtest, you need to configure buildtest. We will not discuss how to configure buildtest in this tutorial, but show how you can interact with configuration file via command line.

Buildtest provides a default configuration file that is sufficient to get started. To view path to configuration file you can run:

buildtest config path

We have an alias buildtest cg for buildtest config command. If you want to view content of configuration file you can run

buildtest cg view
$ buildtest cg view
───────────────────────── /tmp/tmp0ns2hqkt/config.yml ──────────────────────────
    1 system:
    2   generic:
    3     # specify a list of hostnames that is a regular expression where buildtest can run.
    4     hostnames: ['.*']
    5     # system description
    6     description: Generic System
    7     # specify module system to use. Supported module systems are [lmod, environment-modules, none]
    8     moduletool: none
    9 
   10     # specify size of job pool (https://docs.python.org/3/library/multiprocessing.html#multiprocessing.pool.Pool). This will configure the number of processes that can run in parallel.
   11     # If not specified then buildtest will use all available cores on the system.
   12     poolsize: 1
   13 
   14     # maximum number of jobs that can run in parallel. If not specified, buildtest will run all jobs in parallel.
   15     #max_jobs: 1
   16 
   17     # test timeout in number of seconds
   18     # timeout: 3600
   19 
   20     # enable pagination for buildtest
   21     pager: false
   22 
   23     # options for buildtest buildspec find command
   24     buildspecs:
   25       # determine whether to rebuild buildspec cache
   26       rebuild: false
   27       # determine number of records to display
   28       count: 15
   29 
   30       # specify format fields
   31       #format: name,description
   32 
   33       # display output in terse mode
   34       terse: false
   35 
   36       # list of paths to search for buildspecs
   37       #root: ["$BUILDTEST_ROOT/tutorials", "$BUILDTEST_ROOT/examples"]
   38 
   39     # options for buildtest report command
   40     report:
   41       # number of records to display
   42       count: 25
   43       # display output in terse mode
   44       terse: false
   45       # specify format fields
   46       format: name,id,state,runtime,returncode
   47 
   48     # specify directory paths to search for binaries
   49     #paths:
   50       # directory path to search for slurm binaries.
   51       #slurm: "/usr/bin"
   52 
   53       # directory path to search for lsf binaries.
   54       #lsf: "/usr/bin"
   55 
   56       # directory path to search for pbs binaries.
   57       #pbs: "/usr/bin"
   58 
   59       # directory path to search for torque binaries.
   60       #torque: "/usr/bin"
   61 
   62       # directory path to search for cobalt binaries.
   63       #cobalt: "/usr/bin"
   64 
   65 
   66     # start of executor configuration
   67     executors:
   68       # local executor is used to submit jobs on local machine. In this example we have 4 executors: bash, sh, csh, zsh that will submit jobs using bash, sh, csh, zsh shell respectively.
   69       local:
   70         bash:
   71           description: submit jobs on local machine using bash shell
   72           shell: bash
   73         sh:
   74           description: submit jobs on local machine using sh shell
   75           shell: sh
   76         csh:
   77           description: submit jobs on local machine using csh shell
   78           shell: csh
   79         zsh:
   80           description: submit jobs on local machine using zsh shell
   81           shell: zsh
   82     # specify compiler declaration
   83     compilers:
   84       compiler:
   85         # declaration of all gcc compilers
   86         gcc:
   87           # name of compiler
   88           builtin_gcc:
   89             cc: gcc
   90             fc: gfortran
   91             cxx: g++
   92     # specify CDASH configuration when using 'buildtest cdash upload'
   93     cdash:
   94       # CDASH server
   95       url: https://my.cdash.org/
   96       # name of CDASH project where to push test reports
   97       project: buildtest
   98       # specify the site name which should generally by name of your HPC system. This is used by CDASH to group test results by site
   99       site: generic
  100       # specify the build name which is used to group test results by build name
  101       buildname: tutorials
  102

We also support color themes (buildtest cg view --theme <theme>) when showing content of buildtest configuration.

Buildtest configuration file defines one or more executors that are used when writing test. Every test must be run by an executor. To retrieve all executors in a flat-listing you can run the following

buildtest cg executors list
$ buildtest cg executors list
generic.local.bash
generic.local.sh
generic.local.csh
generic.local.zsh

Buildtest can show executor details in JSON and YAML format, you can fetch the details by running the following

buildtest cg executors list --json
$ buildtest cg executors list --json
{
  "executors": {
    "local": {
      "bash": {
        "description": "submit jobs on local machine using bash shell",
        "shell": "bash"
      },
      "sh": {
        "description": "submit jobs on local machine using sh shell",
        "shell": "sh"
      },
      "csh": {
        "description": "submit jobs on local machine using csh shell",
        "shell": "csh"
      },
      "zsh": {
        "description": "submit jobs on local machine using zsh shell",
        "shell": "zsh"
      }
    }
  }
}
buildtest cg executors list --yaml
$ buildtest cg executors list --yaml
executors:
  local:
    bash:
      description: submit jobs on local machine using bash shell
      shell: bash
    csh:
      description: submit jobs on local machine using csh shell
      shell: csh
    sh:
      description: submit jobs on local machine using sh shell
      shell: sh
    zsh:
      description: submit jobs on local machine using zsh shell
      shell: zsh