Query Test Report¶
buildtest keeps track of all tests and results in a JSON file. This file is read by buildtest report command to extract certain fields from JSON file and display them in table format. We use python tabulate library for pretty print data in tables. Shown below is command usage to query test reports.
$ buildtest report --help
usage: buildtest [options] [COMMANDS] report [-h] [--filter FILTER] [--format FORMAT] [--helpfilter] [--helpformat]
[--latest] [--oldest] [-n] [-r REPORT] [-t]
...
optional arguments:
-h, --help show this help message and exit
--filter FILTER Filter report by filter fields. The filter fields must be a key=value pair and multiple fields
can be comma separated in the following format: --filter key1=val1,key2=val2 . For list of
filter fields run: --helpfilter.
--format FORMAT format field for printing purposes. For more details see --helpformat for list of available
fields. Fields must be separated by comma (usage: --format <field1>,<field2>,...)
--helpfilter List available filter fields to be used with --filter option
--helpformat List of available format fields
--latest Retrieve latest record of particular test
--oldest Retrieve oldest record of particular test
-n, --no-header Don't print headers column used with terse option (--terse).
-r REPORT, --report REPORT
Specify a report file to read
-t, --terse Print output in machine readable format
subcommands:
Fetch test results from report file and print them in table format
clear delete report file
list List all report files
summary Summarize test report
You may run buildtest report
without any option, and buildtest will display all test results
with default format fields. To see a list of all format fields, click here.
$ buildtest report
Reading report file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/report.json
+--------------------------------+----------+---------+--------------+---------------------+---------------------+-----------+--------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| name | id | state | returncode | starttime | endtime | runtime | tags | buildspec |
+================================+==========+=========+==============+=====================+=====================+===========+====================+=====================================================================================================================================+
| variables_bash | 98b07db8 | PASS | 0 | 2021/09/09 15:54:50 | 2021/09/09 15:54:50 | 0.012987 | tutorials | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/vars.yml |
+--------------------------------+----------+---------+--------------+---------------------+---------------------+-----------+--------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| variables_bash | 7ff48178 | PASS | 0 | 2021/09/09 15:55:13 | 2021/09/09 15:55:13 | 0.042796 | tutorials | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/vars.yml |
+--------------------------------+----------+---------+--------------+---------------------+---------------------+-----------+--------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| exit1_fail | 53c2663d | FAIL | 1 | 2021/09/09 15:54:51 | 2021/09/09 15:54:51 | 0.023217 | tutorials fail | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml |
+--------------------------------+----------+---------+--------------+---------------------+---------------------+-----------+--------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| exit1_fail | aaa388f4 | FAIL | 1 | 2021/09/09 15:55:18 | 2021/09/09 15:55:18 | 0.029501 | tutorials fail | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml |
+--------------------------------+----------+---------+--------------+---------------------+---------------------+-----------+--------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| exit1_fail | 46c30f6b | FAIL | 1 | 2021/09/09 15:55:18 | 2021/09/09 15:55:18 | 0.037522 | tutorials fail | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml |
+--------------------------------+----------+---------+--------------+---------------------+---------------------+-----------+--------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| exit1_fail | 0de2fede | FAIL | 1 | 2021/09/09 15:55:22 | 2021/09/09 15:55:22 | 0.020173 | tutorials fail | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml |
+--------------------------------+----------+---------+--------------+---------------------+---------------------+-----------+--------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| exit1_fail | 69a9a391 | FAIL | 1 | 2021/09/09 15:55:22 | 2021/09/09 15:55:22 | 0.017334 | tutorials fail | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml |
+--------------------------------+----------+---------+--------------+---------------------+---------------------+-----------+--------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| exit1_pass | 97c4d576 | PASS | 1 | 2021/09/09 15:54:51 | 2021/09/09 15:54:51 | 0.020955 | tutorials pass | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml |
...
Note
buildtest rt
is an alias for buildtest report
command.
Format Reports (buildtest report --format
)¶
Available Format Fields (buildtest report --helpformat
)¶
The buildtest report command displays a default format fields that can be changed using the
--format
option. The report file (JSON) contains many more fields and we expose some of the fields
with the –format option. To see a list of available format fields you can run buildtest report --helpformat
.
This option will list all format fields with their description.
$ buildtest report --helpformat
Fields Description
---------- ----------------------------------------------------------------
buildspec Buildspec file
command Command executed
compiler Retrieve compiler used for test (applicable for compiler schema)
endtime End Time for Test in date format
errfile Error File
executor Executor name
hostname Retrieve hostname of machine where job was submitted from
full_id Full qualified unique build identifier
id Unique Build Identifier (abbreviated)
metrics List all metrics if applicable
name Name of test defined in buildspec
outfile Output file
returncode Return Code from Test Execution
runtime Total runtime in seconds
schemafile Schema file used for validation
starttime Start Time of test in date format
state Test State reported by buildtest (PASS/FAIL)
tags Tag name
testroot Root of test directory
testpath Path to test
user Get user who submitted job
Format Field Usage¶
The --format
field are specified in comma separated format (i.e --format <field1>,<field2>
).
In this example we format table by fields --format id,executor,state,returncode
.
$ buildtest rt --format name,id,executor,state,returncode
Reading report file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/report.json
+--------------------------------+----------+----------------------+---------+--------------+
| name | id | executor | state | returncode |
+================================+==========+======================+=========+==============+
| variables_bash | 98b07db8 | generic.local.bash | PASS | 0 |
+--------------------------------+----------+----------------------+---------+--------------+
| variables_bash | 7ff48178 | generic.local.bash | PASS | 0 |
+--------------------------------+----------+----------------------+---------+--------------+
| exit1_fail | 53c2663d | generic.local.sh | FAIL | 1 |
+--------------------------------+----------+----------------------+---------+--------------+
| exit1_fail | aaa388f4 | generic.local.sh | FAIL | 1 |
+--------------------------------+----------+----------------------+---------+--------------+
| exit1_fail | 46c30f6b | generic.local.sh | FAIL | 1 |
+--------------------------------+----------+----------------------+---------+--------------+
| exit1_fail | 0de2fede | generic.local.sh | FAIL | 1 |
+--------------------------------+----------+----------------------+---------+--------------+
| exit1_fail | 69a9a391 | generic.local.sh | FAIL | 1 |
+--------------------------------+----------+----------------------+---------+--------------+
| exit1_pass | 97c4d576 | generic.local.sh | PASS | 1 |
+--------------------------------+----------+----------------------+---------+--------------+
...
Filter Reports (buildtest report --filter
)¶
The buildtest report command will display all tests results, which can be quite long depending on number of tests
so therefore we need a mechanism to filter the test results. The --filter
option can be used
to filter out tests in the output based on filter fields. First, lets see the available filter fields
by run buildtest report --helpfilter
which shows a list of filter fields and their description.
$ buildtest report --helpfilter
Filter Fields Description Expected Value
--------------- -------------------------- ----------------
buildspec Filter by buildspec file FILE
name Filter by test name STRING
executor Filter by executor name STRING
state Filter by test state PASS/FAIL
tags Filter tests by tag name STRING
returncode Filter tests by returncode INT
The --filter
option expects arguments in key=value format. You can
specify multiple filter delimited by comma. buildtest will treat multiple
filters as logical AND operation. The filter option can be used with
--format
field. Let’s see some examples to illustrate the point.
Filter by returncode (--filter returncode
)¶
If you want to retrieve all tests with a given returncode, we can use the returncode
property. For instance, let’s retrieve all tests with returncode of 2 by setting --filter returncode=2
.
$ buildtest rt --filter returncode=2 --format=name,id,returncode
Reading report file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/report.json
+--------------------------+----------+--------------+
| name | id | returncode |
+==========================+==========+==============+
| returncode_list_mismatch | 31d04ee2 | 2 |
+--------------------------+----------+--------------+
| returncode_list_mismatch | 5e2d005d | 2 |
+--------------------------+----------+--------------+
| returncode_list_mismatch | 1f4bb7da | 2 |
+--------------------------+----------+--------------+
| returncode_list_mismatch | 3f3f660f | 2 |
+--------------------------+----------+--------------+
| returncode_list_mismatch | 866fd8e4 | 2 |
+--------------------------+----------+--------------+
Note
buildtest automatically converts returncode to integer when matching returncode, so --filter returncode="2"
will work too
Filter by test name (--filter name
)¶
If you want to filter by test name, use the name attribute in filter option. Let’s assume
we want to filter all tests by name exit1_pass
, this can be achieved by setting filter
field as follows: --filter name=exit1_pass
. Shown below is an example using name filter field
to filter test results.
$ buildtest rt --filter name=exit1_pass --format=name,id,returncode,state
Reading report file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/report.json
+------------+----------+--------------+---------+
| name | id | returncode | state |
+============+==========+==============+=========+
| exit1_pass | 97c4d576 | 1 | PASS |
+------------+----------+--------------+---------+
| exit1_pass | 55601e7e | 1 | PASS |
+------------+----------+--------------+---------+
| exit1_pass | b2c32941 | 1 | PASS |
+------------+----------+--------------+---------+
| exit1_pass | 80376cc8 | 1 | PASS |
+------------+----------+--------------+---------+
| exit1_pass | bdda64f7 | 1 | PASS |
+------------+----------+--------------+---------+
| exit1_pass | 6d8369a3 | 1 | PASS |
+------------+----------+--------------+---------+
Filter by buildspec (--filter buildspec
)¶
Likewise, we can filter results by buildspec file using buildspec attribute via
--filter buildspec=<file>
. The buildspec attribute must resolve to a file path which can be
relative or absolute path. buildtest will resolve path (absolute path) and find the appropriate
tests that belong to the buildspec file. If file doesn’t exist or is not found in cache it will raise an error.
$ buildtest rt --filter buildspec=tutorials/python-hello.yml --format=name,id,state,buildspec
Reading report file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/report.json
+--------------+----------+---------+---------------------------------------------------------------------------------------------------------+
| name | id | state | buildspec |
+==============+==========+=========+=========================================================================================================+
| python_hello | 6feaf262 | PASS | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/python-hello.yml |
+--------------+----------+---------+---------------------------------------------------------------------------------------------------------+
| python_hello | 3c422a2b | PASS | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/python-hello.yml |
+--------------+----------+---------+---------------------------------------------------------------------------------------------------------+
Filter by test state (--filter state
)¶
If you want to filter results by test state, use the state property. This can be
useful if you want to know all pass or failed tests. The state property expects
value of [PASS|FAIL]
since these are the two recorded test states marked by buildtest.
We can also pass multiple filter fields for instance if we want to find all FAIL
tests for executor generic.local.sh we can do the following.
$ buildtest rt --filter state=FAIL,executor=generic.local.sh --format=name,id,state,executor
Reading report file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/report.json
+--------------------------------+----------+---------+------------------+
| name | id | state | executor |
+================================+==========+=========+==================+
| exit1_fail | 53c2663d | FAIL | generic.local.sh |
+--------------------------------+----------+---------+------------------+
| exit1_fail | aaa388f4 | FAIL | generic.local.sh |
+--------------------------------+----------+---------+------------------+
| exit1_fail | 46c30f6b | FAIL | generic.local.sh |
+--------------------------------+----------+---------+------------------+
| exit1_fail | 0de2fede | FAIL | generic.local.sh |
+--------------------------------+----------+---------+------------------+
| exit1_fail | 69a9a391 | FAIL | generic.local.sh |
+--------------------------------+----------+---------+------------------+
| returncode_list_mismatch | 31d04ee2 | FAIL | generic.local.sh |
+--------------------------------+----------+---------+------------------+
| returncode_list_mismatch | 5e2d005d | FAIL | generic.local.sh |
+--------------------------------+----------+---------+------------------+
| returncode_list_mismatch | 1f4bb7da | FAIL | generic.local.sh |
+--------------------------------+----------+---------+------------------+
| returncode_list_mismatch | 3f3f660f | FAIL | generic.local.sh |
+--------------------------------+----------+---------+------------------+
| returncode_list_mismatch | 866fd8e4 | FAIL | generic.local.sh |
+--------------------------------+----------+---------+------------------+
| timelimit_min_fail | 5352acc1 | FAIL | generic.local.sh |
+--------------------------------+----------+---------+------------------+
| timelimit_max_fail | 40bee7c5 | FAIL | generic.local.sh |
+--------------------------------+----------+---------+------------------+
| status_returncode_by_executors | 912c478d | FAIL | generic.local.sh |
+--------------------------------+----------+---------+------------------+
Filter Exception Cases¶
The returncode
filter field expects an integer value, so if you try a non-integer
returncode you will get the following message
$ buildtest rt --filter returncode=1.5
Traceback (most recent call last):
File "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/bin/buildtest", line 17, in <module>
buildtest.main.main()
File "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/main.py", line 151, in main
report_cmd(args)
File "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/cli/report.py", line 670, in report_cmd
report_file=args.report,
File "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/cli/report.py", line 96, in __init__
self._check_filter_fields()
File "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/buildtest/cli/report.py", line 133, in _check_filter_fields
f"Invalid returncode:{self.filter[key]} must be an integer"
buildtest.exceptions.BuildTestError: 'Invalid returncode:1.5 must be an integer'
The state
filter field expects value of PASS
or FAIL
so if you specify an
invalid state you will get an error as follows.
$ buildtest rt --filter state=UNKNOWN
filter argument 'state' must be 'PASS' or 'FAIL' got value UNKNOWN
The buildspec
field expects a valid file path, it can be an absolute or relative
path, buildtest will resolve absolute path and check if file exist and is in the report
file. If it’s an invalid file we get an error such as
$ buildtest rt --filter buildspec=/path/to/invalid.yml
Invalid File Path for filter field 'buildspec': /path/to/invalid.yml
You may have a valid filepath for buildspec filter field such as
$BUILDTEST_ROOT/tutorials/invalid_executor.yml
, but there is no record of a test in the report cache
because this test wasn’t run. In this case you will get the following message.
$ buildtest rt --filter buildspec=$BUILDTEST_ROOT/tutorials/invalid_executor.yml
buildspec file: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/invalid_executor.yml not found in cache
Find Latest or Oldest test¶
We can search for oldest or latest test for any given test. This can be useful if you
want to see first or last test run. If you want to retrieve the oldest
test you can use --oldest
option. buildtest will append tests, therefore last
record in dictionary will be latest record, similarly first record is the oldest record.
Let’s take a look at this example, we filter by test name hello_f
which retrieves
three entries. Now let’s filter by oldest record by specifying –oldest option
and it will retrieve the first record which is test id 349f3ada.
$ buildtest report --filter name=hello_f --format name,id,starttime
Reading Report File: /Users/siddiq90/.buildtest/report.json
+---------+----------+---------------------+
| name | id | starttime |
+=========+==========+=====================+
| hello_f | 349f3ada | 2021/02/11 18:13:08 |
+---------+----------+---------------------+
| hello_f | ecd4a3f2 | 2021/02/11 18:13:18 |
+---------+----------+---------------------+
| hello_f | 5c87978b | 2021/02/11 18:13:33 |
+---------+----------+---------------------+
$ buildtest report --filter name=hello_f --format name,id,starttime --oldest
Reading Report File: /Users/siddiq90/.buildtest/report.json
+---------+----------+---------------------+
| name | id | starttime |
+=========+==========+=====================+
| hello_f | 349f3ada | 2021/02/11 18:13:08 |
+---------+----------+---------------------+
If you want to retrieve the latest test result you can use --latest
option which
will retrieve the last record, in the same example we will retrieve test id 5c87978b.
$ buildtest report --filter name=hello_f --format name,id,starttime --latest
Reading Report File: /Users/siddiq90/.buildtest/report.json
+---------+----------+---------------------+
| name | id | starttime |
+=========+==========+=====================+
| hello_f | 5c87978b | 2021/02/11 18:13:33 |
+---------+----------+---------------------+
You may combine –oldest and –latest options in same command, in this case buildtest will retrieve the first and last record of every test.
$ buildtest report --format name,id,starttime --oldest --latest | more
Reading Report File: /Users/siddiq90/.buildtest/report.json
+------------------------------+----------+---------------------+
| name | id | starttime |
+==============================+==========+=====================+
| variables_bash | 750f48bc | 2021/02/11 18:13:03 |
+------------------------------+----------+---------------------+
| variables_bash | 1bdfd403 | 2021/02/11 18:13:32 |
+------------------------------+----------+---------------------+
| ulimit_filelock_unlimited | b7b852e4 | 2021/02/11 18:13:03 |
+------------------------------+----------+---------------------+
| ulimit_filelock_unlimited | 56345a43 | 2021/02/11 18:13:18 |
+------------------------------+----------+---------------------+
Terse Output¶
If you would like to parse the result of buildtest report
, you can use the --terse
or -t
option which
will print the report in machine readable format that shows the name of each column followed by each entry. Each entry
is delimited by PIPE symbol (|
). The --terse
option works with --format
and --filter
option. In this
next example, we report all FAIL tests in terse output. The first line is the header of tables followed by
output, if you want to disable output of header you can use --no-header
option.
$ buildtest report --filter state=FAIL --format=name,id,state -t
name|id|state
exit1_fail|53c2663d|FAIL
exit1_fail|aaa388f4|FAIL
exit1_fail|46c30f6b|FAIL
exit1_fail|0de2fede|FAIL
exit1_fail|69a9a391|FAIL
returncode_list_mismatch|31d04ee2|FAIL
returncode_list_mismatch|5e2d005d|FAIL
returncode_list_mismatch|1f4bb7da|FAIL
returncode_list_mismatch|3f3f660f|FAIL
returncode_list_mismatch|866fd8e4|FAIL
status_regex_fail|099fdf40|FAIL
timelimit_min_fail|5352acc1|FAIL
timelimit_max_fail|40bee7c5|FAIL
status_returncode_by_executors|912c478d|FAIL
ulimit_stacksize_unlimited|7204f37a|FAIL
ulimit_stacksize_unlimited|f2782a7c|FAIL
ulimit_filedescriptor_4096|677a3ea5|FAIL
ulimit_filedescriptor_4096|fe1869b1|FAIL
ulimit_max_user_process_2048|81105021|FAIL
ulimit_max_user_process_2048|7d195a72|FAIL
kernel_swapusage|c6406429|FAIL
kernel_swapusage|5ef212a6|FAIL
kernel_swapusage|92b2bafa|FAIL
systemd_default_target|daaa00e7|FAIL
systemd_default_target|d016e48c|FAIL
systemd_default_target|e16f7e53|FAIL
ssh_localhost_remotecommand|d99f5389|FAIL
ssh_localhost_remotecommand|93086006|FAIL
ssh_localhost_remotecommand|c07d8422|FAIL
Report Summary (buildtest report summary
)¶
The buildtest report summary
command can be used to provide a summary of the test report
with breakdown statistics of tests including all fail tests, number of tests by name, test runs
and buildspecs in report file.
Shown below is an example output from the report summary.
$ buildtest report summary
Report: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/report.json
Total Tests: 79
Total Tests by Names: 37
Number of buildspecs in report: 22
Breakdown by Test
+--------------------------------+--------+--------+--------+
| name | runs | pass | fail |
+================================+========+========+========+
| variables_bash | 2 | 2 | 0 |
+--------------------------------+--------+--------+--------+
| exit1_fail | 5 | 0 | 5 |
+--------------------------------+--------+--------+--------+
| exit1_pass | 6 | 6 | 0 |
+--------------------------------+--------+--------+--------+
| returncode_list_mismatch | 5 | 0 | 5 |
+--------------------------------+--------+--------+--------+
| returncode_int_match | 6 | 6 | 0 |
+--------------------------------+--------+--------+--------+
| status_regex_pass | 1 | 1 | 0 |
+--------------------------------+--------+--------+--------+
| status_regex_fail | 1 | 0 | 1 |
+--------------------------------+--------+--------+--------+
| timelimit_min_max | 1 | 1 | 0 |
+--------------------------------+--------+--------+--------+
| timelimit_min | 1 | 1 | 0 |
+--------------------------------+--------+--------+--------+
| timelimit_max | 1 | 1 | 0 |
+--------------------------------+--------+--------+--------+
| timelimit_min_fail | 1 | 0 | 1 |
+--------------------------------+--------+--------+--------+
| timelimit_max_fail | 1 | 0 | 1 |
+--------------------------------+--------+--------+--------+
| bash_login_shebang | 1 | 1 | 0 |
+--------------------------------+--------+--------+--------+
| bash_nonlogin_shebang | 1 | 1 | 0 |
+--------------------------------+--------+--------+--------+
| unskipped | 1 | 1 | 0 |
+--------------------------------+--------+--------+--------+
| metric_regex_example | 1 | 1 | 0 |
+--------------------------------+--------+--------+--------+
| metric_variable_assignment | 1 | 1 | 0 |
+--------------------------------+--------+--------+--------+
| executor_regex_script_schema | 2 | 2 | 0 |
+--------------------------------+--------+--------+--------+
| executors_vars_env_declaration | 2 | 2 | 0 |
+--------------------------------+--------+--------+--------+
| executors_sbatch_declaration | 2 | 2 | 0 |
+--------------------------------+--------+--------+--------+
| status_returncode_by_executors | 2 | 1 | 1 |
+--------------------------------+--------+--------+--------+
| ulimit_filelock_unlimited | 2 | 2 | 0 |
+--------------------------------+--------+--------+--------+
| ulimit_cputime_unlimited | 2 | 2 | 0 |
+--------------------------------+--------+--------+--------+
| ulimit_stacksize_unlimited | 2 | 0 | 2 |
+--------------------------------+--------+--------+--------+
| ulimit_vmsize_unlimited | 2 | 2 | 0 |
+--------------------------------+--------+--------+--------+
| ulimit_filedescriptor_4096 | 2 | 0 | 2 |
+--------------------------------+--------+--------+--------+
| ulimit_max_user_process_2048 | 2 | 0 | 2 |
+--------------------------------+--------+--------+--------+
| kernel_swapusage | 3 | 0 | 3 |
+--------------------------------+--------+--------+--------+
| root_disk_usage | 3 | 3 | 0 |
+--------------------------------+--------+--------+--------+
| systemd_default_target | 3 | 0 | 3 |
+--------------------------------+--------+--------+--------+
| ssh_localhost_remotecommand | 3 | 0 | 3 |
+--------------------------------+--------+--------+--------+
| string_tag | 1 | 1 | 0 |
+--------------------------------+--------+--------+--------+
| list_of_strings_tags | 1 | 1 | 0 |
+--------------------------------+--------+--------+--------+
| python_hello | 2 | 2 | 0 |
+--------------------------------+--------+--------+--------+
| circle_area | 5 | 5 | 0 |
+--------------------------------+--------+--------+--------+
| run_only_platform_linux | 1 | 1 | 0 |
+--------------------------------+--------+--------+--------+
| hello_world | 1 | 1 | 0 |
+--------------------------------+--------+--------+--------+
FAIL test
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| name | id | executor | state | returncode | runtime |
+================================+==========+====================+=========+==============+===========+
| exit1_fail | 53c2663d | generic.local.sh | FAIL | 1 | 0.023217 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| exit1_fail | aaa388f4 | generic.local.sh | FAIL | 1 | 0.029501 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| exit1_fail | 46c30f6b | generic.local.sh | FAIL | 1 | 0.037522 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| exit1_fail | 0de2fede | generic.local.sh | FAIL | 1 | 0.020173 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| exit1_fail | 69a9a391 | generic.local.sh | FAIL | 1 | 0.017334 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| returncode_list_mismatch | 31d04ee2 | generic.local.sh | FAIL | 2 | 0.019587 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| returncode_list_mismatch | 5e2d005d | generic.local.sh | FAIL | 2 | 0.018428 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| returncode_list_mismatch | 1f4bb7da | generic.local.sh | FAIL | 2 | 0.017392 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| returncode_list_mismatch | 3f3f660f | generic.local.sh | FAIL | 2 | 0.019207 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| returncode_list_mismatch | 866fd8e4 | generic.local.sh | FAIL | 2 | 0.017478 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| status_regex_fail | 099fdf40 | generic.local.bash | FAIL | 0 | 0.025702 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| timelimit_min_fail | 5352acc1 | generic.local.sh | FAIL | 0 | 2.03991 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| timelimit_max_fail | 40bee7c5 | generic.local.sh | FAIL | 0 | 3.03514 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| status_returncode_by_executors | 912c478d | generic.local.sh | FAIL | 0 | 0.013939 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| ulimit_stacksize_unlimited | 7204f37a | generic.local.bash | FAIL | 0 | 0.023393 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| ulimit_stacksize_unlimited | f2782a7c | generic.local.bash | FAIL | 0 | 0.023499 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| ulimit_filedescriptor_4096 | 677a3ea5 | generic.local.bash | FAIL | 0 | 0.008116 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| ulimit_filedescriptor_4096 | fe1869b1 | generic.local.bash | FAIL | 0 | 0.027482 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| ulimit_max_user_process_2048 | 81105021 | generic.local.bash | FAIL | 0 | 0.021057 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| ulimit_max_user_process_2048 | 7d195a72 | generic.local.bash | FAIL | 0 | 0.02491 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| kernel_swapusage | c6406429 | generic.local.bash | FAIL | 127 | 0.020363 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| kernel_swapusage | 5ef212a6 | generic.local.bash | FAIL | 127 | 0.031774 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| kernel_swapusage | 92b2bafa | generic.local.bash | FAIL | 127 | 0.027239 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| systemd_default_target | daaa00e7 | generic.local.bash | FAIL | 1 | 0.040417 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| systemd_default_target | d016e48c | generic.local.bash | FAIL | 1 | 0.030873 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| systemd_default_target | e16f7e53 | generic.local.bash | FAIL | 1 | 0.027696 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| ssh_localhost_remotecommand | d99f5389 | generic.local.bash | FAIL | 255 | 0.155613 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| ssh_localhost_remotecommand | 93086006 | generic.local.bash | FAIL | 255 | 0.032854 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
| ssh_localhost_remotecommand | c07d8422 | generic.local.bash | FAIL | 255 | 0.030714 |
+--------------------------------+----------+--------------------+---------+--------------+-----------+
Inspect Tests Records via buildtest inspect
¶
Note
buildtest it
is an alias for buildtest inspect
command.
In previous examples we saw how we can retrieve test records using buildtest report
which
is printed in table format. We have limited the output to a limited fields however, if you want to analyze a particular,
we have a separate command called buildtest inspect
that can be used for inspecting a test record
based on name or id. Shown below is the command usage for buildtest inspect command.
$ buildtest inspect --help
usage: buildtest [options] [COMMANDS] inspect [-h] [-r REPORT] ...
optional arguments:
-h, --help show this help message and exit
-r REPORT, --report REPORT
Specify a report file to load when inspecting test
subcommands:
Inspect Test result based on Test ID or Test Name
buildspec Inspect a test based on buildspec
id Specify a Test ID
name Specify name of test
query Query fields from record
list List all test names, ids, and corresponding buildspecs
You can report all test names and corresponding ids using buildtest inspect list
which
will be used for querying tests by name or id.
$ buildtest inspect list
+--------------------------------+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| name | id | buildspec |
+================================+======================================+=====================================================================================================================================+
| variables_bash | 98b07db8-9b3e-4ff0-b526-1ebcebbc3a1e | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/vars.yml |
+--------------------------------+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| variables_bash | 7ff48178-2f82-4dc0-8e9b-17ce6ff0b48f | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/vars.yml |
+--------------------------------+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| exit1_fail | 53c2663d-6290-4715-bb97-eb2f8b99ff86 | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml |
+--------------------------------+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| exit1_fail | aaa388f4-6e71-4e73-aabd-4f5fb8e317ad | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml |
+--------------------------------+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| exit1_fail | 46c30f6b-5121-4715-90b8-961091a04665 | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml |
+--------------------------------+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| exit1_fail | 0de2fede-81b4-4f55-83d2-4a85e73f96b6 | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml |
+--------------------------------+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| exit1_fail | 69a9a391-cdce-4269-adb5-b844fb4ad23a | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml |
+--------------------------------+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| exit1_pass | 97c4d576-0e99-4f02-abdc-aa8b54802834 | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml |
+--------------------------------+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| exit1_pass | 55601e7e-a451-4fc0-81bb-5138115297a9 | /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml |
...
Inspecting Test by Name via buildtest inspect name
¶
The buildtest inspect name
expects a list of positional argument that correspond to name
of test you want to query and buildtest will fetch the last record for each named test. Let’s see an example to
illustrate the point. We can see that each test is stored as a JSON format and buildtest keeps track of
metadata for each test such as user, hostname, command, path to output and error file, content of test,
state of test, returncode, etc… In this example, we will retrieve record for test name circle_area which
will print the raw content of the test in JSON format.
$ buildtest it name circle_area
{
"circle_area": {
"id": "8e5d3510",
"full_id": "8e5d3510-bbe7-4140-86d7-aa168c6babec",
"description": "Calculate circle of area given a radius",
"schemafile": "script-v1.0.schema.json",
"executor": "generic.local.python",
"compiler": null,
"hostname": "build-14673784-project-280831-buildtest",
"user": "docs",
"testroot": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/8e5d3510",
"testpath": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/8e5d3510/circle_area.sh",
"stagedir": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/8e5d3510/stage",
"command": "sh circle_area_build.sh",
"outfile": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/8e5d3510/circle_area.out",
"errfile": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/8e5d3510/circle_area.err",
"buildspec_content": "version: \"1.0\"\nbuildspecs:\n circle_area:\n executor: generic.local.python\n type: script\n shell: python\n description: \"Calculate circle of area given a radius\"\n tags: [tutorials, python]\n run: |\n import math\n radius = 2\n area = math.pi * radius * radius\n print(\"Circle Radius \", radius)\n print(\"Area of circle \", area)\n",
"test_content": "#!/bin/bash\npython /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/8e5d3510/stage/circle_area.py",
"buildscript_content": "#!/bin/bash\n\n\n############# START VARIABLE DECLARATION ########################\nexport BUILDTEST_TEST_NAME=circle_area\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/8e5d3510\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/8e5d3510/stage\nexport BUILDTEST_TEST_ID=8e5d3510-bbe7-4140-86d7-aa168c6babec\n############# END VARIABLE DECLARATION ########################\n\n\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/executor/generic.local.python/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/8e5d3510/stage/circle_area.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode",
"logpath": "/tmp/buildtest_z7y7g10g.log",
"metrics": {},
"check": {
"returncode": "N/A",
"regex": "N/A",
"runtime": "N/A"
},
"tags": "tutorials python",
"starttime": "2021/09/09 15:55:22",
"endtime": "2021/09/09 15:55:22",
"runtime": "0.111269",
"state": "PASS",
"returncode": "0",
"output": "Circle Radius 2\nArea of circle 12.566370614359172\n",
"error": "circle_area_build.sh: 14: circle_area_build.sh: source: not found\n",
"job": {},
"build_script": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/8e5d3510/circle_area_build.sh"
}
}
You can query multiple tests as positional arguments in the format: buildtest inspect name <test1> <test2>
In this next example, we will retrieve test records for bash_shell
and python_hello
.
$ buildtest inspect name bash_shell python_hello
{
"python_hello": {
"id": "3c422a2b",
"full_id": "3c422a2b-81b4-4d4f-9240-1e74655d9c8e",
"description": "Hello World python",
"schemafile": "script-v1.0.schema.json",
"executor": "generic.local.bash",
"compiler": null,
"hostname": "build-14673784-project-280831-buildtest",
"user": "docs",
"testroot": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/python-hello/python_hello/3c422a2b",
"testpath": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/python-hello/python_hello/3c422a2b/python_hello.sh",
"stagedir": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/python-hello/python_hello/3c422a2b/stage",
"command": "sh python_hello_build.sh",
"outfile": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/python-hello/python_hello/3c422a2b/python_hello.out",
"errfile": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/python-hello/python_hello/3c422a2b/python_hello.err",
"buildspec_content": "version: \"1.0\"\nbuildspecs:\n python_hello:\n type: script\n description: Hello World python\n executor: generic.local.bash\n tags: python\n run: python hello.py\n\n",
"test_content": "#!/bin/bash \n# Content of run section\npython hello.py",
"buildscript_content": "#!/bin/bash\n\n\n############# START VARIABLE DECLARATION ########################\nexport BUILDTEST_TEST_NAME=python_hello\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/python-hello/python_hello/3c422a2b\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/python-hello/python_hello/3c422a2b/stage\nexport BUILDTEST_TEST_ID=3c422a2b-81b4-4d4f-9240-1e74655d9c8e\n############# END VARIABLE DECLARATION ########################\n\n\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/python-hello/python_hello/3c422a2b/stage/python_hello.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode",
"logpath": "/tmp/buildtest_tg3mt2bz.log",
"metrics": {},
"check": {
"returncode": "N/A",
"regex": "N/A",
"runtime": "N/A"
},
"tags": "python",
"starttime": "2021/09/09 15:55:18",
"endtime": "2021/09/09 15:55:18",
"runtime": "0.092008",
"state": "PASS",
"returncode": "0",
"output": "Hello World\n",
"error": "python_hello_build.sh: 14: python_hello_build.sh: source: not found\n",
"job": {},
"build_script": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/python-hello/python_hello/3c422a2b/python_hello_build.sh"
}
}
If you want to query all test records for a given name you can use the --all
option which is applied to all positional
arguments.
Inspect Test by buildspec via buildtest inspect buildspec
¶
buildtest can fetch records based on buildspec via buildtest inspect buildspec
which expects
a list of buildspecs. By default, buildtest will fetch the latest record of each test, but if you
want to fetch all records you can pass the --all
option.
In example below we will fetch latest record for all tests in tutorials/vars.yml
$ buildtest it buildspec tutorials/vars.yml
{
"/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/vars.yml": {
"variables_bash": {
"id": "7ff48178",
"full_id": "7ff48178-2f82-4dc0-8e9b-17ce6ff0b48f",
"description": "Declare shell variables in bash",
"schemafile": "script-v1.0.schema.json",
"executor": "generic.local.bash",
"compiler": null,
"hostname": "build-14673784-project-280831-buildtest",
"user": "docs",
"testroot": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178",
"testpath": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178/variables_bash.sh",
"stagedir": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178/stage",
"command": "sh variables_bash_build.sh",
"outfile": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178/variables_bash.out",
"errfile": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178/variables_bash.err",
"buildspec_content": "version: \"1.0\"\nbuildspecs:\n variables_bash:\n type: script\n executor: generic.local.bash\n description: Declare shell variables in bash\n tags: [tutorials]\n vars:\n X: 1\n Y: 2\n literalstring: |\n \"this is a literal string ':' \"\n singlequote: \\'singlequote\\'\n doublequote: \\\"doublequote\\\"\n current_user: \"$(whoami)\"\n num_files: \"`find $HOME -type f -maxdepth 1 | wc -l`\"\n\n run: |\n echo \"$X+$Y=\"$(($X+$Y))\n echo $literalstring\n echo $singlequote\n echo $doublequote\n echo \"current user:\" $current_user\n echo \"number of files:\" $num_files",
"test_content": "#!/bin/bash \n# Declare shell variables\nX=1\nY=2\nliteralstring=\"this is a literal string ':' \"\n\nsinglequote=\\'singlequote\\'\ndoublequote=\\\"doublequote\\\"\ncurrent_user=$(whoami)\nnum_files=`find $HOME -type f -maxdepth 1 | wc -l`\n\n\n# Content of run section\necho \"$X+$Y=\"$(($X+$Y))\necho $literalstring\necho $singlequote\necho $doublequote\necho \"current user:\" $current_user\necho \"number of files:\" $num_files",
"buildscript_content": "#!/bin/bash\n\n\n############# START VARIABLE DECLARATION ########################\nexport BUILDTEST_TEST_NAME=variables_bash\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178/stage\nexport BUILDTEST_TEST_ID=7ff48178-2f82-4dc0-8e9b-17ce6ff0b48f\n############# END VARIABLE DECLARATION ########################\n\n\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178/stage/variables_bash.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode",
"logpath": "/tmp/buildtest_hkdfz2sm.log",
"metrics": {},
"check": {
"returncode": "N/A",
"regex": "N/A",
"runtime": "N/A"
},
"tags": "tutorials",
"starttime": "2021/09/09 15:55:13",
"endtime": "2021/09/09 15:55:13",
"runtime": "0.042796",
"state": "PASS",
"returncode": "0",
"output": "1+2=3\nthis is a literal string ':'\n'singlequote'\n\"doublequote\"\ncurrent user: docs\nnumber of files: 4\n",
"error": "variables_bash_build.sh: 14: variables_bash_build.sh: source: not found\n",
"job": {},
"build_script": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178/variables_bash_build.sh"
}
}
}
buildtest will report an error if an input buildspec is invalid filepath such as one below
$ buildtest it buildspec /tmp/buildspec.yml
buildspec: /tmp/buildspec.yml is not valid file
There are no buildspecs in cache based on input buildspecs: ['/tmp/buildspec.yml']
You can also pass multiple buildspes on the command line and fetch all records for a test. In example below we will fetch all records from buildspecs tutorials/vars.yml and tutorials/status_regex.yml
$ buildtest it buildspec --all tutorials/vars.yml tutorials/status_regex.yml
{
"/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/vars.yml": {
"variables_bash": [
{
"id": "98b07db8",
"full_id": "98b07db8-9b3e-4ff0-b526-1ebcebbc3a1e",
"description": "Declare shell variables in bash",
"schemafile": "script-v1.0.schema.json",
"executor": "generic.local.bash",
"compiler": null,
"hostname": "build-14673784-project-280831-buildtest",
"user": "docs",
"testroot": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/98b07db8",
"testpath": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/98b07db8/variables_bash.sh",
"stagedir": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/98b07db8/stage",
"command": "sh variables_bash_build.sh",
"outfile": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/98b07db8/variables_bash.out",
"errfile": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/98b07db8/variables_bash.err",
"buildspec_content": "version: \"1.0\"\nbuildspecs:\n variables_bash:\n type: script\n executor: generic.local.bash\n description: Declare shell variables in bash\n tags: [tutorials]\n vars:\n X: 1\n Y: 2\n literalstring: |\n \"this is a literal string ':' \"\n singlequote: \\'singlequote\\'\n doublequote: \\\"doublequote\\\"\n current_user: \"$(whoami)\"\n num_files: \"`find $HOME -type f -maxdepth 1 | wc -l`\"\n\n run: |\n echo \"$X+$Y=\"$(($X+$Y))\n echo $literalstring\n echo $singlequote\n echo $doublequote\n echo \"current user:\" $current_user\n echo \"number of files:\" $num_files",
"test_content": "#!/bin/bash \n# Declare shell variables\nX=1\nY=2\nliteralstring=\"this is a literal string ':' \"\n\nsinglequote=\\'singlequote\\'\ndoublequote=\\\"doublequote\\\"\ncurrent_user=$(whoami)\nnum_files=`find $HOME -type f -maxdepth 1 | wc -l`\n\n\n# Content of run section\necho \"$X+$Y=\"$(($X+$Y))\necho $literalstring\necho $singlequote\necho $doublequote\necho \"current user:\" $current_user\necho \"number of files:\" $num_files",
"buildscript_content": "#!/bin/bash\n\n\n############# START VARIABLE DECLARATION ########################\nexport BUILDTEST_TEST_NAME=variables_bash\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/98b07db8\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/98b07db8/stage\nexport BUILDTEST_TEST_ID=98b07db8-9b3e-4ff0-b526-1ebcebbc3a1e\n############# END VARIABLE DECLARATION ########################\n\n\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/98b07db8/stage/variables_bash.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode",
"logpath": "/tmp/buildtest_8xn_louq.log",
"metrics": {},
"check": {
"returncode": "N/A",
"regex": "N/A",
"runtime": "N/A"
},
"tags": "tutorials",
"starttime": "2021/09/09 15:54:50",
"endtime": "2021/09/09 15:54:50",
"runtime": "0.012987",
"state": "PASS",
"returncode": "0",
"output": "1+2=3\nthis is a literal string ':'\n'singlequote'\n\"doublequote\"\ncurrent user: docs\nnumber of files: 4\n",
"error": "variables_bash_build.sh: 14: variables_bash_build.sh: source: not found\n",
"job": {},
"build_script": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/98b07db8/variables_bash_build.sh"
},
{
"id": "7ff48178",
"full_id": "7ff48178-2f82-4dc0-8e9b-17ce6ff0b48f",
"description": "Declare shell variables in bash",
"schemafile": "script-v1.0.schema.json",
"executor": "generic.local.bash",
"compiler": null,
"hostname": "build-14673784-project-280831-buildtest",
"user": "docs",
"testroot": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178",
"testpath": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178/variables_bash.sh",
"stagedir": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178/stage",
"command": "sh variables_bash_build.sh",
"outfile": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178/variables_bash.out",
"errfile": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178/variables_bash.err",
"buildspec_content": "version: \"1.0\"\nbuildspecs:\n variables_bash:\n type: script\n executor: generic.local.bash\n description: Declare shell variables in bash\n tags: [tutorials]\n vars:\n X: 1\n Y: 2\n literalstring: |\n \"this is a literal string ':' \"\n singlequote: \\'singlequote\\'\n doublequote: \\\"doublequote\\\"\n current_user: \"$(whoami)\"\n num_files: \"`find $HOME -type f -maxdepth 1 | wc -l`\"\n\n run: |\n echo \"$X+$Y=\"$(($X+$Y))\n echo $literalstring\n echo $singlequote\n echo $doublequote\n echo \"current user:\" $current_user\n echo \"number of files:\" $num_files",
"test_content": "#!/bin/bash \n# Declare shell variables\nX=1\nY=2\nliteralstring=\"this is a literal string ':' \"\n\nsinglequote=\\'singlequote\\'\ndoublequote=\\\"doublequote\\\"\ncurrent_user=$(whoami)\nnum_files=`find $HOME -type f -maxdepth 1 | wc -l`\n\n\n# Content of run section\necho \"$X+$Y=\"$(($X+$Y))\necho $literalstring\necho $singlequote\necho $doublequote\necho \"current user:\" $current_user\necho \"number of files:\" $num_files",
"buildscript_content": "#!/bin/bash\n\n\n############# START VARIABLE DECLARATION ########################\nexport BUILDTEST_TEST_NAME=variables_bash\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178/stage\nexport BUILDTEST_TEST_ID=7ff48178-2f82-4dc0-8e9b-17ce6ff0b48f\n############# END VARIABLE DECLARATION ########################\n\n\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178/stage/variables_bash.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode",
"logpath": "/tmp/buildtest_hkdfz2sm.log",
"metrics": {},
"check": {
"returncode": "N/A",
"regex": "N/A",
"runtime": "N/A"
},
"tags": "tutorials",
"starttime": "2021/09/09 15:55:13",
"endtime": "2021/09/09 15:55:13",
"runtime": "0.042796",
"state": "PASS",
"returncode": "0",
"output": "1+2=3\nthis is a literal string ':'\n'singlequote'\n\"doublequote\"\ncurrent user: docs\nnumber of files: 4\n",
"error": "variables_bash_build.sh: 14: variables_bash_build.sh: source: not found\n",
"job": {},
"build_script": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/vars/variables_bash/7ff48178/variables_bash_build.sh"
}
]
},
"/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/status_regex.yml": {
"status_regex_pass": [
{
"id": "572fadd5",
"full_id": "572fadd5-b0eb-4df3-aa2f-d878aeb2522d",
"description": "Pass test based on regular expression",
"schemafile": "script-v1.0.schema.json",
"executor": "generic.local.bash",
"compiler": null,
"hostname": "build-14673784-project-280831-buildtest",
"user": "docs",
"testroot": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_pass/572fadd5",
"testpath": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_pass/572fadd5/status_regex_pass.sh",
"stagedir": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_pass/572fadd5/stage",
"command": "sh status_regex_pass_build.sh",
"outfile": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_pass/572fadd5/status_regex_pass.out",
"errfile": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_pass/572fadd5/status_regex_pass.err",
"buildspec_content": "version: \"1.0\"\nbuildspecs:\n status_regex_pass:\n executor: generic.local.bash\n type: script\n tags: [system]\n description: Pass test based on regular expression\n run: echo \"PASS\"\n status:\n regex:\n stream: stdout\n exp: \"^(PASS)$\"\n\n status_regex_fail:\n executor: generic.local.bash\n type: script\n tags: [system]\n description: Pass test based on regular expression\n run: echo \"FAIL\"\n status:\n regex:\n stream: stdout\n exp: \"^(123FAIL)$\"",
"test_content": "#!/bin/bash \n# Content of run section\necho \"PASS\"",
"buildscript_content": "#!/bin/bash\n\n\n############# START VARIABLE DECLARATION ########################\nexport BUILDTEST_TEST_NAME=status_regex_pass\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_pass/572fadd5\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_pass/572fadd5/stage\nexport BUILDTEST_TEST_ID=572fadd5-b0eb-4df3-aa2f-d878aeb2522d\n############# END VARIABLE DECLARATION ########################\n\n\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_pass/572fadd5/stage/status_regex_pass.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode",
"logpath": "/tmp/buildtest_veh1ta6l.log",
"metrics": {},
"check": {
"returncode": false,
"regex": true,
"runtime": false
},
"tags": "system",
"starttime": "2021/09/09 15:54:51",
"endtime": "2021/09/09 15:54:51",
"runtime": "0.025703",
"state": "PASS",
"returncode": "0",
"output": "PASS\n",
"error": "status_regex_pass_build.sh: 14: status_regex_pass_build.sh: source: not found\n",
"job": {},
"build_script": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_pass/572fadd5/status_regex_pass_build.sh"
}
],
"status_regex_fail": [
{
"id": "099fdf40",
"full_id": "099fdf40-fac6-4581-ab96-780328380d58",
"description": "Pass test based on regular expression",
"schemafile": "script-v1.0.schema.json",
"executor": "generic.local.bash",
"compiler": null,
"hostname": "build-14673784-project-280831-buildtest",
"user": "docs",
"testroot": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_fail/099fdf40",
"testpath": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_fail/099fdf40/status_regex_fail.sh",
"stagedir": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_fail/099fdf40/stage",
"command": "sh status_regex_fail_build.sh",
"outfile": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_fail/099fdf40/status_regex_fail.out",
"errfile": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_fail/099fdf40/status_regex_fail.err",
"buildspec_content": "version: \"1.0\"\nbuildspecs:\n status_regex_pass:\n executor: generic.local.bash\n type: script\n tags: [system]\n description: Pass test based on regular expression\n run: echo \"PASS\"\n status:\n regex:\n stream: stdout\n exp: \"^(PASS)$\"\n\n status_regex_fail:\n executor: generic.local.bash\n type: script\n tags: [system]\n description: Pass test based on regular expression\n run: echo \"FAIL\"\n status:\n regex:\n stream: stdout\n exp: \"^(123FAIL)$\"",
"test_content": "#!/bin/bash \n# Content of run section\necho \"FAIL\"",
"buildscript_content": "#!/bin/bash\n\n\n############# START VARIABLE DECLARATION ########################\nexport BUILDTEST_TEST_NAME=status_regex_fail\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_fail/099fdf40\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_fail/099fdf40/stage\nexport BUILDTEST_TEST_ID=099fdf40-fac6-4581-ab96-780328380d58\n############# END VARIABLE DECLARATION ########################\n\n\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_fail/099fdf40/stage/status_regex_fail.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode",
"logpath": "/tmp/buildtest_veh1ta6l.log",
"metrics": {},
"check": {
"returncode": false,
"regex": false,
"runtime": false
},
"tags": "system",
"starttime": "2021/09/09 15:54:51",
"endtime": "2021/09/09 15:54:51",
"runtime": "0.025702",
"state": "FAIL",
"returncode": "0",
"output": "FAIL\n",
"error": "status_regex_fail_build.sh: 14: status_regex_fail_build.sh: source: not found\n",
"job": {},
"build_script": "/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/status_regex/status_regex_fail/099fdf40/status_regex_fail_build.sh"
}
]
}
}
Note
If you pass a valid filepath but file is not in cache you will get an error as follows
$ buildtest it buildspec $BUILDTEST_ROOT/README.rst
Unable to find any buildspecs in cache, please specify one of the following buildspecs:
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/vars.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/pass_returncode.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/status_regex.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/runtime_status_test.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/shebang.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/skip_tests.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/metrics_regex.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/metrics_variable.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/executor_regex_script.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/script/multiple_executors.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/script/executor_scheduler.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/script/status_by_executors.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/general_tests/configuration/ulimits.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/general_tests/configuration/kernel_state.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/general_tests/configuration/disk_usage.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/general_tests/configuration/systemd-default-target.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/general_tests/configuration/ssh_localhost.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/tags_example.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/python-hello.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/python-shell.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/run_only_platform.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials/hello_world.yml
Inspecting Test by ID via buildtest inspect id
¶
The buildtest inspect id
works similar to buildtest inspect name
except that it
operates on test id. This can be useful if you want to extract a particular test record and not
see all test records at once.
You only need to specify a few characters and buildtest will resolve full test id if there is a match.
The buildtest inspect id
can operate on single or multiple ids if you want to specify multiple
ids in single command you can do buildtest inspect id <identifier1> <identifier2>
.
$ buildtest it id a76
{
"a761ce8f-0442-4ff4-845b-8d7cbd6b563b": {
"id": "a761ce8f",
"full_id": "a761ce8f-0442-4ff4-845b-8d7cbd6b563b",
"description": "hello world example",
"schemafile": "script-v1.0.schema.json",
"executor": "generic.local.bash",
"compiler": null,
"hostname": "DOE-7086392.local",
"user": "siddiq90",
"testroot": "/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/hello_world/hello_world/a761ce8f",
"testpath": "/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/hello_world/hello_world/a761ce8f/hello_world.sh",
"stagedir": "/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/hello_world/hello_world/a761ce8f/stage",
"command": "sh hello_world_build.sh",
"outfile": "/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/hello_world/hello_world/a761ce8f/hello_world.out",
"errfile": "/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/hello_world/hello_world/a761ce8f/hello_world.err",
"buildspec_content": "version: \"1.0\"\nbuildspecs:\n hello_world:\n executor: generic.local.bash\n type: script\n tags: tutorials\n description: \"hello world example\"\n run: echo \"hello world!\"\nmaintainers:\n- \"@shahzebsiddiqui\"\n",
"test_content": "#!/bin/bash \n# Content of run section\necho \"hello world!\"",
"buildscript_content": "#!/bin/bash\n\n\n############# START VARIABLE DECLARATION ########################\nexport BUILDTEST_TEST_NAME=hello_world\nexport BUILDTEST_TEST_ROOT=/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/hello_world/hello_world/a761ce8f\nexport BUILDTEST_BUILDSPEC_DIR=/Users/siddiq90/Documents/GitHubDesktop/buildtest/tutorials\nexport BUILDTEST_STAGE_DIR=/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/hello_world/hello_world/a761ce8f/stage\nexport BUILDTEST_TEST_ID=a761ce8f-0442-4ff4-845b-8d7cbd6b563b\n############# END VARIABLE DECLARATION ########################\n\n\n# source executor startup script\nsource /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/hello_world/hello_world/a761ce8f/stage/hello_world.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode",
"logpath": "/var/folders/1m/_jjv09h17k37mkktwnmbkmj0002t_q/T/buildtest_fcwkh482.log",
"metrics": {},
"tags": "tutorials",
"starttime": "2021/08/19 11:12:32",
"endtime": "2021/08/19 11:12:32",
"runtime": "0.103966",
"state": "PASS",
"returncode": "0",
"output": "hello world!\n",
"error": "",
"job": {},
"build_script": "/Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/hello_world/hello_world/a761ce8f/hello_world_build.sh"
}
}
If you specify an invalid test id using buildtest inspect id
you will get an error
message as follows.
$ buildtest inspect id lad
Unable to find any test records based on id: ['lad'], please run 'buildtest inspect list' to see list of ids.
You will see similar message if you specify an invalid test name using buildtest inspect name
command.
Query Test Records via buildtest inspect query
¶
The buildtest inspect query
command can allow you to retrieve query certain fields from
each test records that can be useful when you are inspecting a test. Currently, we can
fetch content of output file, error file, testpath, and build script. Shown below are the list
of available options for buildtest inspect query
.
$ buildtest inspect query --help
usage: buildtest [options] [COMMANDS] inspect query [-h] [-b] [-d {first,last,all}] [-e] [-o] [-t] [name [name ...]]
positional arguments:
name Name of test
optional arguments:
-h, --help show this help message and exit
-b, --buildscript Print build script
-d {first,last,all}, --display {first,last,all}
Determine how records are fetched, by default it will report the last record of the test.
-e, --error Print error file
-o, --output Print output file
-t, --testpath Print content of testpath
The buildtest inspect query
command expects positional arguments that are name of tests
which you can get by running buildtest inspect list
.
For instance, let’s query the test circle_area
by running the following:
$ buildtest inspect query circle_area
______________________________ circle_area (ID: 8e5d3510-bbe7-4140-86d7-aa168c6babec) ______________________________
executor: generic.local.python
description: Calculate circle of area given a radius
state: PASS
returncode: 0
runtime: 0.111269
starttime: 2021/09/09 15:55:22
endtime: 2021/09/09 15:55:22
buildtest will display metadata for each test. By default, buildtest will report the latest record
for each test that is specified as a positional argument. If you want to see all runs for a particular test
you can use -d all
or --display all
which will report all records. By default, it will use -d last
which
reports the last record. You can retrieve the first record by running -d first
which is the oldest record.
Now as you run test, you want to inspect the output file, this can be done by passing -o
or --output
. Let’s take
what we learned and see the following. In this command, we retrieve all records for circle_area
and
print content of output file
$ buildtest inspect query -d all -o circle_area
______________________________ circle_area (ID: 6ed8bf63-8008-42c7-9416-7e472c15c9e4) ______________________________
executor: generic.local.python
description: Calculate circle of area given a radius
state: PASS
returncode: 0
runtime: 0.116362
starttime: 2021/09/09 15:55:18
endtime: 2021/09/09 15:55:18
************************* Start of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/6ed8bf63/circle_area.out *************************
Circle Radius 2
Area of circle 12.566370614359172
************************* End of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/6ed8bf63/circle_area.out *************************
______________________________ circle_area (ID: 29fd70b3-2bd5-45a0-96af-0b62e394c87e) ______________________________
executor: generic.local.python
description: Calculate circle of area given a radius
state: PASS
returncode: 0
runtime: 0.115076
starttime: 2021/09/09 15:55:19
endtime: 2021/09/09 15:55:19
************************* Start of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/29fd70b3/circle_area.out *************************
Circle Radius 2
Area of circle 12.566370614359172
************************* End of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/29fd70b3/circle_area.out *************************
______________________________ circle_area (ID: f5c50ca7-2ac3-43b0-a59f-1d88eb00f3de) ______________________________
executor: generic.local.python
description: Calculate circle of area given a radius
state: PASS
returncode: 0
runtime: 0.10842
starttime: 2021/09/09 15:55:22
endtime: 2021/09/09 15:55:22
************************* Start of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/f5c50ca7/circle_area.out *************************
Circle Radius 2
Area of circle 12.566370614359172
************************* End of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/f5c50ca7/circle_area.out *************************
______________________________ circle_area (ID: 629ee0a6-94c3-4e62-b05c-964f92c15f0a) ______________________________
executor: generic.local.python
description: Calculate circle of area given a radius
state: PASS
returncode: 0
runtime: 0.040307
starttime: 2021/09/09 15:55:22
endtime: 2021/09/09 15:55:22
************************* Start of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/629ee0a6/circle_area.out *************************
Circle Radius 2
Area of circle 12.566370614359172
************************* End of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/629ee0a6/circle_area.out *************************
______________________________ circle_area (ID: 8e5d3510-bbe7-4140-86d7-aa168c6babec) ______________________________
executor: generic.local.python
description: Calculate circle of area given a radius
state: PASS
returncode: 0
runtime: 0.111269
starttime: 2021/09/09 15:55:22
endtime: 2021/09/09 15:55:22
************************* Start of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/8e5d3510/circle_area.out *************************
Circle Radius 2
Area of circle 12.566370614359172
************************* End of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/8e5d3510/circle_area.out *************************
If you want to see content of error file use the -e
or --error
flag. It would be useful to inspect
content of build script and generated test, which can be retrieved using --testpath
and --buildscript
. Let’s
see query the first record of circle_area
and report all of the content fields
$ buildtest inspect query -d first -o -e -t -b circle_area
______________________________ circle_area (ID: 6ed8bf63-8008-42c7-9416-7e472c15c9e4) ______________________________
executor: generic.local.python
description: Calculate circle of area given a radius
state: PASS
returncode: 0
runtime: 0.116362
starttime: 2021/09/09 15:55:18
endtime: 2021/09/09 15:55:18
************************* Start of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/6ed8bf63/circle_area.out *************************
Circle Radius 2
Area of circle 12.566370614359172
************************* End of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/6ed8bf63/circle_area.out *************************
************************* Start of Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/6ed8bf63/circle_area.err *************************
circle_area_build.sh: 14: circle_area_build.sh: source: not found
************************* End of Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/6ed8bf63/circle_area.err *************************
************************* Start of Test Path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/6ed8bf63/circle_area.sh *************************
#!/bin/bash
python /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/6ed8bf63/stage/circle_area.py
************************* End of Test Path: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/6ed8bf63/circle_area.sh *************************
************************* Start of Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/6ed8bf63/circle_area_build.sh *************************
#!/bin/bash
############# START VARIABLE DECLARATION ########################
export BUILDTEST_TEST_NAME=circle_area
export BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/6ed8bf63
export BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/tutorials
export BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/6ed8bf63/stage
export BUILDTEST_TEST_ID=6ed8bf63-8008-42c7-9416-7e472c15c9e4
############# END VARIABLE DECLARATION ########################
# source executor startup script
source /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/executor/generic.local.python/before_script.sh
# Run generated script
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/6ed8bf63/stage/circle_area.sh
# Get return code
returncode=$?
# Exit with return code
exit $returncode
************************* End of Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.python/python-shell/circle_area/6ed8bf63/circle_area_build.sh *************************
We can query multiple tests using buildtest inspect query
since each test is a positional argument. Any
options specified to buildtest inspect query will be applied to all test. For instance, let’s fetch the output the
of test names root_disk_usage
and python_hello
$ buildtest inspect query -o root_disk_usage python_hello
______________________________ root_disk_usage (ID: 1cd41359-a069-43ea-8807-2b6f256c34e3) ______________________________
executor: generic.local.bash
description: Check root disk usage and report if it exceeds threshold
state: PASS
returncode: 0
runtime: 0.037134
starttime: 2021/09/09 15:55:14
endtime: 2021/09/09 15:55:14
************************* Start of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/disk_usage/root_disk_usage/1cd41359/root_disk_usage.out *************************
[OK] Root disk is below threshold of 90%
************************* End of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/disk_usage/root_disk_usage/1cd41359/root_disk_usage.out *************************
______________________________ python_hello (ID: 3c422a2b-81b4-4d4f-9240-1e74655d9c8e) ______________________________
executor: generic.local.bash
description: Hello World python
state: PASS
returncode: 0
runtime: 0.092008
starttime: 2021/09/09 15:55:18
endtime: 2021/09/09 15:55:18
************************* Start of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/python-hello/python_hello/3c422a2b/python_hello.out *************************
Hello World
************************* End of Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.11.0/var/tests/generic.local.bash/python-hello/python_hello/3c422a2b/python_hello.out *************************
Using Alternate Report File¶
The buildtest report
and buildtest inspect
command will read from the report file tracked by buildtest which is
stored in $BUILDTEST_ROOT/var/report.json. This single file can became an issue if you are running jobs through CI where you
can potentially overwrite same file or if you want separate report files for each set of builds. Luckily we have an option to handle
this using the buildtest build -r /path/to/report
option which can be used to specify an alternate location to report file.
buildtest will write the report file in the desired location, then you can specify the path to report file via
buildtest report -r /path/to/report
and buildtest inspect -r /path/to/report
to load the report file when reporting tests.
The report file must be valid JSON file that buildtest understands in order to use buildtest report and
buildtest inspect command. Shown below are some examples using the alternate report file using buildtest report
and
buildtest inspect
command.
$ buildtest report -r python.json --format name,id
Reading report file: /Users/siddiq90/Documents/GitHubDesktop/buildtest/docs/python.json
+--------------+----------+
| name | id |
+==============+==========+
| circle_area | 6be6c404 |
+--------------+----------+
| python_hello | f21ba744 |
+--------------+----------+
$ buildtest inspect -r test.json name variables_bash
Reading Report File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/test.json
{
"variables_bash": [
{
"id": "cd0511ce",
"full_id": "cd0511ce-377e-4ed2-95f4-f244e5518732",
"schemafile": "script-v1.0.schema.json",
"executor": "generic.local.bash",
"compiler": null,
"hostname": "DOE-7086392.local",
"user": "siddiq90",
"testroot": "/Users/siddiq90/.buildtest/var/tests/generic.local.bash/vars/variables_bash/1",
"testpath": "/Users/siddiq90/.buildtest/var/tests/generic.local.bash/vars/variables_bash/1/stage/generate.sh",
"stagedir": "/Users/siddiq90/.buildtest/var/tests/generic.local.bash/vars/variables_bash/1/stage",
"rundir": "/Users/siddiq90/.buildtest/var/tests/generic.local.bash/vars/variables_bash/1/run",
"command": "/Users/siddiq90/.buildtest/var/tests/generic.local.bash/vars/variables_bash/1/stage/generate.sh",
"outfile": "/Users/siddiq90/.buildtest/var/tests/generic.local.bash/vars/variables_bash/1/run/variables_bash.out",
"errfile": "/Users/siddiq90/.buildtest/var/tests/generic.local.bash/vars/variables_bash/1/run/variables_bash.err",
"buildspec_content": "version: \"1.0\"\nbuildspecs:\n variables_bash:\n type: script\n executor: generic.local.bash\n description: Declare shell variables in bash\n tags: [tutorials]\n vars:\n X: 1\n Y: 2\n literalstring: |\n \"this is a literal string ':' \"\n singlequote: \"'singlequote'\"\n doublequote: \"\\\"doublequote\\\"\"\n current_user: \"$(whoami)\"\n files_homedir: \"`find $HOME -type f -maxdepth 1`\"\n\n run: |\n echo \"$X+$Y=\" $(($X+$Y))\n echo $literalstring\n echo $singlequote\n echo $doublequote\n\n echo $current_user\n echo $files_homedir",
"test_content": "#!/bin/bash \nsource /Users/siddiq90/.buildtest/executor/generic.local.bash/before_script.sh\nX=1\nY=2\nliteralstring=\"this is a literal string ':' \"\n\nsinglequote='singlequote'\ndoublequote=\"doublequote\"\ncurrent_user=$(whoami)\nfiles_homedir=`find $HOME -type f -maxdepth 1`\necho \"$X+$Y=\" $(($X+$Y))\necho $literalstring\necho $singlequote\necho $doublequote\n\necho $current_user\necho $files_homedir\nsource /Users/siddiq90/.buildtest/executor/generic.local.bash/after_script.sh",
"tags": "tutorials",
"starttime": "2021/04/16 14:29:25",
"endtime": "2021/04/16 14:29:25",
"runtime": 0.213196,
"state": "PASS",
"returncode": 0,
"output": "1+2= 3\nthis is a literal string ':'\nsinglequote\ndoublequote\nsiddiq90\n/Users/siddiq90/buildtest_e7yxgttm.log /Users/siddiq90/.anyconnect /Users/siddiq90/buildtest_utwigb8w.log /Users/siddiq90/.DS_Store /Users/siddiq90/.serverauth.555 /Users/siddiq90/.CFUserTextEncoding /Users/siddiq90/.wget-hsts /Users/siddiq90/.bashrc /Users/siddiq90/.zshrc /Users/siddiq90/.coverage /Users/siddiq90/.serverauth.87055 /Users/siddiq90/buildtest_r7bck5zh.log /Users/siddiq90/.zsh_history /Users/siddiq90/.lesshst /Users/siddiq90/calltracker.py /Users/siddiq90/.git-completion.bash /Users/siddiq90/buildtest_wvjaaztp.log /Users/siddiq90/buildtest.log /Users/siddiq90/darhan.log /Users/siddiq90/ascent.yml /Users/siddiq90/.cshrc /Users/siddiq90/buildtest_nyq22whj.log /Users/siddiq90/github-tokens /Users/siddiq90/buildtest_ozb8b52z.log /Users/siddiq90/.zcompdump /Users/siddiq90/buildtest_nab_ckph.log /Users/siddiq90/.serverauth.543 /Users/siddiq90/.s.PGSQL.15007.lock /Users/siddiq90/.bash_profile /Users/siddiq90/.Xauthority /Users/siddiq90/.python_history /Users/siddiq90/.gitconfig /Users/siddiq90/output.txt /Users/siddiq90/.bash_history /Users/siddiq90/.viminfo\n",
"error": "",
"job": null
},
{
"id": "e0901505",
"full_id": "e0901505-a66b-4c91-9b29-d027cb6fabb6",
"schemafile": "script-v1.0.schema.json",
"executor": "generic.local.bash",
"compiler": null,
"hostname": "DOE-7086392.local",
"user": "siddiq90",
"testroot": "/Users/siddiq90/.buildtest/var/tests/generic.local.bash/vars/variables_bash/2",
"testpath": "/Users/siddiq90/.buildtest/var/tests/generic.local.bash/vars/variables_bash/2/stage/generate.sh",
"stagedir": "/Users/siddiq90/.buildtest/var/tests/generic.local.bash/vars/variables_bash/2/stage",
"rundir": "/Users/siddiq90/.buildtest/var/tests/generic.local.bash/vars/variables_bash/2/run",
"command": "/Users/siddiq90/.buildtest/var/tests/generic.local.bash/vars/variables_bash/2/stage/generate.sh",
"outfile": "/Users/siddiq90/.buildtest/var/tests/generic.local.bash/vars/variables_bash/2/run/variables_bash.out",
"errfile": "/Users/siddiq90/.buildtest/var/tests/generic.local.bash/vars/variables_bash/2/run/variables_bash.err",
"buildspec_content": "version: \"1.0\"\nbuildspecs:\n variables_bash:\n type: script\n executor: generic.local.bash\n description: Declare shell variables in bash\n tags: [tutorials]\n vars:\n X: 1\n Y: 2\n literalstring: |\n \"this is a literal string ':' \"\n singlequote: \"'singlequote'\"\n doublequote: \"\\\"doublequote\\\"\"\n current_user: \"$(whoami)\"\n files_homedir: \"`find $HOME -type f -maxdepth 1`\"\n\n run: |\n echo \"$X+$Y=\" $(($X+$Y))\n echo $literalstring\n echo $singlequote\n echo $doublequote\n\n echo $current_user\n echo $files_homedir",
"test_content": "#!/bin/bash \nsource /Users/siddiq90/.buildtest/executor/generic.local.bash/before_script.sh\nX=1\nY=2\nliteralstring=\"this is a literal string ':' \"\n\nsinglequote='singlequote'\ndoublequote=\"doublequote\"\ncurrent_user=$(whoami)\nfiles_homedir=`find $HOME -type f -maxdepth 1`\necho \"$X+$Y=\" $(($X+$Y))\necho $literalstring\necho $singlequote\necho $doublequote\n\necho $current_user\necho $files_homedir\nsource /Users/siddiq90/.buildtest/executor/generic.local.bash/after_script.sh",
"tags": "tutorials",
"starttime": "2021/04/16 14:29:58",
"endtime": "2021/04/16 14:29:58",
"runtime": 0.075224,
"state": "PASS",
"returncode": 0,
"output": "1+2= 3\nthis is a literal string ':'\nsinglequote\ndoublequote\nsiddiq90\n/Users/siddiq90/buildtest_e7yxgttm.log /Users/siddiq90/.anyconnect /Users/siddiq90/buildtest_utwigb8w.log /Users/siddiq90/.DS_Store /Users/siddiq90/.serverauth.555 /Users/siddiq90/.CFUserTextEncoding /Users/siddiq90/.wget-hsts /Users/siddiq90/.bashrc /Users/siddiq90/.zshrc /Users/siddiq90/.coverage /Users/siddiq90/.serverauth.87055 /Users/siddiq90/buildtest_r7bck5zh.log /Users/siddiq90/.zsh_history /Users/siddiq90/.lesshst /Users/siddiq90/calltracker.py /Users/siddiq90/.git-completion.bash /Users/siddiq90/buildtest_wvjaaztp.log /Users/siddiq90/buildtest.log /Users/siddiq90/darhan.log /Users/siddiq90/ascent.yml /Users/siddiq90/.cshrc /Users/siddiq90/buildtest_nyq22whj.log /Users/siddiq90/github-tokens /Users/siddiq90/buildtest_ozb8b52z.log /Users/siddiq90/.zcompdump /Users/siddiq90/buildtest_nab_ckph.log /Users/siddiq90/.serverauth.543 /Users/siddiq90/.s.PGSQL.15007.lock /Users/siddiq90/.bash_profile /Users/siddiq90/.Xauthority /Users/siddiq90/.python_history /Users/siddiq90/.gitconfig /Users/siddiq90/output.txt /Users/siddiq90/.bash_history /Users/siddiq90/.viminfo\n",
"error": "",
"job": null
}
]
}