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. Shown below is command usage to query test reports.

$ buildtest report --help
usage: buildtest [options] [COMMANDS] report [-h] [--filter FILTER]
                                             [--format FORMAT] [--helpfilter]
                                             [--helpformat] [-f] [-s START]
                                             [-e END] [--latest] [--oldest]
                                             [-c COUNT] [-n] [-t] [--pager]
                                             ...

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
  -f, --failure         Retrieve all FAIL tests
  -s START, --start START
                        Retrieve tests by starttime
  -e END, --end END     Retrieve tests by endtime
  --latest              Retrieve latest record of particular test
  --oldest              Retrieve oldest record of particular test
  -c COUNT, --count COUNT
                        Retrieve limited number of rows that get printed
  -n, --no-header       Don't print headers column used with terse option
                        (--terse).
  -t, --terse           Print output in machine readable format
  --pager               Enable PAGING when viewing result

subcommands:
  Fetch test results from report file and print them in table format

  
    clear               Remove all 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
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                           s/v0.15.0/var/report.json                            
┏━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━┓
┃        ┃        ┃       ┃ return ┃ startt ┃ endtim ┃ runtim ┃        ┃ build ┃
┃ name   ┃ id     ┃ state ┃ code   ┃ ime    ┃ e      ┃ e      ┃ tags   ┃ spec  ┃
┡━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━┩
│ variab │ 272ee5 │ PASS  │ 0      │ 2022/0 │ 2022/0 │ 0.0100 │ tutori │ /home │
│ les_ba │ 91     │       │        │ 7/01 0 │ 7/01 0 │ 49     │ als    │ /docs │
│ sh     │        │       │        │ 0:37:3 │ 0:37:3 │        │        │ /chec │
│        │        │       │        │ 1      │ 1      │        │        │ kouts │
│        │        │       │        │        │        │        │        │ /read │
│        │        │       │        │        │        │        │        │ thedo │
│        │        │       │        │        │        │        │        │ cs.or │
│        │        │       │        │        │        │        │        │ g/use │
│        │        │       │        │        │        │        │        │ r_bui │
│        │        │       │        │        │        │        │        │ lds/b │
│        │        │       │        │        │        │        │        │ uildt │
│        │        │       │        │        │        │        │        │ est/c │
│        │        │       │        │        │        │        │        │ hecko │
│        │        │       │        │        │        │        │        │ uts/v │
...

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
                                 Format Fields                                  
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field      ┃ Description                                                     ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ buildspec  │ Buildspec File                                                  │
│ buildenv   │ Show build environment file for test                            │
│ command    │ Command executed                                                │
│ compiler   │ Retrieve compiler used for test (applicable for compiler        │
│            │ schema)                                                         │
│ endtime    │ End Time for test                                               │
│ errfile    │ Error File                                                      │
│ executor   │ Name of executor used for running test                          │
│ hostname   │ Hostname of machine where job was submitted from                │
│ full_id    │ Fully qualified build identifier                                │
│ id         │ Unique build identifier                                         │
│ metrics    │ List all metrics for test                                       │
│ name       │ Name of test                                                    │
│ outfile    │ Output file                                                     │
│ returncode │ Return Code                                                     │
│ runtime    │ Total runtime in seconds                                        │
│ schemafile │ Schema file used for validating test                            │
│ starttime  │ Start time of test                                              │
│ state      │ State of test (PASS/FAIL)                                       │
│ tags       │ Tag name                                                        │
│ testroot   │ Root of test directory                                          │
│ testpath   │ Path to test                                                    │
│ user       │ User who ran the test                                           │
└────────────┴─────────────────────────────────────────────────────────────────┘

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
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                           s/v0.15.0/var/report.json                            
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┓
┃ name                    ┃ id       ┃ executor           ┃ state ┃ returncode ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━┩
│ variables_bash          │ 272ee591 │ generic.local.bash │ PASS  │ 0          │
├─────────────────────────┼──────────┼────────────────────┼───────┼────────────┤
│ variables_bash          │ e63eab39 │ generic.local.bash │ PASS  │ 0          │
├─────────────────────────┼──────────┼────────────────────┼───────┼────────────┤
│ variables_bash          │ 7250a603 │ generic.local.bash │ PASS  │ 0          │
├─────────────────────────┼──────────┼────────────────────┼───────┼────────────┤
│ variables_bash          │ 182dde6b │ generic.local.bash │ PASS  │ 0          │
├─────────────────────────┼──────────┼────────────────────┼───────┼────────────┤
│ variables_bash          │ 14eff1ce │ generic.local.bash │ PASS  │ 0          │
├─────────────────────────┼──────────┼────────────────────┼───────┼────────────┤
│ returncode_int_match    │ e599ee5d │ generic.local.bash │ PASS  │ 128        │
├─────────────────────────┼──────────┼────────────────────┼───────┼────────────┤
│ returncode_int_match    │ 6acfcdc2 │ generic.local.bash │ PASS  │ 128        │
├─────────────────────────┼──────────┼────────────────────┼───────┼────────────┤
│ returncode_int_match    │ 6e88fa1a │ generic.local.bash │ PASS  │ 128        │
├─────────────────────────┼──────────┼────────────────────┼───────┼────────────┤
...

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                        
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Field      ┃ Description                ┃ Expected Value ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ buildspec  │ Filter by buildspec file   │ FILE           │
│ name       │ Filter by test name        │ STRING         │
│ executor   │ Filter by executor name    │ STRING         │
│ returncode │ Filter tests by returncode │ INT            │
│ state      │ Filter by test state       │ PASS/FAIL      │
│ tags       │ Filter tests by tag name   │ STRING         │
└────────────┴────────────────────────────┴────────────────┘

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
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                           s/v0.15.0/var/report.json                            
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ name                                         ┃ id           ┃ returncode     ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ returncode_list_mismatch                     │ 2c47274d     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ returncode_list_mismatch                     │ b6389efb     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ returncode_list_mismatch                     │ cb7a368f     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ returncode_list_mismatch                     │ 2e9d0800     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ returncode_list_mismatch                     │ 39309f1f     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ timelimit_max                                │ 0e80f5d7     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ timelimit_min_max                            │ 6133f67b     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ timelimit_min                                │ 1752c254     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ timelimit_min_fail                           │ 15002c0f     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ timelimit_max_fail                           │ 1a4546ef     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ always_pass                                  │ 5973a25d     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ test_pass_returncode_mismatch                │ 8835e6a0     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ test_fail_returncode_match                   │ d8f20c95     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ always_fail                                  │ 202bb021     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ metric_regex_example                         │ 8daab2c1     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ test2                                        │ 307465a4     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ multiple_executors                           │ 396e29f0     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ executors_vars_env_declaration               │ ce22fb8a     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ executors_sbatch_declaration                 │ c9513fb7     │ 2              │
├──────────────────────────────────────────────┼──────────────┼────────────────┤
│ status_returncode_by_executors               │ 45e05858     │ 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
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                           s/v0.15.0/var/report.json                            
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ name                 ┃ id                ┃ returncode           ┃ state      ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ exit1_pass           │ cd39c866          │ 1                    │ PASS       │
├──────────────────────┼───────────────────┼──────────────────────┼────────────┤
│ exit1_pass           │ dc9c4bd4          │ 1                    │ PASS       │
├──────────────────────┼───────────────────┼──────────────────────┼────────────┤
│ exit1_pass           │ d7a91f3f          │ 1                    │ PASS       │
├──────────────────────┼───────────────────┼──────────────────────┼────────────┤
│ exit1_pass           │ 3d803ea5          │ 1                    │ PASS       │
├──────────────────────┼───────────────────┼──────────────────────┼────────────┤
│ exit1_pass           │ 78bd339b          │ 1                    │ PASS       │
├──────────────────────┼───────────────────┼──────────────────────┼────────────┤
│ exit1_pass           │ de90386b          │ 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
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                           s/v0.15.0/var/report.json                            
┏━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ name         ┃ id       ┃ state ┃ buildspec                                  ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ python_hello │ c4e8b843 │ PASS  │ /home/docs/checkouts/readthedocs.org/user_ │
│              │          │       │ builds/buildtest/checkouts/v0.15.0/tutoria │
│              │          │       │ ls/python-hello.yml                        │
├──────────────┼──────────┼───────┼────────────────────────────────────────────┤
│ python_hello │ 71310f5c │ PASS  │ /home/docs/checkouts/readthedocs.org/user_ │
│              │          │       │ builds/buildtest/checkouts/v0.15.0/tutoria │
│              │          │       │ ls/python-hello.yml                        │
├──────────────┼──────────┼───────┼────────────────────────────────────────────┤
│ python_hello │ 69cd22ea │ PASS  │ /home/docs/checkouts/readthedocs.org/user_ │
│              │          │       │ builds/buildtest/checkouts/v0.15.0/tutoria │
│              │          │       │ ls/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
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                           s/v0.15.0/var/report.json                            
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ name                               ┃ id         ┃ state  ┃ executor          ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ timelimit_min_max                  │ 6133f67b   │ FAIL   │ generic.local.sh  │
├────────────────────────────────────┼────────────┼────────┼───────────────────┤
│ timelimit_min                      │ 1752c254   │ FAIL   │ generic.local.sh  │
├────────────────────────────────────┼────────────┼────────┼───────────────────┤
│ timelimit_min_fail                 │ 15002c0f   │ FAIL   │ generic.local.sh  │
├────────────────────────────────────┼────────────┼────────┼───────────────────┤
│ test_fail_returncode_match         │ d8f20c95   │ FAIL   │ generic.local.sh  │
├────────────────────────────────────┼────────────┼────────┼───────────────────┤
│ always_fail                        │ 202bb021   │ FAIL   │ generic.local.sh  │
├────────────────────────────────────┼────────────┼────────┼───────────────────┤
│ metric_regex_example               │ 8daab2c1   │ FAIL   │ generic.local.sh  │
├────────────────────────────────────┼────────────┼────────┼───────────────────┤
│ multiple_executors                 │ 396e29f0   │ FAIL   │ generic.local.sh  │
├────────────────────────────────────┼────────────┼────────┼───────────────────┤
│ executors_vars_env_declaration     │ ce22fb8a   │ FAIL   │ generic.local.sh  │
├────────────────────────────────────┼────────────┼────────┼───────────────────┤
│ executors_sbatch_declaration       │ c9513fb7   │ FAIL   │ generic.local.sh  │
├────────────────────────────────────┼────────────┼────────┼───────────────────┤
│ status_returncode_by_executors     │ 45e05858   │ 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) ──────────────────────╮
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /bin/buildtest:36 in <module>                                                │
│                                                                              │
│   33                                                                         │
│   34 import buildtest.main                                                   │
│   35                                                                         │
│ ❱ 36 buildtest.main.main()                                                   │
│   37                                                                         │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │ __annotations__ = {}                                                     │ │
│ │    __builtins__ = <module 'builtins' (built-in)>                         │ │
│ │      __cached__ = None                                                   │ │
│ │         __doc__ = ':"\n# preferred pythons for running                   │ │
│ │                   buildtest\nPREFERRED_PYTHONS="python3 python"\n'+365   │ │
│ │        __file__ = '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │      __loader__ = <_frozen_importlib_external.SourceFileLoader object at │ │
│ │                   0x7f64eaf3a190>                                        │ │
│ │        __name__ = '__main__'                                             │ │
│ │     __package__ = None                                                   │ │
│ │        __spec__ = None                                                   │ │
│ │       buildtest = <module 'buildtest' from                               │ │
│ │                   '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │  buildtest_file = '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │              os = <module 'os' from                                      │ │
│ │                   '/home/docs/.asdf/installs/python/3.7.13/lib/python3.… │ │
│ │          prefix = '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │             sys = <module 'sys' (built-in)>                              │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/main.py:225 in main                                               │
│                                                                              │
│   222 │                                                                      │
│   223 │   # buildtest report                                                 │
│   224 │   elif args.subcommands in ["report", "rt"]:                         │
│ ❱ 225 │   │   report_cmd(args, report_file)                                  │
│   226 │                                                                      │
│   227 │   elif args.subcommands == "path":                                   │
│   228 │   │   path_cmd(                                                      │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │               args = Namespace(configfile=None, count=None, debug=False, │ │
│ │                      editor=None, end=None, failure=False,               │ │
│ │                      filter={'returncode': '1.5'}, format=None,          │ │
│ │                      helpfilter=False, helpformat=False, lastlog=False,  │ │
│ │                      latest=False, no_color=False, no_header=False,      │ │
│ │                      oldest=False, pager=False, report=None,             │ │
│ │                      report_subcommand=None, start=None,                 │ │
│ │                      subcommands='rt', terse=False)                      │ │
│ │   buildtest_editor = '/usr/bin/vim'                                      │ │
│ │        config_file = None                                                │ │
│ │      configuration = <buildtest.config.SiteConfiguration object at       │ │
│ │                      0x7f64e8f0c390>                                     │ │
│ │             logger = <Logger buildtest (DEBUG)>                          │ │
│ │           no_color = False                                               │ │
│ │             parser = ArgumentParser(prog='buildtest', usage='%(prog)s    │ │
│ │                      [options] [COMMANDS]', description='buildtest is a  │ │
│ │                      HPC testing framework for building and running      │ │
│ │                      tests.', formatter_class=<class                     │ │
│ │                      'argparse.RawDescriptionHelpFormatter'>,            │ │
│ │                      conflict_handler='error', add_help=True)            │ │
│ │        report_file = None                                                │ │
│ │             system = <buildtest.system.BuildTestSystem object at         │ │
│ │                      0x7f64e92a1a90>                                     │ │
│ │ validate_executors = True                                                │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/cli/report.py:776 in report_cmd                                   │
│                                                                              │
│   773 │   │   oldest=args.oldest,                                            │
│   774 │   │   report_file=report_file,                                       │
│   775 │   │   count=args.count,                                              │
│ ❱ 776 │   │   pager=args.pager,                                              │
│   777 │   )                                                                  │
│   778 │   if args.report_subcommand == "summary":                            │
│   779 │   │   report_summary(results, args.pager)                            │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │        args = Namespace(configfile=None, count=None, debug=False,        │ │
│ │               editor=None, end=None, failure=False,                      │ │
│ │               filter={'returncode': '1.5'}, format=None,                 │ │
│ │               helpfilter=False, helpformat=False, lastlog=False,         │ │
│ │               latest=False, no_color=False, no_header=False,             │ │
│ │               oldest=False, pager=False, report=None,                    │ │
│ │               report_subcommand=None, start=None, subcommands='rt',      │ │
│ │               terse=False)                                               │ │
│ │ report_file = None                                                       │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/cli/report.py:124 in __init__                                     │
│                                                                              │
│   121 │   │   │   self._reportfile = resolve_path(report_file)               │
│   122 │   │                                                                  │
│   123 │   │   self.report = self.load()                                      │
│ ❱ 124 │   │   self._check_filter_fields()                                    │
│   125 │   │   self._check_format_fields()                                    │
│   126 │   │   self._check_start_and_end_fields()                             │
│   127 │   │   self.filter_buildspecs_from_report()                           │
│                                                                              │
│ ╭─────────────────────────────── locals ───────────────────────────────╮     │
│ │       count = None                                                   │     │
│ │         end = None                                                   │     │
│ │     failure = False                                                  │     │
│ │ filter_args = {'returncode': '1.5'}                                  │     │
│ │ format_args = None                                                   │     │
│ │      latest = False                                                  │     │
│ │      oldest = False                                                  │     │
│ │       pager = False                                                  │     │
│ │ report_file = None                                                   │     │
│ │        self = <buildtest.cli.report.Report object at 0x7f64e8f53b10> │     │
│ │       start = None                                                   │     │
│ ╰──────────────────────────────────────────────────────────────────────╯     │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/cli/report.py:162 in _check_filter_fields                         │
│                                                                              │
│   159 │   │   │   │                                                          │
│   160 │   │   │   │   if key == "returncode" and not is_int(self.filter[key] │
│   161 │   │   │   │   │   raise BuildTestError(                              │
│ ❱ 162 │   │   │   │   │   │   f"Invalid returncode:{self.filter[key]} must b │
│   163 │   │   │   │   │   )                                                  │
│   164 │   │   │   │                                                          │
│   165 │   │   │   │   logger.debug(f"filter field: {key} is valid")          │
│                                                                              │
│ ╭─────────────────────────── locals ────────────────────────────╮            │
│ │  key = 'returncode'                                           │            │
│ │ self = <buildtest.cli.report.Report object at 0x7f64e8f53b10> │            │
│ ╰───────────────────────────────────────────────────────────────╯            │
╰──────────────────────────────────────────────────────────────────────────────╯
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
╭───────────────────── Traceback (most recent call last) ──────────────────────╮
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /bin/buildtest:36 in <module>                                                │
│                                                                              │
│   33                                                                         │
│   34 import buildtest.main                                                   │
│   35                                                                         │
│ ❱ 36 buildtest.main.main()                                                   │
│   37                                                                         │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │ __annotations__ = {}                                                     │ │
│ │    __builtins__ = <module 'builtins' (built-in)>                         │ │
│ │      __cached__ = None                                                   │ │
│ │         __doc__ = ':"\n# preferred pythons for running                   │ │
│ │                   buildtest\nPREFERRED_PYTHONS="python3 python"\n'+365   │ │
│ │        __file__ = '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │      __loader__ = <_frozen_importlib_external.SourceFileLoader object at │ │
│ │                   0x7efe78d6d1d0>                                        │ │
│ │        __name__ = '__main__'                                             │ │
│ │     __package__ = None                                                   │ │
│ │        __spec__ = None                                                   │ │
│ │       buildtest = <module 'buildtest' from                               │ │
│ │                   '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │  buildtest_file = '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │              os = <module 'os' from                                      │ │
│ │                   '/home/docs/.asdf/installs/python/3.7.13/lib/python3.… │ │
│ │          prefix = '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │             sys = <module 'sys' (built-in)>                              │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/main.py:225 in main                                               │
│                                                                              │
│   222 │                                                                      │
│   223 │   # buildtest report                                                 │
│   224 │   elif args.subcommands in ["report", "rt"]:                         │
│ ❱ 225 │   │   report_cmd(args, report_file)                                  │
│   226 │                                                                      │
│   227 │   elif args.subcommands == "path":                                   │
│   228 │   │   path_cmd(                                                      │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │               args = Namespace(configfile=None, count=None, debug=False, │ │
│ │                      editor=None, end=None, failure=False,               │ │
│ │                      filter={'state': 'UNKNOWN'}, format=None,           │ │
│ │                      helpfilter=False, helpformat=False, lastlog=False,  │ │
│ │                      latest=False, no_color=False, no_header=False,      │ │
│ │                      oldest=False, pager=False, report=None,             │ │
│ │                      report_subcommand=None, start=None,                 │ │
│ │                      subcommands='rt', terse=False)                      │ │
│ │   buildtest_editor = '/usr/bin/vim'                                      │ │
│ │        config_file = None                                                │ │
│ │      configuration = <buildtest.config.SiteConfiguration object at       │ │
│ │                      0x7efe76d46e10>                                     │ │
│ │             logger = <Logger buildtest (DEBUG)>                          │ │
│ │           no_color = False                                               │ │
│ │             parser = ArgumentParser(prog='buildtest', usage='%(prog)s    │ │
│ │                      [options] [COMMANDS]', description='buildtest is a  │ │
│ │                      HPC testing framework for building and running      │ │
│ │                      tests.', formatter_class=<class                     │ │
│ │                      'argparse.RawDescriptionHelpFormatter'>,            │ │
│ │                      conflict_handler='error', add_help=True)            │ │
│ │        report_file = None                                                │ │
│ │             system = <buildtest.system.BuildTestSystem object at         │ │
│ │                      0x7efe76d46e50>                                     │ │
│ │ validate_executors = True                                                │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/cli/report.py:776 in report_cmd                                   │
│                                                                              │
│   773 │   │   oldest=args.oldest,                                            │
│   774 │   │   report_file=report_file,                                       │
│   775 │   │   count=args.count,                                              │
│ ❱ 776 │   │   pager=args.pager,                                              │
│   777 │   )                                                                  │
│   778 │   if args.report_subcommand == "summary":                            │
│   779 │   │   report_summary(results, args.pager)                            │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │        args = Namespace(configfile=None, count=None, debug=False,        │ │
│ │               editor=None, end=None, failure=False, filter={'state':     │ │
│ │               'UNKNOWN'}, format=None, helpfilter=False,                 │ │
│ │               helpformat=False, lastlog=False, latest=False,             │ │
│ │               no_color=False, no_header=False, oldest=False,             │ │
│ │               pager=False, report=None, report_subcommand=None,          │ │
│ │               start=None, subcommands='rt', terse=False)                 │ │
│ │ report_file = None                                                       │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/cli/report.py:127 in __init__                                     │
│                                                                              │
│   124 │   │   self._check_filter_fields()                                    │
│   125 │   │   self._check_format_fields()                                    │
│   126 │   │   self._check_start_and_end_fields()                             │
│ ❱ 127 │   │   self.filter_buildspecs_from_report()                           │
│   128 │   │                                                                  │
│   129 │   │   self.process_report()                                          │
│   130                                                                        │
│                                                                              │
│ ╭─────────────────────────────── locals ───────────────────────────────╮     │
│ │       count = None                                                   │     │
│ │         end = None                                                   │     │
│ │     failure = False                                                  │     │
│ │ filter_args = {'state': 'UNKNOWN'}                                   │     │
│ │ format_args = None                                                   │     │
│ │      latest = False                                                  │     │
│ │      oldest = False                                                  │     │
│ │       pager = False                                                  │     │
│ │ report_file = None                                                   │     │
│ │        self = <buildtest.cli.report.Report object at 0x7efe76d86390> │     │
│ │       start = None                                                   │     │
│ ╰──────────────────────────────────────────────────────────────────────╯     │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/cli/report.py:296 in filter_buildspecs_from_report                │
│                                                                              │
│   293 │   │   if self.filter.get("state"):                                   │
│   294 │   │   │   if self.filter["state"] not in ["PASS", "FAIL"]:           │
│   295 │   │   │   │   raise BuildTestError(                                  │
│ ❱ 296 │   │   │   │   │   f"filter argument 'state' must be 'PASS' or 'FAIL' │
│   297 │   │   │   │   )                                                      │
│   298 │                                                                      │
│   299 │   def filter_by_start_end(self, test):                               │
│                                                                              │
│ ╭─────────────────────────── locals ────────────────────────────╮            │
│ │ self = <buildtest.cli.report.Report object at 0x7efe76d86390> │            │
│ ╰───────────────────────────────────────────────────────────────╯            │
╰──────────────────────────────────────────────────────────────────────────────╯
BuildTestError: "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
╭───────────────────── Traceback (most recent call last) ──────────────────────╮
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /bin/buildtest:36 in <module>                                                │
│                                                                              │
│   33                                                                         │
│   34 import buildtest.main                                                   │
│   35                                                                         │
│ ❱ 36 buildtest.main.main()                                                   │
│   37                                                                         │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │ __annotations__ = {}                                                     │ │
│ │    __builtins__ = <module 'builtins' (built-in)>                         │ │
│ │      __cached__ = None                                                   │ │
│ │         __doc__ = ':"\n# preferred pythons for running                   │ │
│ │                   buildtest\nPREFERRED_PYTHONS="python3 python"\n'+365   │ │
│ │        __file__ = '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │      __loader__ = <_frozen_importlib_external.SourceFileLoader object at │ │
│ │                   0x7fae3d43e190>                                        │ │
│ │        __name__ = '__main__'                                             │ │
│ │     __package__ = None                                                   │ │
│ │        __spec__ = None                                                   │ │
│ │       buildtest = <module 'buildtest' from                               │ │
│ │                   '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │  buildtest_file = '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │              os = <module 'os' from                                      │ │
│ │                   '/home/docs/.asdf/installs/python/3.7.13/lib/python3.… │ │
│ │          prefix = '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │             sys = <module 'sys' (built-in)>                              │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/main.py:225 in main                                               │
│                                                                              │
│   222 │                                                                      │
│   223 │   # buildtest report                                                 │
│   224 │   elif args.subcommands in ["report", "rt"]:                         │
│ ❱ 225 │   │   report_cmd(args, report_file)                                  │
│   226 │                                                                      │
│   227 │   elif args.subcommands == "path":                                   │
│   228 │   │   path_cmd(                                                      │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │               args = Namespace(configfile=None, count=None, debug=False, │ │
│ │                      editor=None, end=None, failure=False,               │ │
│ │                      filter={'buildspec': '/path/to/invalid.yml'},       │ │
│ │                      format=None, helpfilter=False, helpformat=False,    │ │
│ │                      lastlog=False, latest=False, no_color=False,        │ │
│ │                      no_header=False, oldest=False, pager=False,         │ │
│ │                      report=None, report_subcommand=None, start=None,    │ │
│ │                      subcommands='rt', terse=False)                      │ │
│ │   buildtest_editor = '/usr/bin/vim'                                      │ │
│ │        config_file = None                                                │ │
│ │      configuration = <buildtest.config.SiteConfiguration object at       │ │
│ │                      0x7fae3b418e10>                                     │ │
│ │             logger = <Logger buildtest (DEBUG)>                          │ │
│ │           no_color = False                                               │ │
│ │             parser = ArgumentParser(prog='buildtest', usage='%(prog)s    │ │
│ │                      [options] [COMMANDS]', description='buildtest is a  │ │
│ │                      HPC testing framework for building and running      │ │
│ │                      tests.', formatter_class=<class                     │ │
│ │                      'argparse.RawDescriptionHelpFormatter'>,            │ │
│ │                      conflict_handler='error', add_help=True)            │ │
│ │        report_file = None                                                │ │
│ │             system = <buildtest.system.BuildTestSystem object at         │ │
│ │                      0x7fae3b418750>                                     │ │
│ │ validate_executors = True                                                │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/cli/report.py:776 in report_cmd                                   │
│                                                                              │
│   773 │   │   oldest=args.oldest,                                            │
│   774 │   │   report_file=report_file,                                       │
│   775 │   │   count=args.count,                                              │
│ ❱ 776 │   │   pager=args.pager,                                              │
│   777 │   )                                                                  │
│   778 │   if args.report_subcommand == "summary":                            │
│   779 │   │   report_summary(results, args.pager)                            │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │        args = Namespace(configfile=None, count=None, debug=False,        │ │
│ │               editor=None, end=None, failure=False, filter={'buildspec': │ │
│ │               '/path/to/invalid.yml'}, format=None, helpfilter=False,    │ │
│ │               helpformat=False, lastlog=False, latest=False,             │ │
│ │               no_color=False, no_header=False, oldest=False,             │ │
│ │               pager=False, report=None, report_subcommand=None,          │ │
│ │               start=None, subcommands='rt', terse=False)                 │ │
│ │ report_file = None                                                       │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/cli/report.py:127 in __init__                                     │
│                                                                              │
│   124 │   │   self._check_filter_fields()                                    │
│   125 │   │   self._check_format_fields()                                    │
│   126 │   │   self._check_start_and_end_fields()                             │
│ ❱ 127 │   │   self.filter_buildspecs_from_report()                           │
│   128 │   │                                                                  │
│   129 │   │   self.process_report()                                          │
│   130                                                                        │
│                                                                              │
│ ╭─────────────────────────────── locals ───────────────────────────────╮     │
│ │       count = None                                                   │     │
│ │         end = None                                                   │     │
│ │     failure = False                                                  │     │
│ │ filter_args = {'buildspec': '/path/to/invalid.yml'}                  │     │
│ │ format_args = None                                                   │     │
│ │      latest = False                                                  │     │
│ │      oldest = False                                                  │     │
│ │       pager = False                                                  │     │
│ │ report_file = None                                                   │     │
│ │        self = <buildtest.cli.report.Report object at 0x7fae3b457c90> │     │
│ │       start = None                                                   │     │
│ ╰──────────────────────────────────────────────────────────────────────╯     │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/cli/report.py:280 in filter_buildspecs_from_report                │
│                                                                              │
│   277 │   │   │   # if file doesn't exist we terminate with message          │
│   278 │   │   │   if not resolved_buildspecs:                                │
│   279 │   │   │   │   raise BuildTestError(                                  │
│ ❱ 280 │   │   │   │   │   f"Invalid File Path for filter field 'buildspec':  │
│   281 │   │   │   │   )                                                      │
│   282 │   │   │                                                              │
│   283 │   │   │   # if file not found in cache we exit                       │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │ resolved_buildspecs = None                                               │ │
│ │                self = <buildtest.cli.report.Report object at             │ │
│ │                       0x7fae3b457c90>                                    │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────╯
BuildTestError: "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
╭───────────────────── Traceback (most recent call last) ──────────────────────╮
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /bin/buildtest:36 in <module>                                                │
│                                                                              │
│   33                                                                         │
│   34 import buildtest.main                                                   │
│   35                                                                         │
│ ❱ 36 buildtest.main.main()                                                   │
│   37                                                                         │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │ __annotations__ = {}                                                     │ │
│ │    __builtins__ = <module 'builtins' (built-in)>                         │ │
│ │      __cached__ = None                                                   │ │
│ │         __doc__ = ':"\n# preferred pythons for running                   │ │
│ │                   buildtest\nPREFERRED_PYTHONS="python3 python"\n'+365   │ │
│ │        __file__ = '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │      __loader__ = <_frozen_importlib_external.SourceFileLoader object at │ │
│ │                   0x7fa002865190>                                        │ │
│ │        __name__ = '__main__'                                             │ │
│ │     __package__ = None                                                   │ │
│ │        __spec__ = None                                                   │ │
│ │       buildtest = <module 'buildtest' from                               │ │
│ │                   '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │  buildtest_file = '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │              os = <module 'os' from                                      │ │
│ │                   '/home/docs/.asdf/installs/python/3.7.13/lib/python3.… │ │
│ │          prefix = '/home/docs/checkouts/readthedocs.org/user_builds/bui… │ │
│ │             sys = <module 'sys' (built-in)>                              │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/main.py:225 in main                                               │
│                                                                              │
│   222 │                                                                      │
│   223 │   # buildtest report                                                 │
│   224 │   elif args.subcommands in ["report", "rt"]:                         │
│ ❱ 225 │   │   report_cmd(args, report_file)                                  │
│   226 │                                                                      │
│   227 │   elif args.subcommands == "path":                                   │
│   228 │   │   path_cmd(                                                      │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │               args = Namespace(configfile=None, count=None, debug=False, │ │
│ │                      editor=None, end=None, failure=False,               │ │
│ │                      filter={'buildspec':                                │ │
│ │                      '$BUILDTEST_ROOT/tutorials/invalid_executor.yml'},  │ │
│ │                      format=None, helpfilter=False, helpformat=False,    │ │
│ │                      lastlog=False, latest=False, no_color=False,        │ │
│ │                      no_header=False, oldest=False, pager=False,         │ │
│ │                      report=None, report_subcommand=None, start=None,    │ │
│ │                      subcommands='rt', terse=False)                      │ │
│ │   buildtest_editor = '/usr/bin/vim'                                      │ │
│ │        config_file = None                                                │ │
│ │      configuration = <buildtest.config.SiteConfiguration object at       │ │
│ │                      0x7fa000bbbe90>                                     │ │
│ │             logger = <Logger buildtest (DEBUG)>                          │ │
│ │           no_color = False                                               │ │
│ │             parser = ArgumentParser(prog='buildtest', usage='%(prog)s    │ │
│ │                      [options] [COMMANDS]', description='buildtest is a  │ │
│ │                      HPC testing framework for building and running      │ │
│ │                      tests.', formatter_class=<class                     │ │
│ │                      'argparse.RawDescriptionHelpFormatter'>,            │ │
│ │                      conflict_handler='error', add_help=True)            │ │
│ │        report_file = None                                                │ │
│ │             system = <buildtest.system.BuildTestSystem object at         │ │
│ │                      0x7fa00083e3d0>                                     │ │
│ │ validate_executors = True                                                │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/cli/report.py:776 in report_cmd                                   │
│                                                                              │
│   773 │   │   oldest=args.oldest,                                            │
│   774 │   │   report_file=report_file,                                       │
│   775 │   │   count=args.count,                                              │
│ ❱ 776 │   │   pager=args.pager,                                              │
│   777 │   )                                                                  │
│   778 │   if args.report_subcommand == "summary":                            │
│   779 │   │   report_summary(results, args.pager)                            │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │        args = Namespace(configfile=None, count=None, debug=False,        │ │
│ │               editor=None, end=None, failure=False, filter={'buildspec': │ │
│ │               '$BUILDTEST_ROOT/tutorials/invalid_executor.yml'},         │ │
│ │               format=None, helpfilter=False, helpformat=False,           │ │
│ │               lastlog=False, latest=False, no_color=False,               │ │
│ │               no_header=False, oldest=False, pager=False, report=None,   │ │
│ │               report_subcommand=None, start=None, subcommands='rt',      │ │
│ │               terse=False)                                               │ │
│ │ report_file = None                                                       │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/cli/report.py:127 in __init__                                     │
│                                                                              │
│   124 │   │   self._check_filter_fields()                                    │
│   125 │   │   self._check_format_fields()                                    │
│   126 │   │   self._check_start_and_end_fields()                             │
│ ❱ 127 │   │   self.filter_buildspecs_from_report()                           │
│   128 │   │                                                                  │
│   129 │   │   self.process_report()                                          │
│   130                                                                        │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │       count = None                                                       │ │
│ │         end = None                                                       │ │
│ │     failure = False                                                      │ │
│ │ filter_args = {                                                          │ │
│ │               │   'buildspec':                                           │ │
│ │               '$BUILDTEST_ROOT/tutorials/invalid_executor.yml'           │ │
│ │               }                                                          │ │
│ │ format_args = None                                                       │ │
│ │      latest = False                                                      │ │
│ │      oldest = False                                                      │ │
│ │       pager = False                                                      │ │
│ │ report_file = None                                                       │ │
│ │        self = <buildtest.cli.report.Report object at 0x7fa0015b33d0>     │ │
│ │       start = None                                                       │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0 │
│ /buildtest/cli/report.py:286 in filter_buildspecs_from_report                │
│                                                                              │
│   283 │   │   │   # if file not found in cache we exit                       │
│   284 │   │   │   if not resolved_buildspecs in self.report.keys():          │
│   285 │   │   │   │   raise BuildTestError(                                  │
│ ❱ 286 │   │   │   │   │   f"buildspec file: {resolved_buildspecs} not found  │
│   287 │   │   │   │   )                                                      │
│   288 │   │   │                                                              │
│   289 │   │   │   # need to set as a list since we will loop over all tests  │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │ resolved_buildspecs = '/home/docs/checkouts/readthedocs.org/user_builds… │ │
│ │                self = <buildtest.cli.report.Report object at             │ │
│ │                       0x7fa0015b33d0>                                    │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────╯
BuildTestError: 'buildspec file: /home/docs/checkouts/readthedocs.org/user_build
s/buildtest/checkouts/v0.15.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 for a particular test. If you want to retrieve the oldest test you can use --oldest option, likewise you can retrieve the latest run via --latest option.

Let’s take a look at this example, we filter by test name exit1_pass which retrieves all test runs. In subsequent example we filter by latest and oldest run.

$ buildtest report --filter name=exit1_pass --format name,id,starttime
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                           s/v0.15.0/var/report.json                            
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ name                 ┃ id               ┃ starttime                          ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ exit1_pass           │ cd39c866         │ 2022/07/01 00:37:32                │
├──────────────────────┼──────────────────┼────────────────────────────────────┤
│ exit1_pass           │ dc9c4bd4         │ 2022/07/01 00:38:32                │
├──────────────────────┼──────────────────┼────────────────────────────────────┤
│ exit1_pass           │ d7a91f3f         │ 2022/07/01 00:38:32                │
├──────────────────────┼──────────────────┼────────────────────────────────────┤
│ exit1_pass           │ 3d803ea5         │ 2022/07/01 00:38:45                │
├──────────────────────┼──────────────────┼────────────────────────────────────┤
│ exit1_pass           │ 78bd339b         │ 2022/07/01 00:38:52                │
├──────────────────────┼──────────────────┼────────────────────────────────────┤
│ exit1_pass           │ de90386b         │ 2022/07/01 00:38:52                │
└──────────────────────┴──────────────────┴────────────────────────────────────┘
$ buildtest report --filter name=exit1_pass --format name,id,starttime --oldest
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                           s/v0.15.0/var/report.json                            
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ name                 ┃ id               ┃ starttime                          ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ exit1_pass           │ cd39c866         │ 2022/07/01 00:37:32                │
└──────────────────────┴──────────────────┴────────────────────────────────────┘
$ buildtest report --filter name=exit1_pass --format name,id,starttime --latest
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                           s/v0.15.0/var/report.json                            
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ name                 ┃ id               ┃ starttime                          ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ exit1_pass           │ de90386b         │ 2022/07/01 00:38:52                │
└──────────────────────┴──────────────────┴────────────────────────────────────┘

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 --filter name=exit1_pass --format name,id,starttime --oldest --latest
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                           s/v0.15.0/var/report.json                            
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ name                 ┃ id               ┃ starttime                          ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ exit1_pass           │ cd39c866         │ 2022/07/01 00:37:32                │
├──────────────────────┼──────────────────┼────────────────────────────────────┤
│ exit1_pass           │ de90386b         │ 2022/07/01 00:38:52                │
└──────────────────────┴──────────────────┴────────────────────────────────────┘

Find all Failed Tests (buildtest report --failure)

The buildtest report --failure command can be used to retrieve all failed tests which is equivalent to filtering tests by state=FAIL since test state is determined by state property. This command can be useful to pin-point failures.

Let’s take a look at these two example, the first test queries report by filtering by tag name tutorials and the second command will run same example with --failure option. Take note of the state property in table, in second example buildtest will filter test and report all FAIL tests.

$ buildtest report --filter tags=tutorials --format name,id,state
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                           s/v0.15.0/var/report.json                            
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ name                                             ┃ id             ┃ state    ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ variables_bash                                   │ 272ee591       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ variables_bash                                   │ e63eab39       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ variables_bash                                   │ 7250a603       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ variables_bash                                   │ 182dde6b       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ variables_bash                                   │ 14eff1ce       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_int_match                             │ e599ee5d       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_int_match                             │ 6acfcdc2       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_int_match                             │ 6e88fa1a       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_int_match                             │ c92d4c9a       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_int_match                             │ 30fe5ae1       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_int_match                             │ d2a0f605       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ exit1_pass                                       │ cd39c866       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ exit1_pass                                       │ dc9c4bd4       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ exit1_pass                                       │ d7a91f3f       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ exit1_pass                                       │ 3d803ea5       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ exit1_pass                                       │ 78bd339b       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ exit1_pass                                       │ de90386b       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ exit1_fail                                       │ 2dc77a83       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ exit1_fail                                       │ 66252312       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ exit1_fail                                       │ 9228dbaf       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ exit1_fail                                       │ 2c6464ef       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ exit1_fail                                       │ 17745c36       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_list_mismatch                         │ 2c47274d       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_list_mismatch                         │ b6389efb       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_list_mismatch                         │ cb7a368f       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_list_mismatch                         │ 2e9d0800       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_list_mismatch                         │ 39309f1f       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ timelimit_max                                    │ 0e80f5d7       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ timelimit_min_max                                │ 6133f67b       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ timelimit_min                                    │ 1752c254       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ timelimit_min_fail                               │ 15002c0f       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ timelimit_max_fail                               │ 1a4546ef       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ bash_nonlogin_shebang                            │ a3856c63       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ bash_login_shebang                               │ 3797c704       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ unskipped                                        │ 85419569       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ metric_regex_example                             │ 8daab2c1       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ multiple_executors                               │ f4b72a7a       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ multiple_executors                               │ 396e29f0       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ executors_vars_env_declaration                   │ ce22fb8a       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ executors_vars_env_declaration                   │ 5e3fb649       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ executors_sbatch_declaration                     │ c9513fb7       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ executors_sbatch_declaration                     │ 0841d1e5       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ status_returncode_by_executors                   │ 446ecde1       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ status_returncode_by_executors                   │ 45e05858       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ circle_area                                      │ c13151ba       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ circle_area                                      │ 377b278d       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ circle_area                                      │ 423e6cf0       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ circle_area                                      │ 3c30eaca       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ circle_area                                      │ 8882fde2       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ csh_env_declaration                              │ 14b7a78f       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ bash_env_variables                               │ 8444c844       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ tcsh_env_declaration                             │ 5ae863ac       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ csh_shell                                        │ f6437214       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ hello_world                                      │ be2dc26b       │ PASS     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ sleep                                            │ d3e2c211       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ sleep                                            │ a57ce033       │ PASS     │
└──────────────────────────────────────────────────┴────────────────┴──────────┘
$ buildtest report --filter tags=tutorials --format name,id,state --failure
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                           s/v0.15.0/var/report.json                            
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ name                                             ┃ id             ┃ state    ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ exit1_fail                                       │ 2dc77a83       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ exit1_fail                                       │ 66252312       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ exit1_fail                                       │ 9228dbaf       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ exit1_fail                                       │ 2c6464ef       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ exit1_fail                                       │ 17745c36       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_list_mismatch                         │ 2c47274d       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_list_mismatch                         │ b6389efb       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_list_mismatch                         │ cb7a368f       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_list_mismatch                         │ 2e9d0800       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ returncode_list_mismatch                         │ 39309f1f       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ timelimit_min_max                                │ 6133f67b       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ timelimit_min                                    │ 1752c254       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ timelimit_min_fail                               │ 15002c0f       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ metric_regex_example                             │ 8daab2c1       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ multiple_executors                               │ 396e29f0       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ executors_vars_env_declaration                   │ ce22fb8a       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ executors_sbatch_declaration                     │ c9513fb7       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ status_returncode_by_executors                   │ 45e05858       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ tcsh_env_declaration                             │ 5ae863ac       │ FAIL     │
├──────────────────────────────────────────────────┼────────────────┼──────────┤
│ sleep                                            │ d3e2c211       │ FAIL     │
└──────────────────────────────────────────────────┴────────────────┴──────────┘

Find Tests by Start and End Date (buildtest report --start --end)

The buildtest report --start and buildtest report --end command can be used to retrieve test records based on start and end date.

Let’s take a look at these two example, the first test queries report by filtering by state and name. The second command will run same example with --start --end option. Take note of the starttime and endtime properties in table, in second example buildtest will filter test and only report tests in the range of [start, end] dates.

$ buildtest report --filter state=FAIL,name=exit1_fail --format name,state,starttime,endtime
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                             s/1082/var/report.json
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ name                                                   ┃ state        ┃ starttime                                ┃ endtime                                 ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ exit1_fail                                             │ FAIL         │ 2022/06/09 17:51:50                      │ 2022/06/09 17:51:50                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/09 17:51:51                      │ 2022/06/09 17:51:51                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/09 17:51:53                      │ 2022/06/09 17:51:53                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/09 17:52:01                      │ 2022/06/09 17:52:01                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/10 17:51:50                      │ 2022/06/10 17:51:50                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/10 17:51:52                      │ 2022/06/10 17:51:52                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/10 17:51:52                      │ 2022/06/10 17:51:52                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/10 17:52:01                      │ 2022/06/10 17:52:01                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/11 17:51:57                      │ 2022/06/11 17:51:57                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/11 17:51:59                      │ 2022/06/11 17:51:59                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/11 17:51:57                      │ 2022/06/11 17:51:57                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/11 17:51:59                      │ 2022/06/11 17:51:59                     │
└────────────────────────────────────────────────────────┴──────────────┴──────────────────────────────────────────┴─────────────────────────────────────────┘
$ buildtest report --filter state=FAIL,name=exit1_fail --format name,state,starttime,endtime --start 2022-06-10 --end 2022-06-11
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                             s/1082/var/report.json
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ name                                                   ┃ state        ┃ starttime                                ┃ endtime                                 ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ exit1_fail                                             │ FAIL         │ 2022/06/10 17:51:50                      │ 2022/06/10 17:51:50                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/10 17:51:52                      │ 2022/06/10 17:51:52                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/10 17:51:52                      │ 2022/06/10 17:51:52                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/10 17:52:01                      │ 2022/06/10 17:52:01                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/11 17:51:57                      │ 2022/06/11 17:51:57                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/11 17:51:59                      │ 2022/06/11 17:51:59                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/11 17:51:57                      │ 2022/06/11 17:51:57                     │
├────────────────────────────────────────────────────────┼──────────────┼──────────────────────────────────────────┼─────────────────────────────────────────┤
│ exit1_fail                                             │ FAIL         │ 2022/06/11 17:51:59                      │ 2022/06/11 17:51:59                     │
└────────────────────────────────────────────────────────┴──────────────┴──────────────────────────────────────────┴─────────────────────────────────────────┘

Find limited Tests (buildtest report --count)

The buildtest report command will show all test results from the report file and the output can be quite long. If you want to limit the number of records that get printed then you can use buildtest report --count where --count is number of rows that that get printed. Shown below is the output of 2 records in table format

$ buildtest report --count 2
Report File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
                           s/v0.15.0/var/report.json                            
┏━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━┓
┃        ┃        ┃       ┃ return ┃ startt ┃ endtim ┃ runtim ┃        ┃ build ┃
┃ name   ┃ id     ┃ state ┃ code   ┃ ime    ┃ e      ┃ e      ┃ tags   ┃ spec  ┃
┡━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━┩
│ variab │ 272ee5 │ PASS  │ 0      │ 2022/0 │ 2022/0 │ 0.0100 │ tutori │ /home │
│ les_ba │ 91     │       │        │ 7/01 0 │ 7/01 0 │ 49     │ als    │ /docs │
│ sh     │        │       │        │ 0:37:3 │ 0:37:3 │        │        │ /chec │
│        │        │       │        │ 1      │ 1      │        │        │ kouts │
│        │        │       │        │        │        │        │        │ /read │
│        │        │       │        │        │        │        │        │ thedo │
│        │        │       │        │        │        │        │        │ cs.or │
│        │        │       │        │        │        │        │        │ g/use │
│        │        │       │        │        │        │        │        │ r_bui │
│        │        │       │        │        │        │        │        │ lds/b │
│        │        │       │        │        │        │        │        │ uildt │
│        │        │       │        │        │        │        │        │ est/c │
│        │        │       │        │        │        │        │        │ hecko │
│        │        │       │        │        │        │        │        │ uts/v │
│        │        │       │        │        │        │        │        │ 0.15. │
│        │        │       │        │        │        │        │        │ 0/tut │
│        │        │       │        │        │        │        │        │ orial │
│        │        │       │        │        │        │        │        │ s/var │
│        │        │       │        │        │        │        │        │ s.yml │
├────────┼────────┼───────┼────────┼────────┼────────┼────────┼────────┼───────┤
│ variab │ e63eab │ PASS  │ 0      │ 2022/0 │ 2022/0 │ 0.0087 │ tutori │ /home │
│ les_ba │ 39     │       │        │ 7/01 0 │ 7/01 0 │ 03     │ als    │ /docs │
│ sh     │        │       │        │ 0:38:2 │ 0:38:2 │        │        │ /chec │
│        │        │       │        │ 6      │ 6      │        │        │ kouts │
│        │        │       │        │        │        │        │        │ /read │
│        │        │       │        │        │        │        │        │ thedo │
│        │        │       │        │        │        │        │        │ cs.or │
│        │        │       │        │        │        │        │        │ g/use │
│        │        │       │        │        │        │        │        │ r_bui │
│        │        │       │        │        │        │        │        │ lds/b │
│        │        │       │        │        │        │        │        │ uildt │
│        │        │       │        │        │        │        │        │ est/c │
│        │        │       │        │        │        │        │        │ hecko │
│        │        │       │        │        │        │        │        │ uts/v │
│        │        │       │        │        │        │        │        │ 0.15. │
│        │        │       │        │        │        │        │        │ 0/tut │
│        │        │       │        │        │        │        │        │ orial │
│        │        │       │        │        │        │        │        │ s/var │
│        │        │       │        │        │        │        │        │ s.yml │
└────────┴────────┴───────┴────────┴────────┴────────┴────────┴────────┴───────┘

The --count option also works with terse mode --terse, shown below is the same output

$ buildtest report --terse --count 2
name|id|state|returncode|starttime|endtime|runtime|tags|buildspec
variables_bash|272ee591|PASS|0|2022/07/01 00:37:31|2022/07/01 00:37:31|0.010049|tutorials|/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/vars.yml
variables_bash|e63eab39|PASS|0|2022/07/01 00:38:26|2022/07/01 00:38:26|0.008703|tutorials|/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/vars.yml

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|2dc77a83|FAIL
exit1_fail|66252312|FAIL
exit1_fail|9228dbaf|FAIL
exit1_fail|2c6464ef|FAIL
exit1_fail|17745c36|FAIL
returncode_list_mismatch|2c47274d|FAIL
returncode_list_mismatch|b6389efb|FAIL
returncode_list_mismatch|cb7a368f|FAIL
returncode_list_mismatch|2e9d0800|FAIL
returncode_list_mismatch|39309f1f|FAIL
status_regex_fail|d5da1300|FAIL
timelimit_min_max|6133f67b|FAIL
timelimit_min|1752c254|FAIL
timelimit_min_fail|15002c0f|FAIL
test_fail_returncode_match|d8f20c95|FAIL
always_fail|202bb021|FAIL
metric_regex_example|8daab2c1|FAIL
fail_test|8bc4c071|FAIL
multiple_executors|396e29f0|FAIL
executors_vars_env_declaration|ce22fb8a|FAIL
executors_sbatch_declaration|c9513fb7|FAIL
status_returncode_by_executors|45e05858|FAIL
kernel_swapusage|7157276c|FAIL
kernel_swapusage|e7c0ebd3|FAIL
kernel_swapusage|4819e73e|FAIL
ulimit_filedescriptor_4096|5d00ac91|FAIL
ulimit_filedescriptor_4096|5744546e|FAIL
ulimit_stacksize_unlimited|d2576e86|FAIL
ulimit_stacksize_unlimited|90a1e1af|FAIL
ulimit_max_user_process_2048|13a393be|FAIL
ulimit_max_user_process_2048|4238cc61|FAIL
systemd_default_target|15d8d29e|FAIL
systemd_default_target|e55308ef|FAIL
systemd_default_target|ba85aacd|FAIL
tcsh_env_declaration|5ae863ac|FAIL
sleep|d3e2c211|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 File:  /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkou
ts/v0.15.0/var/report.json
Total Tests: 100
Total Tests by Names:  55
Number of buildspecs in report:  27
                            Breakdown by test                            
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Name                           ┃ Total Pass ┃ Total Fail ┃ Total Runs ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ variables_bash                 │ 5          │ 0          │ 5          │
│ returncode_int_match           │ 6          │ 0          │ 6          │
│ exit1_pass                     │ 6          │ 0          │ 6          │
│ exit1_fail                     │ 0          │ 5          │ 5          │
│ returncode_list_mismatch       │ 0          │ 5          │ 5          │
│ status_regex_pass              │ 1          │ 0          │ 1          │
│ status_regex_fail              │ 0          │ 1          │ 1          │
│ timelimit_max                  │ 1          │ 0          │ 1          │
│ timelimit_min_max              │ 0          │ 1          │ 1          │
│ timelimit_min                  │ 0          │ 1          │ 1          │
│ timelimit_min_fail             │ 0          │ 1          │ 1          │
│ timelimit_max_fail             │ 1          │ 0          │ 1          │
│ always_pass                    │ 1          │ 0          │ 1          │
│ test_pass_returncode_mismatch  │ 1          │ 0          │ 1          │
│ test_fail_returncode_match     │ 0          │ 1          │ 1          │
│ always_fail                    │ 0          │ 1          │ 1          │
│ bash_nonlogin_shebang          │ 1          │ 0          │ 1          │
│ bash_login_shebang             │ 1          │ 0          │ 1          │
│ unskipped                      │ 1          │ 0          │ 1          │
│ metric_regex_example           │ 0          │ 1          │ 1          │
│ jobC                           │ 1          │ 0          │ 1          │
│ jobA                           │ 1          │ 0          │ 1          │
│ jobB                           │ 1          │ 0          │ 1          │
│ test1                          │ 1          │ 0          │ 1          │
│ test2                          │ 1          │ 0          │ 1          │
│ test3                          │ 1          │ 0          │ 1          │
│ final_test                     │ 1          │ 0          │ 1          │
│ fail_test                      │ 0          │ 1          │ 1          │
│ pass_test                      │ 1          │ 0          │ 1          │
│ pass_and_fail_test             │ 1          │ 0          │ 1          │
│ runtime_test                   │ 1          │ 0          │ 1          │
│ runtime_test_pass              │ 1          │ 0          │ 1          │
│ multiple_executors             │ 1          │ 1          │ 2          │
│ executors_vars_env_declaration │ 1          │ 1          │ 2          │
│ executors_sbatch_declaration   │ 1          │ 1          │ 2          │
│ status_returncode_by_executors │ 1          │ 1          │ 2          │
│ kernel_swapusage               │ 0          │ 3          │ 3          │
│ ulimit_vmsize_unlimited        │ 2          │ 0          │ 2          │
│ ulimit_cputime_unlimited       │ 2          │ 0          │ 2          │
│ ulimit_filelock_unlimited      │ 2          │ 0          │ 2          │
│ ulimit_filedescriptor_4096     │ 0          │ 2          │ 2          │
│ ulimit_stacksize_unlimited     │ 0          │ 2          │ 2          │
│ ulimit_max_user_process_2048   │ 0          │ 2          │ 2          │
│ systemd_default_target         │ 0          │ 3          │ 3          │
│ root_disk_usage                │ 3          │ 0          │ 3          │
│ list_of_strings_tags           │ 1          │ 0          │ 1          │
│ string_tag                     │ 1          │ 0          │ 1          │
│ circle_area                    │ 5          │ 0          │ 5          │
│ python_hello                   │ 3          │ 0          │ 3          │
│ csh_env_declaration            │ 1          │ 0          │ 1          │
│ bash_env_variables             │ 1          │ 0          │ 1          │
│ tcsh_env_declaration           │ 0          │ 1          │ 1          │
│ csh_shell                      │ 1          │ 0          │ 1          │
│ hello_world                    │ 1          │ 0          │ 1          │
│ sleep                          │ 1          │ 1          │ 2          │
└────────────────────────────────┴────────────┴────────────┴────────────┘
                                   PASS Tests                                   
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ name            ┃ id       ┃ executor        ┃ state ┃ returncode ┃ runtime  ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ variables_bash  │ 272ee591 │ generic.local.b │ PASS  │ 0          │ 0.010049 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ variables_bash  │ e63eab39 │ generic.local.b │ PASS  │ 0          │ 0.008703 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ variables_bash  │ 7250a603 │ generic.local.b │ PASS  │ 0          │ 0.008886 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ variables_bash  │ 182dde6b │ generic.local.b │ PASS  │ 0          │ 0.009069 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ variables_bash  │ 14eff1ce │ generic.local.b │ PASS  │ 0          │ 0.008847 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ returncode_int_ │ e599ee5d │ generic.local.b │ PASS  │ 128        │ 0.00501  │
│ match           │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ returncode_int_ │ 6acfcdc2 │ generic.local.b │ PASS  │ 128        │ 0.004994 │
│ match           │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ returncode_int_ │ 6e88fa1a │ generic.local.b │ PASS  │ 128        │ 0.005113 │
│ match           │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ returncode_int_ │ c92d4c9a │ generic.local.b │ PASS  │ 128        │ 0.005084 │
│ match           │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ returncode_int_ │ 30fe5ae1 │ generic.local.b │ PASS  │ 128        │ 0.005069 │
│ match           │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ returncode_int_ │ d2a0f605 │ generic.local.b │ PASS  │ 128        │ 0.005197 │
│ match           │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ exit1_pass      │ cd39c866 │ generic.local.b │ PASS  │ 1          │ 0.00509  │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ exit1_pass      │ dc9c4bd4 │ generic.local.b │ PASS  │ 1          │ 0.004943 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ exit1_pass      │ d7a91f3f │ generic.local.b │ PASS  │ 1          │ 0.005419 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ exit1_pass      │ 3d803ea5 │ generic.local.b │ PASS  │ 1          │ 0.005384 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ exit1_pass      │ 78bd339b │ generic.local.b │ PASS  │ 1          │ 0.005021 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ exit1_pass      │ de90386b │ generic.local.b │ PASS  │ 1          │ 0.005227 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ status_regex_pa │ 982987e2 │ generic.local.b │ PASS  │ 0          │ 0.00542  │
│ ss              │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ timelimit_max   │ 0e80f5d7 │ generic.local.s │ PASS  │ 2          │ 0.003273 │
│                 │          │ h               │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ timelimit_max_f │ 1a4546ef │ generic.local.s │ PASS  │ 2          │ 0.002857 │
│ ail             │          │ h               │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ always_pass     │ 5973a25d │ generic.local.s │ PASS  │ 2          │ 0.002875 │
│                 │          │ h               │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ test_pass_retur │ 8835e6a0 │ generic.local.s │ PASS  │ 2          │ 0.002915 │
│ ncode_mismatch  │          │ h               │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ bash_nonlogin_s │ a3856c63 │ generic.local.b │ PASS  │ 0          │ 0.005083 │
│ hebang          │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ bash_login_sheb │ 3797c704 │ generic.local.b │ PASS  │ 0          │ 0.009014 │
│ ang             │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ unskipped       │ 85419569 │ generic.local.b │ PASS  │ 0          │ 0.006115 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ jobC            │ c7815354 │ generic.local.b │ PASS  │ 0          │ 2.007031 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ jobA            │ 5f05eb40 │ generic.local.b │ PASS  │ 0          │ 5.006836 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ jobB            │ 98f6beca │ generic.local.b │ PASS  │ 0          │ 2.006744 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ test1           │ dc75fd97 │ generic.local.b │ PASS  │ 1          │ 0.005514 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ test2           │ 307465a4 │ generic.local.b │ PASS  │ 2          │ 0.005191 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ test3           │ 982f45b5 │ generic.local.b │ PASS  │ 1          │ 0.005145 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ final_test      │ 66f39587 │ generic.local.b │ PASS  │ 0          │ 2.007071 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ pass_test       │ ed2e9c33 │ generic.local.b │ PASS  │ 0          │ 2.006865 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ pass_and_fail_t │ ad2a3dae │ generic.local.b │ PASS  │ 1          │ 2.006859 │
│ est             │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ runtime_test    │ 8416b1df │ generic.local.b │ PASS  │ 0          │ 5.00668  │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ runtime_test_pa │ 06aaf3ee │ generic.local.b │ PASS  │ 0          │ 0.005599 │
│ ss              │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ multiple_execut │ f4b72a7a │ generic.local.b │ PASS  │ 0          │ 0.00771  │
│ ors             │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ executors_vars_ │ 5e3fb649 │ generic.local.b │ PASS  │ 0          │ 0.005745 │
│ env_declaration │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ executors_sbatc │ 0841d1e5 │ generic.local.b │ PASS  │ 0          │ 0.00597  │
│ h_declaration   │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ status_returnco │ 446ecde1 │ generic.local.b │ PASS  │ 0          │ 0.005354 │
│ de_by_executors │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ ulimit_vmsize_u │ ebaac7b0 │ generic.local.b │ PASS  │ 0          │ 0.005231 │
│ nlimited        │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ ulimit_vmsize_u │ 6c5fbe0c │ generic.local.b │ PASS  │ 0          │ 0.005614 │
│ nlimited        │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ ulimit_cputime_ │ c3cf7d08 │ generic.local.b │ PASS  │ 0          │ 0.005398 │
│ unlimited       │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ ulimit_cputime_ │ 1d58f147 │ generic.local.b │ PASS  │ 0          │ 0.005163 │
│ unlimited       │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ ulimit_filelock │ 18e2c9e7 │ generic.local.b │ PASS  │ 0          │ 0.005134 │
│ _unlimited      │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ ulimit_filelock │ ddd039cd │ generic.local.b │ PASS  │ 0          │ 0.005525 │
│ _unlimited      │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ root_disk_usage │ 53d7ab71 │ generic.local.b │ PASS  │ 0          │ 0.010167 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ root_disk_usage │ 9179b0d2 │ generic.local.b │ PASS  │ 0          │ 0.009222 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ root_disk_usage │ 585f174b │ generic.local.b │ PASS  │ 0          │ 0.008999 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ list_of_strings │ 8917da6b │ generic.local.b │ PASS  │ 0          │ 3.031709 │
│ _tags           │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ string_tag      │ 27c3b8f6 │ generic.local.b │ PASS  │ 0          │ 0.00632  │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ circle_area     │ c13151ba │ generic.local.b │ PASS  │ 0          │ 0.02994  │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ circle_area     │ 377b278d │ generic.local.b │ PASS  │ 0          │ 0.031651 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ circle_area     │ 423e6cf0 │ generic.local.b │ PASS  │ 0          │ 0.029582 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ circle_area     │ 3c30eaca │ generic.local.b │ PASS  │ 0          │ 0.030675 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ circle_area     │ 8882fde2 │ generic.local.b │ PASS  │ 0          │ 0.029671 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ python_hello    │ c4e8b843 │ generic.local.b │ PASS  │ 0          │ 0.030331 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ python_hello    │ 71310f5c │ generic.local.b │ PASS  │ 0          │ 0.030162 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ python_hello    │ 69cd22ea │ generic.local.b │ PASS  │ 0          │ 0.03025  │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ csh_env_declara │ 14b7a78f │ generic.local.c │ PASS  │ 0          │ 4.433391 │
│ tion            │          │ sh              │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ bash_env_variab │ 8444c844 │ generic.local.b │ PASS  │ 0          │ 0.007392 │
│ les             │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ csh_shell       │ f6437214 │ generic.local.c │ PASS  │ 0          │ 4.565706 │
│                 │          │ sh              │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ hello_world     │ be2dc26b │ generic.local.b │ PASS  │ 0          │ 0.005457 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ sleep           │ a57ce033 │ generic.local.b │ PASS  │ 0          │ 2.019321 │
│                 │          │ ash             │       │            │          │
└─────────────────┴──────────┴─────────────────┴───────┴────────────┴──────────┘
                                   FAIL Tests                                   
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ name            ┃ id       ┃ executor        ┃ state ┃ returncode ┃ runtime  ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ exit1_fail      │ 2dc77a83 │ generic.local.b │ FAIL  │ 1          │ 0.00557  │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ exit1_fail      │ 66252312 │ generic.local.b │ FAIL  │ 1          │ 0.005137 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ exit1_fail      │ 9228dbaf │ generic.local.b │ FAIL  │ 1          │ 0.005088 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ exit1_fail      │ 2c6464ef │ generic.local.b │ FAIL  │ 1          │ 0.005013 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ exit1_fail      │ 17745c36 │ generic.local.b │ FAIL  │ 1          │ 0.005086 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ returncode_list │ 2c47274d │ generic.local.b │ FAIL  │ 2          │ 0.005    │
│ _mismatch       │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ returncode_list │ b6389efb │ generic.local.b │ FAIL  │ 2          │ 0.005152 │
│ _mismatch       │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ returncode_list │ cb7a368f │ generic.local.b │ FAIL  │ 2          │ 0.005199 │
│ _mismatch       │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ returncode_list │ 2e9d0800 │ generic.local.b │ FAIL  │ 2          │ 0.00555  │
│ _mismatch       │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ returncode_list │ 39309f1f │ generic.local.b │ FAIL  │ 2          │ 0.005009 │
│ _mismatch       │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ status_regex_fa │ d5da1300 │ generic.local.b │ FAIL  │ 0          │ 0.005101 │
│ il              │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ timelimit_min_m │ 6133f67b │ generic.local.s │ FAIL  │ 2          │ 0.002989 │
│ ax              │          │ h               │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ timelimit_min   │ 1752c254 │ generic.local.s │ FAIL  │ 2          │ 0.002948 │
│                 │          │ h               │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ timelimit_min_f │ 15002c0f │ generic.local.s │ FAIL  │ 2          │ 0.002901 │
│ ail             │          │ h               │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ test_fail_retur │ d8f20c95 │ generic.local.s │ FAIL  │ 2          │ 0.002962 │
│ ncode_match     │          │ h               │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ always_fail     │ 202bb021 │ generic.local.s │ FAIL  │ 2          │ 0.003133 │
│                 │          │ h               │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ metric_regex_ex │ 8daab2c1 │ generic.local.s │ FAIL  │ 2          │ 0.003083 │
│ ample           │          │ h               │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ fail_test       │ 8bc4c071 │ generic.local.b │ FAIL  │ 0          │ 2.006828 │
│                 │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ multiple_execut │ 396e29f0 │ generic.local.s │ FAIL  │ 2          │ 0.002923 │
│ ors             │          │ h               │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ executors_vars_ │ ce22fb8a │ generic.local.s │ FAIL  │ 2          │ 0.003031 │
│ env_declaration │          │ h               │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ executors_sbatc │ c9513fb7 │ generic.local.s │ FAIL  │ 2          │ 0.002992 │
│ h_declaration   │          │ h               │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ status_returnco │ 45e05858 │ generic.local.s │ FAIL  │ 2          │ 0.003132 │
│ de_by_executors │          │ h               │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ kernel_swapusag │ 7157276c │ generic.local.b │ FAIL  │ 255        │ 0.105682 │
│ e               │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ kernel_swapusag │ e7c0ebd3 │ generic.local.b │ FAIL  │ 255        │ 0.006283 │
│ e               │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ kernel_swapusag │ 4819e73e │ generic.local.b │ FAIL  │ 255        │ 0.00607  │
│ e               │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ ulimit_filedesc │ 5d00ac91 │ generic.local.b │ FAIL  │ 0          │ 0.005173 │
│ riptor_4096     │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ ulimit_filedesc │ 5744546e │ generic.local.b │ FAIL  │ 0          │ 0.00512  │
│ riptor_4096     │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ ulimit_stacksiz │ d2576e86 │ generic.local.b │ FAIL  │ 0          │ 0.005569 │
│ e_unlimited     │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ ulimit_stacksiz │ 90a1e1af │ generic.local.b │ FAIL  │ 0          │ 0.005164 │
│ e_unlimited     │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ ulimit_max_user │ 13a393be │ generic.local.b │ FAIL  │ 0          │ 0.005362 │
│ _process_2048   │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ ulimit_max_user │ 4238cc61 │ generic.local.b │ FAIL  │ 0          │ 0.005393 │
│ _process_2048   │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ systemd_default │ 15d8d29e │ generic.local.b │ FAIL  │ 1          │ 0.130304 │
│ _target         │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ systemd_default │ e55308ef │ generic.local.b │ FAIL  │ 1          │ 0.007566 │
│ _target         │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ systemd_default │ ba85aacd │ generic.local.b │ FAIL  │ 1          │ 0.007452 │
│ _target         │          │ ash             │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ tcsh_env_declar │ 5ae863ac │ generic.local.c │ FAIL  │ 1          │ 2.220863 │
│ ation           │          │ sh              │       │            │          │
├─────────────────┼──────────┼─────────────────┼───────┼────────────┼──────────┤
│ sleep           │ d3e2c211 │ generic.local.b │ FAIL  │ -9         │ 1.003268 │
│                 │          │ ash             │       │            │          │
└─────────────────┴──────────┴─────────────────┴───────┴────────────┴──────────┘

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]  ...

optional arguments:
  -h, --help  show this help message and exit

subcommands:
  Inspect Test result based on Test ID or Test Name

  
    buildspec
              Inspect a test based on buildspec
    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
                      Test Summary by name, id, buildspec                       
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ id                      ┃ name                     ┃ buildspec               ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 272ee591-cc98-4f24-9be… │ variables_bash           │ /home/docs/checkouts/re │
│                         │                          │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ v0.15.0/tutorials/vars. │
│                         │                          │ yml                     │
│ e63eab39-0a46-40c6-ac1… │ variables_bash           │ /home/docs/checkouts/re │
│                         │                          │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ v0.15.0/tutorials/vars. │
│                         │                          │ yml                     │
│ 7250a603-b378-4077-8d5… │ variables_bash           │ /home/docs/checkouts/re │
│                         │                          │ adthedocs.org/user_buil │
│                         │                          │ ds/buildtest/checkouts/ │
│                         │                          │ v0.15.0/tutorials/vars. │
│                         │                          │ yml                     │
│ 182dde6b-8711-425d-812… │ variables_bash           │ /home/docs/checkouts/re │
...

You can fetch all builder names via buildtest inspect list --builder which is the format used for querying test records via buildtest inspect name or buildtest inspect query.

$ buildtest inspect list --builder
variables_bash/272ee591-cc98-4f24-9bee-b02884bb4cca
variables_bash/e63eab39-0a46-40c6-ac18-aa92739bce0e
variables_bash/7250a603-b378-4077-8d53-dff2ea8d9dfd
variables_bash/182dde6b-8711-425d-8129-fd94a97c8a92
variables_bash/14eff1ce-82f3-4faf-bec9-e1f6a72a54b9
...

If you are interested in parsing output of buildtest inspect list, you can may find the --terse option useful. The output will show headers followed by entries, the headers can be omitted by specifying --no-header option.

$ buildtest inspect list -t
id|name|buildspec
272ee591-cc98-4f24-9bee-b02884bb4cca|variables_bash|/home/docs/checkouts/readthe
docs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/vars.yml
e63eab39-0a46-40c6-ac18-aa92739bce0e|variables_bash|/home/docs/checkouts/readthe
docs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/vars.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
We have detected 1 builders with the following names 
['circle_area/8882fde2-0186-4db5-a34a-2816fbf18c5b']
{
│   'circle_area': [
│   │   {
│   │   │   '8882fde2-0186-4db5-a34a-2816fbf18c5b': {
│   │   │   │   'id': '8882fde2',
│   │   │   │   'full_id': '8882fde2-0186-4db5-a34a-2816fbf18c5b',
│   │   │   │   'description': 'Calculate circle of area given a radius',
│   │   │   │   'summary': '',
│   │   │   │   'schemafile': 'script.schema.json',
│   │   │   │   'executor': 'generic.local.bash',
│   │   │   │   'compiler': None,
│   │   │   │   'hostname': 'build-17326554-project-280831-buildtest',
│   │   │   │   'user': 'docs',
│   │   │   │   'testroot': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2',
│   │   │   │   'testpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/circle_area.sh',
│   │   │   │   'stagedir': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/stage',
│   │   │   │   'command': 'bash --norc --noprofile -eo pipefail circle_area_build.sh',
│   │   │   │   'outfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/circle_area.out',
│   │   │   │   'errfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/circle_area.err',
│   │   │   │   'buildenv': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/build-env.txt',
│   │   │   │   'buildspec_content': 'buildspecs:\n  circle_area:\n    executor: generic.local.bash\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.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/stage/circle_area.py',
│   │   │   │   'buildscript_content': '#!/bin/bash\nexport BUILDTEST_TEST_NAME=circle_area\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/stage\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/stage/circle_area.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode',
│   │   │   │   'logpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/logs/buildtest_xpgwkubl.log',
│   │   │   │   'metrics': {},
│   │   │   │   'check': {
│   │   │   │   │   'returncode': 'N/A',
│   │   │   │   │   'regex': 'N/A',
│   │   │   │   │   'runtime': 'N/A'
│   │   │   │   },
│   │   │   │   'tags': 'tutorials python',
│   │   │   │   'starttime': '2022/07/01 00:38:51',
│   │   │   │   'endtime': '2022/07/01 00:38:51',
│   │   │   │   'runtime': '0.029671',
│   │   │   │   'state': 'PASS',
│   │   │   │   'returncode': '0',
│   │   │   │   'output': 'Circle Radius  2\nArea of circle  12.566370614359172\n',
│   │   │   │   'error': '',
│   │   │   │   'job': {},
│   │   │   │   'build_script': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/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
We have detected 1 builders with the following names 
['python_hello/69cd22ea-9a80-4b0f-9d03-ebcb1e575890']
{
│   'python_hello': [
│   │   {
│   │   │   '69cd22ea-9a80-4b0f-9d03-ebcb1e575890': {
│   │   │   │   'id': '69cd22ea',
│   │   │   │   'full_id': '69cd22ea-9a80-4b0f-9d03-ebcb1e575890',
│   │   │   │   'description': 'Hello World python',
│   │   │   │   'summary': '',
│   │   │   │   'schemafile': 'script.schema.json',
│   │   │   │   'executor': 'generic.local.bash',
│   │   │   │   'compiler': None,
│   │   │   │   'hostname': 'build-17326554-project-280831-buildtest',
│   │   │   │   'user': 'docs',
│   │   │   │   'testroot': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-hello/python_hello/69cd22ea',
│   │   │   │   'testpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-hello/python_hello/69cd22ea/python_hello.sh',
│   │   │   │   'stagedir': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-hello/python_hello/69cd22ea/stage',
│   │   │   │   'command': 'bash --norc --noprofile -eo pipefail python_hello_build.sh',
│   │   │   │   'outfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-hello/python_hello/69cd22ea/python_hello.out',
│   │   │   │   'errfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-hello/python_hello/69cd22ea/python_hello.err',
│   │   │   │   'buildenv': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-hello/python_hello/69cd22ea/build-env.txt',
│   │   │   │   'buildspec_content': 'buildspecs:\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': '#!/usr/bin/bash \n# Content of run section\npython hello.py',
│   │   │   │   'buildscript_content': '#!/bin/bash\nexport BUILDTEST_TEST_NAME=python_hello\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-hello/python_hello/69cd22ea\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-hello/python_hello/69cd22ea/stage\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-hello/python_hello/69cd22ea/stage/python_hello.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode',
│   │   │   │   'logpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/logs/buildtest_purt64at.log',
│   │   │   │   'metrics': {},
│   │   │   │   'check': {
│   │   │   │   │   'returncode': 'N/A',
│   │   │   │   │   'regex': 'N/A',
│   │   │   │   │   'runtime': 'N/A'
│   │   │   │   },
│   │   │   │   'tags': 'python',
│   │   │   │   'starttime': '2022/07/01 00:38:48',
│   │   │   │   'endtime': '2022/07/01 00:38:48',
│   │   │   │   'runtime': '0.03025',
│   │   │   │   'state': 'PASS',
│   │   │   │   'returncode': '0',
│   │   │   │   'output': 'Hello World\n',
│   │   │   │   'error': '',
│   │   │   │   'job': {},
│   │   │   │   'build_script': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/python-hello/python_hello/69cd22ea/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.15.0/tutorials/vars.yml': {
│   │   'variables_bash': {
│   │   │   'id': '14eff1ce',
│   │   │   'full_id': '14eff1ce-82f3-4faf-bec9-e1f6a72a54b9',
│   │   │   'description': 'Declare shell variables in bash',
│   │   │   'summary': '',
│   │   │   'schemafile': 'script.schema.json',
│   │   │   'executor': 'generic.local.bash',
│   │   │   'compiler': None,
│   │   │   'hostname': 'build-17326554-project-280831-buildtest',
│   │   │   'user': 'docs',
│   │   │   'testroot': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce',
│   │   │   'testpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/variables_bash.sh',
│   │   │   'stagedir': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/stage',
│   │   │   'command': 'bash --norc --noprofile -eo pipefail variables_bash_build.sh',
│   │   │   'outfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/variables_bash.out',
│   │   │   'errfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/variables_bash.err',
│   │   │   'buildenv': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/build-env.txt',
│   │   │   'buildspec_content': 'buildspecs:\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: 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      multiline_string: |\n        Hello my name is Bob \\n\n        I am 30 years old\n\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\n      echo -e $multiline_string\n',
│   │   │   'test_content': '#!/usr/bin/bash \nX="1"\nY="2"\nliteralstring="this is a literal string"\nsinglequote="\\\'singlequote\\\'"\ndoublequote="\\"doublequote\\""\ncurrent_user="$(whoami)"\nnum_files="`find $HOME -type f -maxdepth 1 | wc -l`"\nmultiline_string="Hello my name is Bob \\n\nI am 30 years old\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\necho -e $multiline_string\n',
│   │   │   'buildscript_content': '#!/bin/bash\nexport BUILDTEST_TEST_NAME=variables_bash\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/stage\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/stage/variables_bash.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode',
│   │   │   'logpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/logs/buildtest_2huuxmu8.log',
│   │   │   'metrics': {},
│   │   │   'check': {'returncode': 'N/A', 'regex': 'N/A', 'runtime': 'N/A'},
│   │   │   'tags': 'tutorials',
│   │   │   'starttime': '2022/07/01 00:38:54',
│   │   │   'endtime': '2022/07/01 00:38:54',
│   │   │   'runtime': '0.008847',
│   │   │   'state': 'PASS',
│   │   │   'returncode': '0',
│   │   │   'output': '1+2=3\nthis is a literal string\n\\\'singlequote\\\'\n"doublequote"\ncurrent user: docs\nnumber of files: 4\nHello my name is Bob \n I am 30 years old\n',
│   │   │   'error': '',
│   │   │   'job': {},
│   │   │   'build_script': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/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/hello_world.yml

$ buildtest it buildspec --all tutorials/vars.yml tutorials/hello_world.yml
{
│   '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/vars.yml': {
│   │   'variables_bash': [
│   │   │   {
│   │   │   │   'id': '272ee591',
│   │   │   │   'full_id': '272ee591-cc98-4f24-9bee-b02884bb4cca',
│   │   │   │   'description': 'Declare shell variables in bash',
│   │   │   │   'summary': '',
│   │   │   │   'schemafile': 'script.schema.json',
│   │   │   │   'executor': 'generic.local.bash',
│   │   │   │   'compiler': None,
│   │   │   │   'hostname': 'build-17326554-project-280831-buildtest',
│   │   │   │   'user': 'docs',
│   │   │   │   'testroot': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/272ee591',
│   │   │   │   'testpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/272ee591/variables_bash.sh',
│   │   │   │   'stagedir': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/272ee591/stage',
│   │   │   │   'command': 'bash --norc --noprofile -eo pipefail variables_bash_build.sh',
│   │   │   │   'outfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/272ee591/variables_bash.out',
│   │   │   │   'errfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/272ee591/variables_bash.err',
│   │   │   │   'buildenv': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/272ee591/build-env.txt',
│   │   │   │   'buildspec_content': 'buildspecs:\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: 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      multiline_string: |\n        Hello my name is Bob \\n\n        I am 30 years old\n\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\n      echo -e $multiline_string\n',
│   │   │   │   'test_content': '#!/usr/bin/bash \nX="1"\nY="2"\nliteralstring="this is a literal string"\nsinglequote="\\\'singlequote\\\'"\ndoublequote="\\"doublequote\\""\ncurrent_user="$(whoami)"\nnum_files="`find $HOME -type f -maxdepth 1 | wc -l`"\nmultiline_string="Hello my name is Bob \\n\nI am 30 years old\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\necho -e $multiline_string\n',
│   │   │   │   'buildscript_content': '#!/bin/bash\nexport BUILDTEST_TEST_NAME=variables_bash\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/272ee591\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/272ee591/stage\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/272ee591/stage/variables_bash.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode',
│   │   │   │   'logpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/logs/buildtest_t1me5pr5.log',
│   │   │   │   'metrics': {},
│   │   │   │   'check': {
│   │   │   │   │   'returncode': 'N/A',
│   │   │   │   │   'regex': 'N/A',
│   │   │   │   │   'runtime': 'N/A'
│   │   │   │   },
│   │   │   │   'tags': 'tutorials',
│   │   │   │   'starttime': '2022/07/01 00:37:31',
│   │   │   │   'endtime': '2022/07/01 00:37:31',
│   │   │   │   'runtime': '0.010049',
│   │   │   │   'state': 'PASS',
│   │   │   │   'returncode': '0',
│   │   │   │   'output': '1+2=3\nthis is a literal string\n\\\'singlequote\\\'\n"doublequote"\ncurrent user: docs\nnumber of files: 4\nHello my name is Bob \n I am 30 years old\n',
│   │   │   │   'error': '',
│   │   │   │   'job': {},
│   │   │   │   'build_script': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/272ee591/variables_bash_build.sh'
│   │   │   },
│   │   │   {
│   │   │   │   'id': 'e63eab39',
│   │   │   │   'full_id': 'e63eab39-0a46-40c6-ac18-aa92739bce0e',
│   │   │   │   'description': 'Declare shell variables in bash',
│   │   │   │   'summary': '',
│   │   │   │   'schemafile': 'script.schema.json',
│   │   │   │   'executor': 'generic.local.bash',
│   │   │   │   'compiler': None,
│   │   │   │   'hostname': 'build-17326554-project-280831-buildtest',
│   │   │   │   'user': 'docs',
│   │   │   │   'testroot': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/e63eab39',
│   │   │   │   'testpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/e63eab39/variables_bash.sh',
│   │   │   │   'stagedir': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/e63eab39/stage',
│   │   │   │   'command': 'bash --norc --noprofile -eo pipefail variables_bash_build.sh',
│   │   │   │   'outfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/e63eab39/variables_bash.out',
│   │   │   │   'errfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/e63eab39/variables_bash.err',
│   │   │   │   'buildenv': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/e63eab39/build-env.txt',
│   │   │   │   'buildspec_content': 'buildspecs:\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: 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      multiline_string: |\n        Hello my name is Bob \\n\n        I am 30 years old\n\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\n      echo -e $multiline_string\n',
│   │   │   │   'test_content': '#!/usr/bin/bash \nX="1"\nY="2"\nliteralstring="this is a literal string"\nsinglequote="\\\'singlequote\\\'"\ndoublequote="\\"doublequote\\""\ncurrent_user="$(whoami)"\nnum_files="`find $HOME -type f -maxdepth 1 | wc -l`"\nmultiline_string="Hello my name is Bob \\n\nI am 30 years old\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\necho -e $multiline_string\n',
│   │   │   │   'buildscript_content': '#!/bin/bash\nexport BUILDTEST_TEST_NAME=variables_bash\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/e63eab39\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/e63eab39/stage\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/e63eab39/stage/variables_bash.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode',
│   │   │   │   'logpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/logs/buildtest_wr0fx1oi.log',
│   │   │   │   'metrics': {},
│   │   │   │   'check': {
│   │   │   │   │   'returncode': 'N/A',
│   │   │   │   │   'regex': 'N/A',
│   │   │   │   │   'runtime': 'N/A'
│   │   │   │   },
│   │   │   │   'tags': 'tutorials',
│   │   │   │   'starttime': '2022/07/01 00:38:26',
│   │   │   │   'endtime': '2022/07/01 00:38:26',
│   │   │   │   'runtime': '0.008703',
│   │   │   │   'state': 'PASS',
│   │   │   │   'returncode': '0',
│   │   │   │   'output': '1+2=3\nthis is a literal string\n\\\'singlequote\\\'\n"doublequote"\ncurrent user: docs\nnumber of files: 4\nHello my name is Bob \n I am 30 years old\n',
│   │   │   │   'error': '',
│   │   │   │   'job': {},
│   │   │   │   'build_script': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/e63eab39/variables_bash_build.sh'
│   │   │   },
│   │   │   {
│   │   │   │   'id': '7250a603',
│   │   │   │   'full_id': '7250a603-b378-4077-8d53-dff2ea8d9dfd',
│   │   │   │   'description': 'Declare shell variables in bash',
│   │   │   │   'summary': '',
│   │   │   │   'schemafile': 'script.schema.json',
│   │   │   │   'executor': 'generic.local.bash',
│   │   │   │   'compiler': None,
│   │   │   │   'hostname': 'build-17326554-project-280831-buildtest',
│   │   │   │   'user': 'docs',
│   │   │   │   'testroot': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/7250a603',
│   │   │   │   'testpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/7250a603/variables_bash.sh',
│   │   │   │   'stagedir': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/7250a603/stage',
│   │   │   │   'command': 'bash --norc --noprofile -eo pipefail variables_bash_build.sh',
│   │   │   │   'outfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/7250a603/variables_bash.out',
│   │   │   │   'errfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/7250a603/variables_bash.err',
│   │   │   │   'buildenv': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/7250a603/build-env.txt',
│   │   │   │   'buildspec_content': 'buildspecs:\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: 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      multiline_string: |\n        Hello my name is Bob \\n\n        I am 30 years old\n\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\n      echo -e $multiline_string\n',
│   │   │   │   'test_content': '#!/usr/bin/bash \nX="1"\nY="2"\nliteralstring="this is a literal string"\nsinglequote="\\\'singlequote\\\'"\ndoublequote="\\"doublequote\\""\ncurrent_user="$(whoami)"\nnum_files="`find $HOME -type f -maxdepth 1 | wc -l`"\nmultiline_string="Hello my name is Bob \\n\nI am 30 years old\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\necho -e $multiline_string\n',
│   │   │   │   'buildscript_content': '#!/bin/bash\nexport BUILDTEST_TEST_NAME=variables_bash\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/7250a603\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/7250a603/stage\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/7250a603/stage/variables_bash.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode',
│   │   │   │   'logpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/logs/buildtest_smj9bp3o.log',
│   │   │   │   'metrics': {},
│   │   │   │   'check': {
│   │   │   │   │   'returncode': 'N/A',
│   │   │   │   │   'regex': 'N/A',
│   │   │   │   │   'runtime': 'N/A'
│   │   │   │   },
│   │   │   │   'tags': 'tutorials',
│   │   │   │   'starttime': '2022/07/01 00:38:53',
│   │   │   │   'endtime': '2022/07/01 00:38:53',
│   │   │   │   'runtime': '0.008886',
│   │   │   │   'state': 'PASS',
│   │   │   │   'returncode': '0',
│   │   │   │   'output': '1+2=3\nthis is a literal string\n\\\'singlequote\\\'\n"doublequote"\ncurrent user: docs\nnumber of files: 4\nHello my name is Bob \n I am 30 years old\n',
│   │   │   │   'error': '',
│   │   │   │   'job': {},
│   │   │   │   'build_script': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/7250a603/variables_bash_build.sh'
│   │   │   },
│   │   │   {
│   │   │   │   'id': '182dde6b',
│   │   │   │   'full_id': '182dde6b-8711-425d-8129-fd94a97c8a92',
│   │   │   │   'description': 'Declare shell variables in bash',
│   │   │   │   'summary': '',
│   │   │   │   'schemafile': 'script.schema.json',
│   │   │   │   'executor': 'generic.local.bash',
│   │   │   │   'compiler': None,
│   │   │   │   'hostname': 'build-17326554-project-280831-buildtest',
│   │   │   │   'user': 'docs',
│   │   │   │   'testroot': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/182dde6b',
│   │   │   │   'testpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/182dde6b/variables_bash.sh',
│   │   │   │   'stagedir': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/182dde6b/stage',
│   │   │   │   'command': 'bash --norc --noprofile -eo pipefail variables_bash_build.sh',
│   │   │   │   'outfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/182dde6b/variables_bash.out',
│   │   │   │   'errfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/182dde6b/variables_bash.err',
│   │   │   │   'buildenv': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/182dde6b/build-env.txt',
│   │   │   │   'buildspec_content': 'buildspecs:\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: 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      multiline_string: |\n        Hello my name is Bob \\n\n        I am 30 years old\n\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\n      echo -e $multiline_string\n',
│   │   │   │   'test_content': '#!/usr/bin/bash \nX="1"\nY="2"\nliteralstring="this is a literal string"\nsinglequote="\\\'singlequote\\\'"\ndoublequote="\\"doublequote\\""\ncurrent_user="$(whoami)"\nnum_files="`find $HOME -type f -maxdepth 1 | wc -l`"\nmultiline_string="Hello my name is Bob \\n\nI am 30 years old\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\necho -e $multiline_string\n',
│   │   │   │   'buildscript_content': '#!/bin/bash\nexport BUILDTEST_TEST_NAME=variables_bash\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/182dde6b\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/182dde6b/stage\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/182dde6b/stage/variables_bash.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode',
│   │   │   │   'logpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/logs/buildtest_24wokdyd.log',
│   │   │   │   'metrics': {},
│   │   │   │   'check': {
│   │   │   │   │   'returncode': 'N/A',
│   │   │   │   │   'regex': 'N/A',
│   │   │   │   │   'runtime': 'N/A'
│   │   │   │   },
│   │   │   │   'tags': 'tutorials',
│   │   │   │   'starttime': '2022/07/01 00:38:54',
│   │   │   │   'endtime': '2022/07/01 00:38:54',
│   │   │   │   'runtime': '0.009069',
│   │   │   │   'state': 'PASS',
│   │   │   │   'returncode': '0',
│   │   │   │   'output': '1+2=3\nthis is a literal string\n\\\'singlequote\\\'\n"doublequote"\ncurrent user: docs\nnumber of files: 4\nHello my name is Bob \n I am 30 years old\n',
│   │   │   │   'error': '',
│   │   │   │   'job': {},
│   │   │   │   'build_script': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/182dde6b/variables_bash_build.sh'
│   │   │   },
│   │   │   {
│   │   │   │   'id': '14eff1ce',
│   │   │   │   'full_id': '14eff1ce-82f3-4faf-bec9-e1f6a72a54b9',
│   │   │   │   'description': 'Declare shell variables in bash',
│   │   │   │   'summary': '',
│   │   │   │   'schemafile': 'script.schema.json',
│   │   │   │   'executor': 'generic.local.bash',
│   │   │   │   'compiler': None,
│   │   │   │   'hostname': 'build-17326554-project-280831-buildtest',
│   │   │   │   'user': 'docs',
│   │   │   │   'testroot': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce',
│   │   │   │   'testpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/variables_bash.sh',
│   │   │   │   'stagedir': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/stage',
│   │   │   │   'command': 'bash --norc --noprofile -eo pipefail variables_bash_build.sh',
│   │   │   │   'outfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/variables_bash.out',
│   │   │   │   'errfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/variables_bash.err',
│   │   │   │   'buildenv': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/build-env.txt',
│   │   │   │   'buildspec_content': 'buildspecs:\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: 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      multiline_string: |\n        Hello my name is Bob \\n\n        I am 30 years old\n\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\n      echo -e $multiline_string\n',
│   │   │   │   'test_content': '#!/usr/bin/bash \nX="1"\nY="2"\nliteralstring="this is a literal string"\nsinglequote="\\\'singlequote\\\'"\ndoublequote="\\"doublequote\\""\ncurrent_user="$(whoami)"\nnum_files="`find $HOME -type f -maxdepth 1 | wc -l`"\nmultiline_string="Hello my name is Bob \\n\nI am 30 years old\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\necho -e $multiline_string\n',
│   │   │   │   'buildscript_content': '#!/bin/bash\nexport BUILDTEST_TEST_NAME=variables_bash\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/stage\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/stage/variables_bash.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode',
│   │   │   │   'logpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/logs/buildtest_2huuxmu8.log',
│   │   │   │   'metrics': {},
│   │   │   │   'check': {
│   │   │   │   │   'returncode': 'N/A',
│   │   │   │   │   'regex': 'N/A',
│   │   │   │   │   'runtime': 'N/A'
│   │   │   │   },
│   │   │   │   'tags': 'tutorials',
│   │   │   │   'starttime': '2022/07/01 00:38:54',
│   │   │   │   'endtime': '2022/07/01 00:38:54',
│   │   │   │   'runtime': '0.008847',
│   │   │   │   'state': 'PASS',
│   │   │   │   'returncode': '0',
│   │   │   │   'output': '1+2=3\nthis is a literal string\n\\\'singlequote\\\'\n"doublequote"\ncurrent user: docs\nnumber of files: 4\nHello my name is Bob \n I am 30 years old\n',
│   │   │   │   'error': '',
│   │   │   │   'job': {},
│   │   │   │   'build_script': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/vars/variables_bash/14eff1ce/variables_bash_build.sh'
│   │   │   }
│   │   ]
│   },
│   '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/hello_world.yml': {
│   │   'hello_world': [
│   │   │   {
│   │   │   │   'id': 'be2dc26b',
│   │   │   │   'full_id': 'be2dc26b-dd03-4956-91cb-b1272f5f18f4',
│   │   │   │   'description': 'hello world example',
│   │   │   │   'summary': '',
│   │   │   │   'schemafile': 'script.schema.json',
│   │   │   │   'executor': 'generic.local.bash',
│   │   │   │   'compiler': None,
│   │   │   │   'hostname': 'build-17326554-project-280831-buildtest',
│   │   │   │   'user': 'docs',
│   │   │   │   'testroot': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/hello_world/hello_world/be2dc26b',
│   │   │   │   'testpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/hello_world/hello_world/be2dc26b/hello_world.sh',
│   │   │   │   'stagedir': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/hello_world/hello_world/be2dc26b/stage',
│   │   │   │   'command': 'bash --norc --noprofile -eo pipefail hello_world_build.sh',
│   │   │   │   'outfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/hello_world/hello_world/be2dc26b/hello_world.out',
│   │   │   │   'errfile': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/hello_world/hello_world/be2dc26b/hello_world.err',
│   │   │   │   'buildenv': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/hello_world/hello_world/be2dc26b/build-env.txt',
│   │   │   │   'buildspec_content': 'buildspecs:\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': '#!/usr/bin/bash \n# Content of run section\necho "hello world!"',
│   │   │   │   'buildscript_content': '#!/bin/bash\nexport BUILDTEST_TEST_NAME=hello_world\nexport BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/hello_world/hello_world/be2dc26b\nexport BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials\nexport BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/hello_world/hello_world/be2dc26b/stage\n# source executor startup script\nsource /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/executor/generic.local.bash/before_script.sh\n# Run generated script\n/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/hello_world/hello_world/be2dc26b/stage/hello_world.sh\n# Get return code\nreturncode=$?\n# Exit with return code\nexit $returncode',
│   │   │   │   'logpath': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/logs/buildtest_6428g0rq.log',
│   │   │   │   'metrics': {},
│   │   │   │   'check': {
│   │   │   │   │   'returncode': 'N/A',
│   │   │   │   │   'regex': 'N/A',
│   │   │   │   │   'runtime': 'N/A'
│   │   │   │   },
│   │   │   │   'tags': 'tutorials',
│   │   │   │   'starttime': '2022/07/01 00:38:46',
│   │   │   │   'endtime': '2022/07/01 00:38:46',
│   │   │   │   'runtime': '0.005457',
│   │   │   │   'state': 'PASS',
│   │   │   │   'returncode': '0',
│   │   │   │   'output': 'hello world!\n',
│   │   │   │   'error': '',
│   │   │   │   'job': {},
│   │   │   │   'build_script': '/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var/tests/generic.local.bash/hello_world/hello_world/be2dc26b/hello_world_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.15.0/tutorials/vars.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/test_status/pass_returncode.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/test_status/status_regex.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/test_status/runtime_status_test.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/test_status/explicit_state.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/shebang.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/skip_tests.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/metrics_regex.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/job_dependency/ex1.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/job_dependency/ex2.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/job_dependency/ex3.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/job_dependency/ex4.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/multi_executors/executor_regex_script.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/multi_executors/executors_var_env_declaration.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/multi_executors/executor_scheduler.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/multi_executors/status_by_executors.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/general_tests/configuration/kernel_state.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/general_tests/configuration/ulimits.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/general_tests/configuration/systemd-default-target.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/general_tests/configuration/disk_usage.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/tags_example.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/python-shell.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/python-hello.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/environment.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/csh_shell_examples.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/hello_world.yml
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/tutorials/sleep.yml

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] [-be] [-e] [-o]
                                                    [-t]
                                                    [name [name ...]]

positional arguments:
  name               Name of builder to query in report file

optional arguments:
  -h, --help         show this help message and exit
  -b, --buildscript  Print build script
  -be, --buildenv    Print content of build env
  -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/8882fde2-0186-4db5-a34a-2816fbf18c5b ───────────────
Executor: generic.local.bash
Description: Calculate circle of area given a radius
State: PASS
Returncode: 0
Runtime: 0.029671 sec
Starttime: 2022/07/01 00:38:51
Endtime: 2022/07/01 00:38:51
Command: bash --norc --noprofile -eo pipefail circle_area_build.sh
Test Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/circle_
area.sh
Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkou
ts/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/circle
_area_build.sh
Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/circle_
area.out
Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts
/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/circle_a
rea.err
Log File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v
0.15.0/var/logs/buildtest_xpgwkubl.log

buildtest will display metadata for each test. By default, buildtest will report the last run for each test that is specified as a positional argument.

You can retrieve content of output file via --output or short option -o. In this command, we retrieve the last run for circle_area and print content of output file

$ buildtest inspect query -o circle_area
─────────────── circle_area/8882fde2-0186-4db5-a34a-2816fbf18c5b ───────────────
Executor: generic.local.bash
Description: Calculate circle of area given a radius
State: PASS
Returncode: 0
Runtime: 0.029671 sec
Starttime: 2022/07/01 00:38:51
Endtime: 2022/07/01 00:38:51
Command: bash --norc --noprofile -eo pipefail circle_area_build.sh
Test Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/circle_
area.sh
Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkou
ts/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/circle
_area_build.sh
Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/circle_
area.out
Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts
/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/circle_a
rea.err
Log File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v
0.15.0/var/logs/buildtest_xpgwkubl.log
─ Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/che… ─
Circle Radius  2                                                                
Area of circle  12.566370614359172

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 query test circle_area and report all of the content fields

$ buildtest inspect query -o -e -t -b circle_area
─────────────── circle_area/8882fde2-0186-4db5-a34a-2816fbf18c5b ───────────────
Executor: generic.local.bash
Description: Calculate circle of area given a radius
State: PASS
Returncode: 0
Runtime: 0.029671 sec
Starttime: 2022/07/01 00:38:51
Endtime: 2022/07/01 00:38:51
Command: bash --norc --noprofile -eo pipefail circle_area_build.sh
Test Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/circle_
area.sh
Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkou
ts/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/circle
_area_build.sh
Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/circle_
area.out
Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts
/v0.15.0/var/tests/generic.local.bash/python-shell/circle_area/8882fde2/circle_a
rea.err
Log File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v
0.15.0/var/logs/buildtest_xpgwkubl.log
─ Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/che… ─
Circle Radius  2                                                                
Area of circle  12.566370614359172                                              
                                                                                
─ Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/chec… ─
                                                                                
─ Test File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/check… ─
#!/bin/bash                                                                     
python /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.1
─ Test File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/check… ─
#!/bin/bash                                                                     
export BUILDTEST_TEST_NAME=circle_area                                          
export BUILDTEST_TEST_ROOT=/home/docs/checkouts/readthedocs.org/user_builds/buil
export BUILDTEST_BUILDSPEC_DIR=/home/docs/checkouts/readthedocs.org/user_builds/
export BUILDTEST_STAGE_DIR=/home/docs/checkouts/readthedocs.org/user_builds/buil
# source executor startup script                                                
source /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.1
# Run generated script                                                          
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var
# Get return code                                                               
returncode=$?                                                                   
# Exit with return code                                                         
exit $returncode

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/585f174b-4aa5-4639-a529-ff28e49d8566 ─────────────
Executor: generic.local.bash
Description: Check root disk usage and report if it exceeds threshold
State: PASS
Returncode: 0
Runtime: 0.008999 sec
Starttime: 2022/07/01 00:38:27
Endtime: 2022/07/01 00:38:27
Command: bash --norc --noprofile -eo pipefail root_disk_usage_build.sh
Test Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/v0.15.0/var/tests/generic.local.bash/disk_usage/root_disk_usage/585f174b/root_
disk_usage.sh
Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkou
ts/v0.15.0/var/tests/generic.local.bash/disk_usage/root_disk_usage/585f174b/root
_disk_usage_build.sh
Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/v0.15.0/var/tests/generic.local.bash/disk_usage/root_disk_usage/585f174b/root_
disk_usage.out
Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts
/v0.15.0/var/tests/generic.local.bash/disk_usage/root_disk_usage/585f174b/root_d
isk_usage.err
Log File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v
0.15.0/var/logs/buildtest_msp92vd9.log
─ Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/che… ─
[OK] Root disk is below threshold of 90%                                        
                                                                                
────────────── python_hello/69cd22ea-9a80-4b0f-9d03-ebcb1e575890 ───────────────
Executor: generic.local.bash
Description: Hello World python
State: PASS
Returncode: 0
Runtime: 0.03025 sec
Starttime: 2022/07/01 00:38:48
Endtime: 2022/07/01 00:38:48
Command: bash --norc --noprofile -eo pipefail python_hello_build.sh
Test Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/v0.15.0/var/tests/generic.local.bash/python-hello/python_hello/69cd22ea/python
_hello.sh
Build Script: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkou
ts/v0.15.0/var/tests/generic.local.bash/python-hello/python_hello/69cd22ea/pytho
n_hello_build.sh
Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkout
s/v0.15.0/var/tests/generic.local.bash/python-hello/python_hello/69cd22ea/python
_hello.out
Error File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts
/v0.15.0/var/tests/generic.local.bash/python-hello/python_hello/69cd22ea/python_
hello.err
Log File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v
0.15.0/var/logs/buildtest_purt64at.log
─ Output File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/che… ─
Hello World

If you want to query specific test ID, you can specify name of test followed by / and test ID. You don’t need to specify the full ID however tab completion is available to help fill in the names. For example if you want to query test record for circle_area/8edce927-2ecc-4991-ac40-e376c03394b4 shown in tab completion you can type a first few characters to query the record

$ buildtest inspect query circle_area/
circle_area/08f20b50-d2e2-41ab-a75e-a7df75e5afcc  circle_area/8edce927-2ecc-4991-ac40-e376c03394b4  circle_area/d47b6ba8-71b6-4531-b8cd-b6ba9b5f0c6c
circle_area/237c3a96-fad0-4ab7-ab1f-3e7ed1816955  circle_area/baea2e9b-a187-4f9f-bcea-75e768ccb0e0  circle_area/e6652700-4cdb-4f6b-80c5-261e4f448876
circle_area/2c279160-1abf-4c70-957f-d9e4608f521b  circle_area/bf8f1762-ebf9-458e-92e2-af3fc6e73eac  circle_area/e7cc7138-a650-4cd8-aca8-b904f901a0da

$ buildtest inspect query circle_area/8ed
──────────────────────────────────────────────────────────────────────────────────────────── circle_area/8edce927-2ecc-4991-ac40-e376c03394b4 ─────────────────────────────────────────────────────────────────────────────────────────────
Executor: generic.local.bash
Description: Calculate circle of area given a radius
State: PASS
Returncode: 0
Runtime: 0.360774 sec
Starttime: 2021/12/23 12:37:25
Endtime: 2021/12/23 12:37:25
Command: bash --norc --noprofile -eo pipefail circle_area_build.sh
Test Script: /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/python-shell/circle_area/8edce927/circle_area.sh
Build Script: /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/python-shell/circle_area/8edce927/circle_area_build.sh
Output File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/python-shell/circle_area/8edce927/circle_area.out
Error File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/tests/generic.local.bash/python-shell/circle_area/8edce927/circle_area.err
Log File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/logs/buildtest_c5dnun2l.log

buildtest will search for test ID using re.match so it is possible to apply a regular expression to seek out multiple test records. The tests must be enclosed in quotes " in-order to have a valid regular expression. Here are few examples that can be useful

# retrieve all test records for name `circle_area`
buildtest inspect query circle_area/

# retrieve test records starting with ID `8a` and `bc` for test name `exit1`
buildtest inspect query "exit1/(8a|bc)"

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 -r <report_path> build -b <buildspec_path> 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 -r <report_path> report and buildtest -r <report_path> inspect 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 -r $BUILDTEST_ROOT/python.json report --format name,id
                      Report File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/python.json
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ name                                                               ┃ id                                            ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ circle_area                                                        │ a2814554                                      │
├────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ python_hello                                                       │ dd447e43                                      │
└────────────────────────────────────────────────────────────────────┴───────────────────────────────────────────────┘

You can view path to all report files via buildtest report list which keeps track of any new report files created when using buildtest build -r option.

$ buildtest report list
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/var
/report.json
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.15.0/pyt
hon.json