Building Test via buildtest¶
This guide will get you familiar with buildtest command line interface. Once you complete this section, you can proceed to writing buildspecs section where we will cover how to write buildspecs.
Once you install buildtest, you should find the buildtest command in your $PATH. You can check the path to buildtest command by running:
$ which buildtest
If you don’t see buildtest go back and install buildtest.
When you clone buildtest, you also get a set of buildspecs that you can run on your
system. The buildtest build command is used for building and running tests.
Buildtest will read one or more buildspecs file that adheres to one of the
buildtest schemas. For a complete list of build options, run buildtest build --help
Build Usage¶
$ buildtest build --help
usage: buildtest [options] [COMMANDS] build [-h] [-b BUILDSPEC] [-x EXCLUDE] [-t TAGS] [-ft FILTER_TAGS] [-e EXECUTOR]
[-s {parse,build}] [--testdir TESTDIR] [--rebuild REBUILD] [-r REPORT]
[--max-pend-time MAX_PEND_TIME] [--poll-interval POLL_INTERVAL] [-k]
optional arguments:
-h, --help show this help message and exit
-b BUILDSPEC, --buildspec BUILDSPEC
Specify a buildspec (file or directory) to build. A buildspec must end in '.yml' extension.
-x EXCLUDE, --exclude EXCLUDE
Exclude one or more buildspecs (file or directory) from processing. A buildspec must end in
'.yml' extension.
-t TAGS, --tags TAGS Discover buildspecs by tags found in buildspec cache
-ft FILTER_TAGS, --filter-tags FILTER_TAGS
Filter buildspecs by tags when building tests.
-e EXECUTOR, --executor EXECUTOR
Discover buildspecs by executor name found in buildspec cache
-s {parse,build}, --stage {parse,build}
control behavior of buildtest build
--testdir TESTDIR Specify a custom test directory where to write tests. This overrides configuration file and
default location.
--rebuild REBUILD Rebuild test X number of times. Must be a positive number between [1-50]
-r REPORT, --report REPORT
Specify a report file where tests will be written.
--max-pend-time MAX_PEND_TIME
Specify Maximum Pending Time (sec) for job before cancelling job. This only applies for batch
job submission.
--poll-interval POLL_INTERVAL
Specify Poll Interval (sec) for polling batch jobs
-k, --keep-stage-dir Keep stage directory after job completion.
Building a Test¶
To build a test, we use the --buildspec or short option -b to specify the
path to buildspec file. Let’s see some examples, first we specify a full path to buildspec file.
In this example, buildtest will discover buildspecs followed by
parsing the test with appropriate schema and generate a shell script that is run
by buildtest. You can learn more about build and test process.
$ buildtest build -b $BUILDTEST_ROOT/tutorials/vars.yml
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:30
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build -b /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/vars.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+-------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+=================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/vars.yml |
+-------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
-------------------------+--------------+-------------------------------------------------------------------------------------------------
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/vars.yml
name description
-------------- -------------------------------
variables_bash Declare shell variables in bash
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
----------------+----------+--------+--------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------
variables_bash | 4d34c3aa | script | generic.local.bash | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/vars/variables_bash/0/variables_bash_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
name | id | executor | status | returncode
----------------+----------+--------------------+----------+--------------
variables_bash | 4d34c3aa | generic.local.bash | PASS | 0
+----------------------+
| Stage: Test Summary |
+----------------------+
Passed Tests: 1/1 Percentage: 100.000%
Failed Tests: 0/1 Percentage: 0.000%
Writing Logfile to: /tmp/buildtest_dyv8b4j0.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest.log
Note
buildtest will only read buildspecs with .yml extension, if you specify a
.yaml it will be ignored by buildtest.
The --buildspec option can be used to specify a file or directory path. If you want
to build multiple buildspecs in a directory you can specify the directory path
and buildtest will recursively search for all .yml files. In the next example,
we build all tests in directory general_tests/configuration.
$ buildtest build -b general_tests/configuration/
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:51
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build -b general_tests/configuration/
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+-------------------------------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+=====================================================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/disk_usage.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/ssh_localhost.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/ulimits.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/kernel_state.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/systemd-default-target.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 5
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 5
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
-------------------------+--------------+-------------------------------------------------------------------------------------------------------------------------------------
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/disk_usage.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/ssh_localhost.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/ulimits.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/kernel_state.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/systemd-default-target.yml
name description
---------------------------- ----------------------------------------------------------------
root_disk_usage Check root disk usage and report if it exceeds threshold
ssh_localhost_remotecommand Test if ssh on localhost works and if we can run remote command.
ulimit_filelock_unlimited Check if file lock is set to unlimited in ulimits
ulimit_cputime_unlimited Check if cputime is set to unlimited in ulimits
ulimit_stacksize_unlimited Check if stack size is set to unlimited in ulimits
ulimit_vmsize_unlimited Check virtual memory size and check if its set to unlimited
ulimit_filedescriptor_4096 Check if open file descriptors limit is set to 4096
ulimit_max_user_process_2048 Check max number of user process limit is set to 2048
kernel_swapusage Retrieve Kernel Swap Usage
systemd_default_target check if default target is multi-user.target
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
------------------------------+----------+--------+--------------------+---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
root_disk_usage | 3dd8135a | script | generic.local.bash | ['filesystem', 'storage'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/disk_usage/root_disk_usage/0/root_disk_usage_build.sh
ssh_localhost_remotecommand | c2386a01 | script | generic.local.bash | ['ssh'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/ssh_localhost/ssh_localhost_remotecommand/0/ssh_localhost_remotecommand_build.sh
ulimit_filelock_unlimited | 3bb18d20 | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/ulimits/ulimit_filelock_unlimited/0/ulimit_filelock_unlimited_build.sh
ulimit_cputime_unlimited | cd4bfa0d | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/ulimits/ulimit_cputime_unlimited/0/ulimit_cputime_unlimited_build.sh
ulimit_stacksize_unlimited | 155261e0 | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/ulimits/ulimit_stacksize_unlimited/0/ulimit_stacksize_unlimited_build.sh
ulimit_vmsize_unlimited | 4c268496 | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/ulimits/ulimit_vmsize_unlimited/0/ulimit_vmsize_unlimited_build.sh
ulimit_filedescriptor_4096 | c22ab4c1 | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/ulimits/ulimit_filedescriptor_4096/0/ulimit_filedescriptor_4096_build.sh
ulimit_max_user_process_2048 | 5e687dd4 | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/ulimits/ulimit_max_user_process_2048/0/ulimit_max_user_process_2048_build.sh
kernel_swapusage | 2a6ab5c2 | script | generic.local.bash | ['configuration'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/kernel_state/kernel_swapusage/0/kernel_swapusage_build.sh
systemd_default_target | 2185cf71 | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/systemd-default-target/systemd_default_target/0/systemd_default_target_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
name | id | executor | status | returncode
------------------------------+----------+--------------------+----------+--------------
root_disk_usage | 3dd8135a | generic.local.bash | PASS | 0
ssh_localhost_remotecommand | c2386a01 | generic.local.bash | FAIL | 255
ulimit_filelock_unlimited | 3bb18d20 | generic.local.bash | PASS | 0
ulimit_cputime_unlimited | cd4bfa0d | generic.local.bash | PASS | 0
ulimit_stacksize_unlimited | 155261e0 | generic.local.bash | FAIL | 0
ulimit_vmsize_unlimited | 4c268496 | generic.local.bash | PASS | 0
ulimit_filedescriptor_4096 | c22ab4c1 | generic.local.bash | FAIL | 0
ulimit_max_user_process_2048 | 5e687dd4 | generic.local.bash | FAIL | 0
kernel_swapusage | 2a6ab5c2 | generic.local.bash | FAIL | 127
systemd_default_target | 2185cf71 | generic.local.bash | FAIL | 1
+----------------------+
| Stage: Test Summary |
+----------------------+
Passed Tests: 4/10 Percentage: 40.000%
Failed Tests: 6/10 Percentage: 60.000%
Writing Logfile to: /tmp/buildtest_3ujxy0fh.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest.log
Building Multiple Buildspecs¶
You can append -b option to build multiple buildspecs in the same
command. Buildtest will discover buildspecs for every argument (-b) and accumulate
a list of buildspecs to run. In this example, we instruct buildtest to build
a buildspec file and all buildspecs in a directory path.
$ buildtest build -b general_tests/configuration/ -b tutorials/vars.yml
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:52
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build -b general_tests/configuration/ -b tutorials/vars.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+-------------------------------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+=====================================================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/vars.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/kernel_state.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/systemd-default-target.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/ulimits.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/disk_usage.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/ssh_localhost.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 6
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 6
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
-------------------------+--------------+-------------------------------------------------------------------------------------------------------------------------------------
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/vars.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/kernel_state.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/systemd-default-target.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/ulimits.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/disk_usage.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/ssh_localhost.yml
name description
---------------------------- ----------------------------------------------------------------
variables_bash Declare shell variables in bash
kernel_swapusage Retrieve Kernel Swap Usage
systemd_default_target check if default target is multi-user.target
ulimit_filelock_unlimited Check if file lock is set to unlimited in ulimits
ulimit_cputime_unlimited Check if cputime is set to unlimited in ulimits
ulimit_stacksize_unlimited Check if stack size is set to unlimited in ulimits
ulimit_vmsize_unlimited Check virtual memory size and check if its set to unlimited
ulimit_filedescriptor_4096 Check if open file descriptors limit is set to 4096
ulimit_max_user_process_2048 Check max number of user process limit is set to 2048
root_disk_usage Check root disk usage and report if it exceeds threshold
ssh_localhost_remotecommand Test if ssh on localhost works and if we can run remote command.
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
------------------------------+----------+--------+--------------------+---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
variables_bash | 7597f889 | script | generic.local.bash | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/vars/variables_bash/1/variables_bash_build.sh
kernel_swapusage | 808c8828 | script | generic.local.bash | ['configuration'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/kernel_state/kernel_swapusage/1/kernel_swapusage_build.sh
systemd_default_target | 40a017a5 | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/systemd-default-target/systemd_default_target/1/systemd_default_target_build.sh
ulimit_filelock_unlimited | de34bf13 | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/ulimits/ulimit_filelock_unlimited/1/ulimit_filelock_unlimited_build.sh
ulimit_cputime_unlimited | e40139a3 | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/ulimits/ulimit_cputime_unlimited/1/ulimit_cputime_unlimited_build.sh
ulimit_stacksize_unlimited | 6bd977c0 | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/ulimits/ulimit_stacksize_unlimited/1/ulimit_stacksize_unlimited_build.sh
ulimit_vmsize_unlimited | d8212946 | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/ulimits/ulimit_vmsize_unlimited/1/ulimit_vmsize_unlimited_build.sh
ulimit_filedescriptor_4096 | 55160d1a | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/ulimits/ulimit_filedescriptor_4096/1/ulimit_filedescriptor_4096_build.sh
ulimit_max_user_process_2048 | 3f4aa574 | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/ulimits/ulimit_max_user_process_2048/1/ulimit_max_user_process_2048_build.sh
root_disk_usage | a4e7fc98 | script | generic.local.bash | ['filesystem', 'storage'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/disk_usage/root_disk_usage/1/root_disk_usage_build.sh
ssh_localhost_remotecommand | 9e0d34b7 | script | generic.local.bash | ['ssh'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/ssh_localhost/ssh_localhost_remotecommand/1/ssh_localhost_remotecommand_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
name | id | executor | status | returncode
------------------------------+----------+--------------------+----------+--------------
variables_bash | 7597f889 | generic.local.bash | PASS | 0
kernel_swapusage | 808c8828 | generic.local.bash | FAIL | 127
systemd_default_target | 40a017a5 | generic.local.bash | FAIL | 1
ulimit_filelock_unlimited | de34bf13 | generic.local.bash | PASS | 0
ulimit_cputime_unlimited | e40139a3 | generic.local.bash | PASS | 0
ulimit_stacksize_unlimited | 6bd977c0 | generic.local.bash | FAIL | 0
ulimit_vmsize_unlimited | d8212946 | generic.local.bash | PASS | 0
ulimit_filedescriptor_4096 | 55160d1a | generic.local.bash | FAIL | 0
ulimit_max_user_process_2048 | 3f4aa574 | generic.local.bash | FAIL | 0
root_disk_usage | a4e7fc98 | generic.local.bash | PASS | 0
ssh_localhost_remotecommand | 9e0d34b7 | generic.local.bash | FAIL | 255
+----------------------+
| Stage: Test Summary |
+----------------------+
Passed Tests: 5/11 Percentage: 45.455%
Failed Tests: 6/11 Percentage: 54.545%
Writing Logfile to: /tmp/buildtest_s8xzvrxp.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest.log
Excluding Buildspecs¶
So far we learned how to build buildspecs by file and directory path using the -b
option. Next, we will discuss how one may exclude buildspecs which behaves similar to
-b option. You can exclude buildspecs via --exclude or short option -x
which can be useful when you want to exclude certain files or sub directory.
For example we can build all buildspecs in tutorials but exclude file tutorials/vars.yml
by running:
$ buildtest build -b tutorials -x tutorials/vars.yml
buildtest will discover all buildspecs and then exclude any buildspecs specified
by -x option. You can specify -x multiple times just like -b option.
For example, we can undo discovery by passing same option to -b and -x as follows
$ buildtest build -b tutorials/ -x tutorials/
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:52
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build -b tutorials/ -x tutorials/
There are no Buildspec files to process.
Buildtest will stop immediately if there are no Buildspecs to process, this is true if you were to specify files instead of directory.
In this example, we build all buildspecs in a directory but exclude a file. Buildtest
will report the excluded buildspecs in the output and -x option can be appended multiple times.
The -x can be a file or a directory and behaves similar to -b option.
$ buildtest build -b general_tests/configuration/ -x general_tests/configuration/ulimits.yml
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:53
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build -b general_tests/configuration/ -x general_tests/configuration/ulimits.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+-------------------------------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+=====================================================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/systemd-default-target.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/ulimits.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/kernel_state.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/ssh_localhost.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/disk_usage.yml |
+-------------------------------------------------------------------------------------------------------------------------------------+
+----------------------------------------------------------------------------------------------------------------------+
| Excluded Buildspecs |
+======================================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/ulimits.yml |
+----------------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 5
Excluded Buildspecs: 1
Detected Buildspecs after exclusion: 4
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
-------------------------+--------------+-------------------------------------------------------------------------------------------------------------------------------------
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/systemd-default-target.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/kernel_state.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/ssh_localhost.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/general_tests/configuration/disk_usage.yml
name description
--------------------------- ----------------------------------------------------------------
systemd_default_target check if default target is multi-user.target
kernel_swapusage Retrieve Kernel Swap Usage
ssh_localhost_remotecommand Test if ssh on localhost works and if we can run remote command.
root_disk_usage Check root disk usage and report if it exceeds threshold
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
-----------------------------+----------+--------+--------------------+---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
systemd_default_target | 46bdeee3 | script | generic.local.bash | ['system'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/systemd-default-target/systemd_default_target/2/systemd_default_target_build.sh
kernel_swapusage | 6b8d64b1 | script | generic.local.bash | ['configuration'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/kernel_state/kernel_swapusage/2/kernel_swapusage_build.sh
ssh_localhost_remotecommand | 734cb524 | script | generic.local.bash | ['ssh'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/ssh_localhost/ssh_localhost_remotecommand/2/ssh_localhost_remotecommand_build.sh
root_disk_usage | af270f01 | script | generic.local.bash | ['filesystem', 'storage'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/disk_usage/root_disk_usage/2/root_disk_usage_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
name | id | executor | status | returncode
-----------------------------+----------+--------------------+----------+--------------
systemd_default_target | 46bdeee3 | generic.local.bash | FAIL | 1
kernel_swapusage | 6b8d64b1 | generic.local.bash | FAIL | 127
ssh_localhost_remotecommand | 734cb524 | generic.local.bash | FAIL | 255
root_disk_usage | af270f01 | generic.local.bash | PASS | 0
+----------------------+
| Stage: Test Summary |
+----------------------+
Passed Tests: 1/4 Percentage: 25.000%
Failed Tests: 3/4 Percentage: 75.000%
Writing Logfile to: /tmp/buildtest_w12bth6s.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest.log
Building By Tags¶
buildtest can perform builds by tags by using --tags or short option (-t).
In order to use this feature, buildtest must load buildspecs in cache which can be run
via buildtest buildspec find. If you are unsure of the available tags you can
run buildtest buildspec find --tags or let buildtest tab-complete the available tags. For more details
see Querying buildspec tags.
Let’s assume you want to build by tag name network, buildtest
will attempt to find all tests that contain tags: ['network'] in the buildspec
which is loaded in the buildcache cache. If a test matches the tag name, the test
will be picked up during the discover process.
$ buildtest build -t network
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:53
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build -t network
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+---------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+=========================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/tags_example.yml |
+---------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
BREAKDOWN OF BUILDSPECS BY TAGS
----------------------------------
Detected Tag Names: ['network']
+---------------------------------------------------------------------------------------------------------+
| network |
+=========================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/tags_example.yml |
+---------------------------------------------------------------------------------------------------------+
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
-------------------------+--------------+---------------------------------------------------------------------------------------------------------
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/tags_example.yml
name description
-------------------- -----------------------------
string_tag tags can be a string
list_of_strings_tags tags can be a list of strings
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
----------------------+----------+--------+--------------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
string_tag | 405b133c | script | generic.local.bash | network | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/tags_example/string_tag/0/string_tag_build.sh
list_of_strings_tags | 4ae61a72 | script | generic.local.bash | ['network', 'ping'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/tags_example/list_of_strings_tags/0/list_of_strings_tags_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
name | id | executor | status | returncode
----------------------+----------+--------------------+----------+--------------
string_tag | 405b133c | generic.local.bash | PASS | 0
list_of_strings_tags | 4ae61a72 | generic.local.bash | FAIL | 127
+----------------------+
| Stage: Test Summary |
+----------------------+
Passed Tests: 1/2 Percentage: 50.000%
Failed Tests: 1/2 Percentage: 50.000%
Writing Logfile to: /tmp/buildtest_9r9m7gya.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest.log
You can build by multiple tags by specifying --tags multiple times. In next
example we build all tests with tag name pass and python.
$ buildtest build -t python -t pass
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:53
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build -t python -t pass
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+============================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-shell.yml |
+------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-hello.yml |
+------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/pass_returncode.yml |
+------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 3
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 3
BREAKDOWN OF BUILDSPECS BY TAGS
----------------------------------
Detected Tag Names: ['python', 'pass']
+---------------------------------------------------------------------------------------------------------+
| python |
+=========================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-shell.yml |
+---------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-hello.yml |
+---------------------------------------------------------------------------------------------------------+
+------------------------------------------------------------------------------------------------------------+
| pass |
+============================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/pass_returncode.yml |
+------------------------------------------------------------------------------------------------------------+
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
-------------------------+--------------+------------------------------------------------------------------------------------------------------------
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-shell.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-hello.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/pass_returncode.yml
name description
------------------------ ---------------------------------------------------
circle_area Calculate circle of area given a radius
python_hello Hello World python
exit1_fail exit 1 by default is FAIL
exit1_pass report exit 1 as PASS
returncode_list_mismatch exit 2 failed since it failed to match returncode 1
returncode_int_match exit 128 matches returncode 128
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
--------------------------+----------+--------+----------------------+-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
circle_area | 178ef5ce | script | generic.local.python | ['tutorials', 'python'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.python/python-shell/circle_area/1/circle_area_build.sh
python_hello | 04a87317 | script | generic.local.bash | python | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/python-hello/python_hello/1/python_hello_build.sh
exit1_fail | 84c02c94 | script | generic.local.sh | ['tutorials', 'fail'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/exit1_fail/1/exit1_fail_build.sh
exit1_pass | 3e06bf49 | script | generic.local.sh | ['tutorials', 'pass'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/exit1_pass/1/exit1_pass_build.sh
returncode_list_mismatch | ed0a8187 | script | generic.local.sh | ['tutorials', 'fail'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/returncode_list_mismatch/1/returncode_list_mismatch_build.sh
returncode_int_match | 7f0c8ed0 | script | generic.local.sh | ['tutorials', 'pass'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/returncode_int_match/1/returncode_int_match_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
name | id | executor | status | returncode
--------------------------+----------+----------------------+----------+--------------
circle_area | 178ef5ce | generic.local.python | PASS | 0
python_hello | 04a87317 | generic.local.bash | PASS | 0
exit1_fail | 84c02c94 | generic.local.sh | FAIL | 1
exit1_pass | 3e06bf49 | generic.local.sh | PASS | 1
returncode_list_mismatch | ed0a8187 | generic.local.sh | FAIL | 2
returncode_int_match | 7f0c8ed0 | generic.local.sh | PASS | 128
+----------------------+
| Stage: Test Summary |
+----------------------+
Passed Tests: 4/6 Percentage: 66.667%
Failed Tests: 2/6 Percentage: 33.333%
Writing Logfile to: /tmp/buildtest_u8hjw81_.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest.log
When multiple tags are specified, we search each tag independently and if it’s
found in the buildspec cache we retrieve the buildspec file and add file to queue.
This queue is a list of buildspecs that buildtest will process (i.e parse, build, run).
You can query tags from buildspecs cache to see all available
tags by running buildtest buildspec find --tags.
Note
The --tags is used for discovering buildspec file and not filtering tests
by tag. If you want to filter tests by tags use --filter-tags.
The --filter-tags or short option -ft is used for filtering tests by
tag name. The --filter-tags is used in conjunction with other options like
--buildspec, --tags, or --executor for discovering buildspecs.
Let’s rerun the previous example and filter tests by pass. Now we only see
tests built with tagname pass and all remaining tests were ignored.
$ buildtest build --tags pass --filter-tags pass -b tutorials/python-hello.yml
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:54
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build --tags pass --filter-tags pass -b tutorials/python-hello.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+============================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-hello.yml |
+------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/pass_returncode.yml |
+------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 2
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 2
BREAKDOWN OF BUILDSPECS BY TAGS
----------------------------------
Detected Tag Names: ['pass']
+------------------------------------------------------------------------------------------------------------+
| pass |
+============================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/pass_returncode.yml |
+------------------------------------------------------------------------------------------------------------+
[python_hello][/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-hello.yml]: test is skipped because it is not in tag filter list: ['pass']
[exit1_fail][/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/pass_returncode.yml]: test is skipped because it is not in tag filter list: ['pass']
[returncode_list_mismatch][/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/pass_returncode.yml]: test is skipped because it is not in tag filter list: ['pass']
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
-------------------------+--------------+------------------------------------------------------------------------------------------------------------
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-hello.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/pass_returncode.yml
name description
-------------------- -------------------------------
exit1_pass report exit 1 as PASS
returncode_int_match exit 128 matches returncode 128
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
----------------------+----------+--------+------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
exit1_pass | dec97567 | script | generic.local.sh | ['tutorials', 'pass'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/exit1_pass/2/exit1_pass_build.sh
returncode_int_match | 56e33ad6 | script | generic.local.sh | ['tutorials', 'pass'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/returncode_int_match/2/returncode_int_match_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
name | id | executor | status | returncode
----------------------+----------+------------------+----------+--------------
exit1_pass | dec97567 | generic.local.sh | PASS | 1
returncode_int_match | 56e33ad6 | generic.local.sh | PASS | 128
+----------------------+
| Stage: Test Summary |
+----------------------+
Passed Tests: 2/2 Percentage: 100.000%
Failed Tests: 0/2 Percentage: 0.000%
Writing Logfile to: /tmp/buildtest_j9xotkv4.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest.log
The --filter-tags option can be appended multiple times to filter tests by
multiple tags. If buildtest detects no tests were found when filtering tests by
tag name then buildtest will terminate with a message.
You can combine --tags with --buildspec to discover buildspecs in a single command.
buildtest will query tags and buildspecs independently and combine all discovered
buildspecs together.
$ buildtest build --tags pass --buildspec tutorials/python-hello.yml
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:54
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build --tags pass --buildspec tutorials/python-hello.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+============================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/pass_returncode.yml |
+------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-hello.yml |
+------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 2
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 2
BREAKDOWN OF BUILDSPECS BY TAGS
----------------------------------
Detected Tag Names: ['pass']
+------------------------------------------------------------------------------------------------------------+
| pass |
+============================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/pass_returncode.yml |
+------------------------------------------------------------------------------------------------------------+
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
-------------------------+--------------+------------------------------------------------------------------------------------------------------------
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/pass_returncode.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-hello.yml
name description
------------------------ ---------------------------------------------------
exit1_fail exit 1 by default is FAIL
exit1_pass report exit 1 as PASS
returncode_list_mismatch exit 2 failed since it failed to match returncode 1
returncode_int_match exit 128 matches returncode 128
python_hello Hello World python
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
--------------------------+----------+--------+--------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
exit1_fail | 93ad2bb3 | script | generic.local.sh | ['tutorials', 'fail'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/exit1_fail/2/exit1_fail_build.sh
exit1_pass | 7c74495b | script | generic.local.sh | ['tutorials', 'pass'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/exit1_pass/3/exit1_pass_build.sh
returncode_list_mismatch | 8a13233b | script | generic.local.sh | ['tutorials', 'fail'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/returncode_list_mismatch/2/returncode_list_mismatch_build.sh
returncode_int_match | 478bf901 | script | generic.local.sh | ['tutorials', 'pass'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/returncode_int_match/3/returncode_int_match_build.sh
python_hello | de751b51 | script | generic.local.bash | python | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/python-hello/python_hello/2/python_hello_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
name | id | executor | status | returncode
--------------------------+----------+--------------------+----------+--------------
exit1_fail | 93ad2bb3 | generic.local.sh | FAIL | 1
exit1_pass | 7c74495b | generic.local.sh | PASS | 1
returncode_list_mismatch | 8a13233b | generic.local.sh | FAIL | 2
returncode_int_match | 478bf901 | generic.local.sh | PASS | 128
python_hello | de751b51 | generic.local.bash | PASS | 0
+----------------------+
| Stage: Test Summary |
+----------------------+
Passed Tests: 3/5 Percentage: 60.000%
Failed Tests: 2/5 Percentage: 40.000%
Writing Logfile to: /tmp/buildtest_5ra6r44a.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest.log
As you may see, there are several ways to build buildspecs with buildtest. Tags is great way to build a whole collection of tests if you don’t know path to all the files. You can specify multiple tags per buildspecs to classify how test can be run.
Building by Executors¶
Every buildspec is associated to an executor which is responsible for running the test.
You can instruct buildtest to run all tests by given executor via --executor option or short option -e.
For instance, if you want to build all test associated to executor generic.local.python you can run:
$ buildtest build --executor generic.local.python
buildtest will query buildspec cache for the executor name and retrieve a list of buildspecs with matching executor name. To see a list of available executors in buildspec cache see querying buildspec executor.
Note
By default all tests are run in buildspec file. The buildtest build --executor option discovers
buildspecs if one of the test matches the executor name. The --executor option
is not filtering on test level like --filter-tags option.
In this example we run all tests that are associated to generic.local.python executor.
$ buildtest build --executor generic.local.python
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:54
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build --executor generic.local.python
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+--------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+==============================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/run_only_platform.yml |
+--------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-shell.yml |
+--------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 2
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 2
BREAKDOWN OF BUILDSPECS BY EXECUTORS
--------------------------------------
Detected Executor Names: ['generic.local.python']
+--------------------------------------------------------------------------------------------------------------+
| generic.local.python |
+==============================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/run_only_platform.yml |
+--------------------------------------------------------------------------------------------------------------+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-shell.yml |
+--------------------------------------------------------------------------------------------------------------+
[run_only_platform_darwin][/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/run_only_platform.yml]: test is skipped because this test is expected to run on platform: Darwin but detected platform: Linux.
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
-------------------------+--------------+--------------------------------------------------------------------------------------------------------------
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/run_only_platform.yml
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-shell.yml
name description
----------------------- ---------------------------------------------------
run_only_platform_linux This test will only run if target platform is Linux
circle_area Calculate circle of area given a radius
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
-------------------------+----------+--------+----------------------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
run_only_platform_linux | d018a512 | script | generic.local.python | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.python/run_only_platform/run_only_platform_linux/0/run_only_platform_linux_build.sh
circle_area | 3475676d | script | generic.local.python | ['tutorials', 'python'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.python/python-shell/circle_area/2/circle_area_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
name | id | executor | status | returncode
-------------------------+----------+----------------------+----------+--------------
run_only_platform_linux | d018a512 | generic.local.python | PASS | 0
circle_area | 3475676d | generic.local.python | PASS | 0
+----------------------+
| Stage: Test Summary |
+----------------------+
Passed Tests: 2/2 Percentage: 100.000%
Failed Tests: 0/2 Percentage: 0.000%
Writing Logfile to: /tmp/buildtest_3p596gw_.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest.log
Note
The --executor option can be appended to discover tests by multiple executors.
Discover Buildspecs¶
Now, let’s discuss how buildtest discovers buildspecs since there are several ways to build buildspecs.
The buildspec search resolution is described as follows:
If file or directory specified by
-boption doesn’t exist we exit immediately.If buildspec path is a directory, traverse directory recursively to find all
.ymlextensionsIf buildspec path is a file, check if file extension is not
.yml, exit immediatelyIf user specifies
--tagsor--executorwe search in buildspec cache to discover buildspecs.
Shown below is a diagram on how buildtest discovers buildspecs. The user can build buildspecs
by --buildspec, –tags, or –executor
which will discover the buildspecs. You can exclude buildspecs
using --exclude option which is processed after discovering buildspecs. The
excluded buildspecs are removed from list if found and final list of buildspecs
is processed.
Control builds by Stages¶
We can control behavior of buildtest build command to stop at certain phase
using --stage option. The –stage option accepts parse or build, which
will instruct buildtest to stop at parse or build phase of the pipeline.
Buildtest will validate all the buildspecs in the parse stage, so you can
instruct buildtest to stop at parse stage via --stage=parse. This can be useful
when debugging buildspecs that are invalid. In this example below, we instruct
buildtest to stop after parse stage.
$ buildtest build -b tutorials/vars.yml --stage=parse
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:55
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build -b tutorials/vars.yml --stage=parse
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+-------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+=================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/vars.yml |
+-------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
-------------------------+--------------+-------------------------------------------------------------------------------------------------
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/vars.yml
name description
-------------- -------------------------------
variables_bash Declare shell variables in bash
Likewise, if you want to troubleshoot your test script without running them you can
use --stage=build which will stop after build phase. This can
be used when you are writing buildspec to troubleshoot how test is generated.
In this next example, we inform buildtest to stop after build stage.
$ buildtest build -b tutorials/vars.yml --stage=build
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:55
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build -b tutorials/vars.yml --stage=build
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+-------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+=================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/vars.yml |
+-------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
-------------------------+--------------+-------------------------------------------------------------------------------------------------
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/vars.yml
name description
-------------- -------------------------------
variables_bash Declare shell variables in bash
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
----------------+----------+--------+--------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------
variables_bash | 521f895a | script | generic.local.bash | ['tutorials'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.bash/vars/variables_bash/2/variables_bash_build.sh
Invalid Buildspecs¶
buildtest will skip any buildspecs that fail to validate, in that case the test script will not be generated. Here is an example where we have an invalid buildspec.
$ buildtest build -b tutorials/invalid_buildspec_section.yml
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:55
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build -b tutorials/invalid_buildspec_section.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+----------------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+======================================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/invalid_buildspec_section.yml |
+----------------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
Error Messages from Stage: Parse
________________________________________________________________________________
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/invalid_buildspec_section.yml
No buildspecs to process because there are no valid buildspecs
buildtest may skip tests from running if buildspec specifies an invalid executor name since buildtest needs to know this in order to delegate test to Executor class responsible for running the test. Here is an example where test failed to run since we provided invalid executor.
$ buildtest build -b tutorials/invalid_executor.yml
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:55
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build -b tutorials/invalid_executor.yml
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+-------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+=============================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/invalid_executor.yml |
+-------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
Error Messages from Stage: Parse
________________________________________________________________________________
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/invalid_executor.yml
No buildspecs to process because there are no valid buildspecs
Rebuild Tests¶
buildtest can rebuild tests using the --rebuild option which can be useful if
you want to test a particular test multiple times. The rebuild option works across
all discovered buildspecs and create a new test instance (unique id) and test directory
path. To demonstrate we will build tutorials/python-shell.yml three times using
--rebuild=3.
$ buildtest build -b tutorials/python-shell.yml --rebuild=3
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:55
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build -b tutorials/python-shell.yml --rebuild=3
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+---------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+=========================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-shell.yml |
+---------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
-------------------------+--------------+---------------------------------------------------------------------------------------------------------
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/python-shell.yml
name description
----------- ---------------------------------------
circle_area Calculate circle of area given a radius
circle_area Calculate circle of area given a radius
circle_area Calculate circle of area given a radius
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
-------------+----------+--------+----------------------+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------
circle_area | a1f47ba1 | script | generic.local.python | ['tutorials', 'python'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.python/python-shell/circle_area/3/circle_area_build.sh
circle_area | 66d02fbd | script | generic.local.python | ['tutorials', 'python'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.python/python-shell/circle_area/4/circle_area_build.sh
circle_area | 020608ed | script | generic.local.python | ['tutorials', 'python'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.python/python-shell/circle_area/5/circle_area_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
name | id | executor | status | returncode
-------------+----------+----------------------+----------+--------------
circle_area | a1f47ba1 | generic.local.python | PASS | 0
circle_area | 66d02fbd | generic.local.python | PASS | 0
circle_area | 020608ed | generic.local.python | PASS | 0
+----------------------+
| Stage: Test Summary |
+----------------------+
Passed Tests: 3/3 Percentage: 100.000%
Failed Tests: 0/3 Percentage: 0.000%
Writing Logfile to: /tmp/buildtest_krchtpxi.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest.log
The rebuild works with all options including: --buildspec, --exclude, --tags
and --executors. buildtest will perform rebuild for all discovered tests, for instance in
this next example we will discover all tests by tag name fail and each test is rebuild twoce.
$ buildtest build -t fail --rebuild 2
User: docs
Hostname: build-14361642-project-280831-buildtest
Platform: Linux
Current Time: 2021/07/30 15:08:56
buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest
buildtest version: 0.10.0
python path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/v0.10.0/bin/python
python version: 3.6.12
Test Directory: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests
Configuration File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest/settings/config.yml
Command: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/bin/buildtest build -t fail --rebuild 2
+-------------------------------+
| Stage: Discovering Buildspecs |
+-------------------------------+
+------------------------------------------------------------------------------------------------------------+
| Discovered Buildspecs |
+============================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/pass_returncode.yml |
+------------------------------------------------------------------------------------------------------------+
Discovered Buildspecs: 1
Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
BREAKDOWN OF BUILDSPECS BY TAGS
----------------------------------
Detected Tag Names: ['fail']
+------------------------------------------------------------------------------------------------------------+
| fail |
+============================================================================================================+
| /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/pass_returncode.yml |
+------------------------------------------------------------------------------------------------------------+
+---------------------------+
| Stage: Parsing Buildspecs |
+---------------------------+
schemafile | validstate | buildspec
-------------------------+--------------+------------------------------------------------------------------------------------------------------------
script-v1.0.schema.json | True | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/tutorials/pass_returncode.yml
name description
------------------------ ---------------------------------------------------
exit1_fail exit 1 by default is FAIL
exit1_pass report exit 1 as PASS
returncode_list_mismatch exit 2 failed since it failed to match returncode 1
returncode_int_match exit 128 matches returncode 128
exit1_fail exit 1 by default is FAIL
exit1_pass report exit 1 as PASS
returncode_list_mismatch exit 2 failed since it failed to match returncode 1
returncode_int_match exit 128 matches returncode 128
+----------------------+
| Stage: Building Test |
+----------------------+
name | id | type | executor | tags | testpath
--------------------------+----------+--------+------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
exit1_fail | e1052582 | script | generic.local.sh | ['tutorials', 'fail'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/exit1_fail/3/exit1_fail_build.sh
exit1_pass | 74ba735f | script | generic.local.sh | ['tutorials', 'pass'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/exit1_pass/4/exit1_pass_build.sh
returncode_list_mismatch | 21d2f5cb | script | generic.local.sh | ['tutorials', 'fail'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/returncode_list_mismatch/3/returncode_list_mismatch_build.sh
returncode_int_match | e52db458 | script | generic.local.sh | ['tutorials', 'pass'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/returncode_int_match/4/returncode_int_match_build.sh
exit1_fail | 65444282 | script | generic.local.sh | ['tutorials', 'fail'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/exit1_fail/4/exit1_fail_build.sh
exit1_pass | 68a9fdf0 | script | generic.local.sh | ['tutorials', 'pass'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/exit1_pass/5/exit1_pass_build.sh
returncode_list_mismatch | c13bc1ff | script | generic.local.sh | ['tutorials', 'fail'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/returncode_list_mismatch/4/returncode_list_mismatch_build.sh
returncode_int_match | 6d86d63b | script | generic.local.sh | ['tutorials', 'pass'] | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/var/tests/generic.local.sh/pass_returncode/returncode_int_match/5/returncode_int_match_build.sh
+---------------------+
| Stage: Running Test |
+---------------------+
name | id | executor | status | returncode
--------------------------+----------+------------------+----------+--------------
exit1_fail | e1052582 | generic.local.sh | FAIL | 1
exit1_pass | 74ba735f | generic.local.sh | PASS | 1
returncode_list_mismatch | 21d2f5cb | generic.local.sh | FAIL | 2
returncode_int_match | e52db458 | generic.local.sh | PASS | 128
exit1_fail | 65444282 | generic.local.sh | FAIL | 1
exit1_pass | 68a9fdf0 | generic.local.sh | PASS | 1
returncode_list_mismatch | c13bc1ff | generic.local.sh | FAIL | 2
returncode_int_match | 6d86d63b | generic.local.sh | PASS | 128
+----------------------+
| Stage: Test Summary |
+----------------------+
Passed Tests: 4/8 Percentage: 50.000%
Failed Tests: 4/8 Percentage: 50.000%
Writing Logfile to: /tmp/buildtest_a0lx323f.log
A copy of logfile can be found at $BUILDTEST_ROOT/buildtest.log - /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.0/buildtest.log
The rebuild option expects a range between 1-50, the --rebuild=1 is equivalent
to running without --rebuild option. We set a max limit for rebuild option to
avoid system degredation due to high workload.
If you try to exceed this bound you will get an error such as:
.. command-output:: buildtest build -b tutorials/pass_returncode.yml --rebuild 51
Use Alternate Configuration file¶
If you want to use an alternate configuration file when building test you can use buildtest -c <config> build.
buildtest will prefer configuration file on command line over the user configuration ($HOME/.buildtest/config.yml). For more
details see Which configuration file does buildtest read?.
Keeping Stage Directory¶
buildtest will create setup the test environment in the stage directory where test will be executed. Once
test is complete, buildtest will remove the stage directory. If you
want to preserve the stage directory you can use buildtest build --keep-stage-dir, this
is only useful if you want to run the test manually