:py:mod:`buildtest.cli.report` ============================== .. py:module:: buildtest.cli.report Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: buildtest.cli.report.Report Functions ~~~~~~~~~ .. autoapisummary:: buildtest.cli.report.is_int buildtest.cli.report.list_report buildtest.cli.report.clear_report buildtest.cli.report.report_cmd buildtest.cli.report.report_summary buildtest.cli.report.print_report_summary_output Attributes ~~~~~~~~~~ .. autoapisummary:: buildtest.cli.report.logger buildtest.cli.report.PASS buildtest.cli.report.FAIL .. py:data:: logger .. py:data:: PASS :value: 'PASS' .. py:data:: FAIL :value: 'FAIL' .. py:function:: is_int(val) Check if input is an integer by running `int() `_. If its successful we return **True** otherwise returns **False** .. py:class:: Report(configuration, **kwargs) :param configuration: Instance of SiteConfiguration class that is loaded buildtest configuration. :type configuration: buildtest.config.SiteConfiguration :param \*\*kwargs: Arbitrary keyword arguments. This will set report parameters for report class. .. py:attribute:: default_row_count :value: 50 .. py:attribute:: format_field_description .. py:attribute:: filter_field_description .. py:attribute:: format_fields .. py:attribute:: filter_fields .. py:attribute:: display_table .. py:attribute:: format_fields_detailed :value: 'name,id,user,state,returncode,runtime,outfile,errfile,buildspec' .. py:method:: set_report_parameters(**kwargs) Set report parameters for report class. .. py:method:: reportfile() Return full path to report file .. py:method:: get() Return raw content of report file .. py:method:: validate_filter_and_format_fields() .. py:method:: _check_filter_fields() This method will validate filter fields ``buildtest report --filter`` by checking if field is valid filter field. If one specifies an invalid filter field, we will raise an exception :raises BuildTestError: Raise exception if its in invalid filter field. If returncode is not an integer we raise exception .. py:method:: _check_format_fields() Check all format arguments (--format) are valid, the arguments are specified in format (--format key1=val1,key2=val2). We make sure each key is valid format field. :raises BuildTestError: If format field is not valid .. py:method:: _check_start_and_end_fields() Check start argument (--start) and end argument (--end) are valid. The start argument is specified in format (--start yyyy-mm-dd), end argument in format (--end yyyy-mm-dd), or both (--start yyyy-mm-dd --end yyyy-mm-dd). :raises BuildTestError: If --start is greater than --end or --end is greater than current time - datetime.datetime.now() .. py:method:: load_report() This method is responsible for loading report file. If file not found or report is empty dictionary we raise an error. The report file is loaded if its valid JSON file and returns as dictionary containing entire report of all tests. :raises SystemExit: If report file doesn't exist or path is not a file. If the report file is empty upon loading we raise an error. .. py:method:: validate_buildspec_filter() .. py:method:: validate_state_filter() .. py:method:: filter_buildspecs_from_report() This method filters the report table input filter ``--filter buildspec``. If entry found in buildspec cache we add to list .. py:method:: filter_by_start_end(test) This method will return a boolean (True/False) to check if test should be included from report. Given an input test, we check if a test record has 'starttime' and 'endtime' fields in range specified by ``--start`` and ``--end`` by the user. If there is a match we return ``True``. A ``False`` indicates the test will not be incldued in report. :param test: Test record loaded as dictionary :type test: dict .. py:method:: _filter_by_names(name) Filter test by name of test. This method will return True if record should be processed, otherwise returns False :param name: Name of test to filter :type name: str .. py:method:: _filter_by_tags(test) This method will return a boolean (True/False) to check if test should be skipped from report. Given an input test, we check if test has 'tags' property in buildspec and if tagnames specified by ``--filter tags`` are found in the test. If there is a match we return ``False``. A ``True`` indicates the test will be filtered out. :param test: Test recorded loaded as dictionary :type test: dict .. py:method:: _filter_by_executor(test) Filters test by ``executor`` property given input parameter ``buildtest report --filter executor:``. If there is **no** match we return ``True`` otherwise returns ``False``. :param test: Test recorded loaded as dictionary :type test: dict .. py:method:: _filter_by_state(test) This method filters test by ``state`` property based on input parameter ``buildtest report --filter state:``. If there is **no** match we return ``True`` otherwise returns ``False``. :param test: Test recorded loaded as dictionary :type test: dict .. py:method:: _filter_by_returncode(test) Returns True/False if test is filtered by returncode. We will get input returncode in filter field via ``buildtest report --filter returncode:`` with one in test and if there is a match we return ``True`` otherwise returns ``False``. :param test: Test recorded loaded as dictionary :type test: dict .. py:method:: process_report() .. py:method:: filter_tests(tests) .. py:method:: add_tests_to_display_table(tests, buildspec, name) .. py:method:: print_format_fields() Displays list of format field which implements command ``buildtest report --helpformat`` .. py:method:: print_filter_fields() Displays list of help filters which implements command ``buildtest report --helpfilter`` .. py:method:: print_raw_filter_fields() Print list of filter fields which implements command ``buildtest report --filterfields`` .. py:method:: print_raw_format_fields() Print list of format fields which implements command ``buildtest report --formatfields`` .. py:method:: print_report(terse=None, row_count=None, noheader=None, title=None, count=None, color=None) This method will print report table after processing report file. By default we print output in table format but this can be changed to terse format which will print output in parseable format. :param terse: Print output int terse format :type terse: bool, optional :param row_count: Print total number of records from the table :type row_count: bool, optional :param noheader: Determine whether to print header in terse format :type noheader: bool, optional :param title: Table title to print out :type title: str, optional :param count: Number of rows to be printed in terse format :type count: int, optional :param color: An instance of a string class that tells print_report what color the output should be printed in. :type color: str, optional In this example, we display output in tabular format which works with ``--filter`` and ``--format`` option. .. code-block:: console bash-3.2$ buildtest report --filter name=root_disk_usage --format name,state,returncode Reading report file: /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/report.json +-----------------+---------+--------------+ | name | state | returncode | +=================+=========+==============+ | root_disk_usage | PASS | 0 | +-----------------+---------+--------------+ | root_disk_usage | PASS | 0 | +-----------------+---------+--------------+ | root_disk_usage | PASS | 0 | +-----------------+---------+--------------+ In terse format each output is separated by PIPE symbol (**|***). The first row contains headers followed by content of the report. .. code-block:: console bash-3.2$ buildtest report --filter name=root_disk_usage --format name,state,returncode --terse name|state|returncode root_disk_usage|PASS|0 root_disk_usage|PASS|0 root_disk_usage|PASS|0 You can avoid printing the header table by specifying `--no-header` option .. code-block:: console bash-3.2$ buildtest report --filter name=root_disk_usage --format name,state,returncode --terse --no-header root_disk_usage|PASS|0 root_disk_usage|PASS|0 root_disk_usage|PASS|0 .. py:method:: latest_testid_by_name(name) Given a test name return test id of latest run :param name: Name of test to search in report file and retrieve corresponding test id :type name: str .. py:method:: get_names() Return a list of test names from report file .. py:method:: get_random_tests(num_items=1) Returns a list of random test names from the list of available test. The test are picked using `random.sample `_ :param num_items: Number of test items to retrieve :type num_items: int, optional .. py:method:: get_buildspecs() Return a list of buildspecs in report file .. py:method:: get_test_by_state(state) Return a list of test names by state from report file .. py:method:: get_testids() Return a list of test ids from the report file .. py:method:: _testid_lookup() Return a dict where `key` represents full id of test and value is a dictionary containing two values ``name`` and ``buildspec`` property which contains name of test and path to buildspec file. .. py:method:: lookup() Create a lookup dictionary with keys corresponding to name of test names and values are list of test ids. .. code-block:: python from buildtest.cli.report import Report r = Report() r.lookup() {'exit1_fail': ['913ce128-f425-488a-829d-d5d898113e8b', '54fc3dfe-50c5-4d2c-93fc-0c26364d215d', '70971081-84f9-462e-809b-a7d438a480bf'], 'exit1_pass': ['775a5545-bac5-468d-994d-85b22544306b', '0e908a64-fc81-4606-8ef4-78360563618e', '17082a05-ba32-4ef1-a38a-c2c6ea125bae', '3f50a73c-e333-4bbb-a722-aa5d72f98ac1', '964cd416-ad91-42be-bc1c-e25119f6df5d']} .. py:method:: builder_names() Return a list of builder names in builder format which is in the form: `/`. .. py:method:: get_random_builder_names(num_items=1) Return a list of random builder names from report file. :param num_items: Number of items to retrieve :type num_items: int, optional .. py:method:: breakdown_by_test_names() Returns a dictionary with number of test runs, pass test and fail test by testname .. py:method:: fetch_records_by_ids(testids) Fetch a test record given a list of test identifier. :param testids: A list of test IDs to search in report file and retrieve JSON record for each test. :type testids: list .. py:method:: get_buildspec_by_test(name) Retrieve buildspec file by test name. This method will return buildspec file for a given test name. .. py:function:: list_report() This method will list all report files. This method will implement ``buildtest report list`` command. .. py:function:: clear_report() This method will clear all report files. We read file BUILDTEST_REPORTS and remove all report files and also remove content of BUILDTEST_REPORTS. This method will implement ``buildtest report clear`` command. .. py:function:: report_cmd(args, configuration, report_file=None) Entry point for ``buildtest report`` command .. py:function:: report_summary(report, configuration, detailed=None, color=None) This method will print summary for report file which can be retrieved via ``buildtest report summary`` command :param report: An instance of Report class :type report: buildtest.cli.report.Report :param configuration: An instance of SiteConfiguration class :type configuration: buildtest.config.SiteConfiguration :param detailed: An instance of bool, flag for printing a detailed report. :type detailed: bool :param color: An instance of str, color that the report should be printed in :type color: str .. py:function:: print_report_summary_output(report, table, pass_results, fail_results, color=None, detailed=None) Print output of ``buildtest report summary``. :param report: An instance of Report class :type report: buildtest.cli.report.Report :param table: An instance of Rich Table class :type table: rich.table.Table :param pass_results: An instance of Report class with filtered output by ``state=PASS`` :type pass_results: buildtest.cli.report.Report :param fail_results: An instance of Report class with filtered output by ``state=FAIL`` :type fail_results: buildtest.cli.report.Report :param color: An instance of a string class that tells print_report_summary what color the output should be printed in. :type color: str :param detailed: Print detailed output of the report summary if ``buildtest report summary --detailed`` is specified :type detailed: bool, optional