resources/libraries/python/model/export_json.py

   1 # Copyright (c) 2022 Cisco and/or its affiliates.
   2 # Licensed under the Apache License, Version 2.0 (the "License");
   3 # you may not use this file except in compliance with the License.
   4 # You may obtain a copy of the License at:
   5 #
   6 #     http://www.apache.org/licenses/LICENSE-2.0
   7 #
   8 # Unless required by applicable law or agreed to in writing, software
   9 # distributed under the License is distributed on an "AS IS" BASIS,
  10 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  11 # See the License for the specific language governing permissions and
  12 # limitations under the License.
  13
  14 """Module tracking json in-memory data and saving it to files.
  15
  16 The current implementation tracks data for raw output,
  17 and info output is created from raw output on disk (see raw2info module).
  18 Raw file contains all log items but no derived quantities,
  19 info file contains only important log items but also derived quantities.
  20 The overlap between two files is big.
  21
  22 Each test case, suite setup (hierarchical) and teardown has its own file pair.
  23
  24 Validation is performed for output files with available JSON schema.
  25 Validation is performed in data deserialized from disk,
  26 as serialization might have introduced subtle errors.
  27 """
  28
  29 import datetime
  30 import os.path
  31
  32 from robot.api import logger
  33 from robot.libraries.BuiltIn import BuiltIn
  34
  35 from resources.libraries.python.Constants import Constants
  36 from resources.libraries.python.model.ExportResult import (
  37     export_dut_type_and_version
  38 )
  39 from resources.libraries.python.model.mem2raw import write_raw_output
  40 from resources.libraries.python.model.raw2info import convert_content_to_info
  41 from resources.libraries.python.model.validate import (get_validators, validate)
  42
  43
  44 class export_json():
  45     """Class handling the json data setting and export."""
  46
  47     ROBOT_LIBRARY_SCOPE = u"GLOBAL"
  48
  49     def __init__(self):
  50         """Declare required fields, cache output dir.
  51
  52         Also memorize schema validator instances.
  53         """
  54         self.output_dir = BuiltIn().get_variable_value(u"\\${OUTPUT_DIR}", ".")
  55         self.raw_file_path = None
  56         self.raw_data = None
  57         self.validators = get_validators()
  58
  59     def export_pending_data(self):
  60         """Write the accumulated data to disk.
  61
  62         Create missing directories.
  63         Reset both file path and data to avoid writing multiple times.
  64
  65         Functions which finalize content for given file are calling this,
  66         so make sure each test and non-empty suite setup or teardown
  67         is calling this as their last keyword.
  68
  69         If no file path is set, do not write anything,
  70         as that is the failsafe behavior when caller from unexpected place.
  71         Aso do not write anything when EXPORT_JSON constant is false.
  72
  73         Regardless of whether data was written, it is cleared.
  74         """
  75         if not Constants.EXPORT_JSON or not self.raw_file_path:
  76             self.raw_data = None
  77             self.raw_file_path = None
  78             return
  79         write_raw_output(self.raw_file_path, self.raw_data)
  80         # Raw data is going to be cleared (as a sign that raw export succeeded),
  81         # so this is the last chance to detect if it was for a test case.
  82         is_testcase = u"result" in self.raw_data
  83         self.raw_data = None
  84         # Validation for raw output goes here when ready.
  85         info_file_path = convert_content_to_info(self.raw_file_path)
  86         self.raw_file_path = None
  87         # If "result" is missing from info content,
  88         # it could be a bug in conversion from raw test case content,
  89         # so instead of that we use the flag detected earlier.
  90         if is_testcase:
  91             validate(info_file_path, self.validators[u"tc_info"])
  92
  93     def warn_on_bad_export(self):
  94         """If bad state is detected, log a warning and clean up state."""
  95         if self.raw_file_path is not None or self.raw_data is not None:
  96             logger.warn(f"Previous export not clean, path {self.raw_file_path}")
  97             self.raw_data = None
  98             self.raw_file_path = None
  99
 100     def start_suite_setup_export(self):
 101         """Set new file path, initialize data for the suite setup.
 102
 103         This has to be called explicitly at start of suite setup,
 104         otherwise Robot likes to postpone initialization
 105         until first call by a data-adding keyword.
 106
 107         File path is set based on suite.
 108         """
 109         self.warn_on_bad_export()
 110         start_time = datetime.datetime.utcnow().strftime(
 111             u"%Y-%m-%dT%H:%M:%S.%fZ"
 112         )
 113         suite_name = BuiltIn().get_variable_value(u"\\${SUITE_NAME}")
 114         suite_id = suite_name.lower().replace(u" ", u"_")
 115         suite_path_part = os.path.join(*suite_id.split(u"."))
 116         output_dir = self.output_dir
 117         self.raw_file_path = os.path.join(
 118             output_dir, suite_path_part, u"setup.raw.json"
 119         )
 120         self.raw_data = dict()
 121         self.raw_data[u"version"] = Constants.MODEL_VERSION
 122         self.raw_data[u"start_time"] = start_time
 123         self.raw_data[u"suite_name"] = suite_name
 124         self.raw_data[u"suite_documentation"] = BuiltIn().get_variable_value(
 125             u"\\${SUITE_DOCUMENTATION}"
 126         )
 127         # "end_time" and "duration" is added on flush.
 128         self.raw_data[u"hosts"] = set()
 129         self.raw_data[u"log"] = list()
 130
 131     def start_test_export(self):
 132         """Set new file path, initialize data to minimal tree for the test case.
 133
 134         It is assumed Robot variables DUT_TYPE and DUT_VERSION
 135         are already set (in suite setup) to correct values.
 136
 137         This function has to be called explicitly at the start of test setup,
 138         otherwise Robot likes to postpone initialization
 139         until first call by a data-adding keyword.
 140
 141         File path is set based on suite and test.
 142         """
 143         self.warn_on_bad_export()
 144         start_time = datetime.datetime.utcnow().strftime(
 145             u"%Y-%m-%dT%H:%M:%S.%fZ"
 146         )
 147         suite_name = BuiltIn().get_variable_value(u"\\${SUITE_NAME}")
 148         suite_id = suite_name.lower().replace(u" ", u"_")
 149         suite_path_part = os.path.join(*suite_id.split(u"."))
 150         test_name = BuiltIn().get_variable_value(u"\\${TEST_NAME}")
 151         self.raw_file_path = os.path.join(
 152             self.output_dir, suite_path_part,
 153             test_name.lower().replace(u" ", u"_") + u".raw.json"
 154         )
 155         self.raw_data = dict()
 156         self.raw_data[u"version"] = Constants.MODEL_VERSION
 157         self.raw_data[u"start_time"] = start_time
 158         self.raw_data[u"suite_name"] = suite_name
 159         self.raw_data[u"test_name"] = test_name
 160         test_doc = BuiltIn().get_variable_value(u"\\${TEST_DOCUMENTATION}", u"")
 161         self.raw_data[u"test_documentation"] = test_doc
 162         # "test_type" is added when converting to info.
 163         # "tags" is detected and added on flush.
 164         # "end_time" and "duration" is added on flush.
 165         # Robot status and message are added on flush.
 166         self.raw_data[u"result"] = dict(type=u"unknown")
 167         self.raw_data[u"hosts"] = set()
 168         self.raw_data[u"log"] = list()
 169         export_dut_type_and_version()
 170
 171     def start_suite_teardown_export(self):
 172         """Set new file path, initialize data for the suite teardown.
 173
 174         This has to be called explicitly at start of suite teardown,
 175         otherwise Robot likes to postpone initialization
 176         until first call by a data-adding keyword.
 177
 178         File path is set based on suite.
 179         """
 180         self.warn_on_bad_export()
 181         start_time = datetime.datetime.utcnow().strftime(
 182             u"%Y-%m-%dT%H:%M:%S.%fZ"
 183         )
 184         suite_name = BuiltIn().get_variable_value(u"\\${SUITE_NAME}")
 185         suite_id = suite_name.lower().replace(u" ", u"_")
 186         suite_path_part = os.path.join(*suite_id.split(u"."))
 187         self.raw_file_path = os.path.join(
 188             self.output_dir, suite_path_part, u"teardown.raw.json"
 189         )
 190         self.raw_data = dict()
 191         self.raw_data[u"version"] = Constants.MODEL_VERSION
 192         self.raw_data[u"start_time"] = start_time
 193         self.raw_data[u"suite_name"] = suite_name
 194         # "end_time" and "duration" is added on flush.
 195         self.raw_data[u"hosts"] = set()
 196         self.raw_data[u"log"] = list()
 197
 198     def finalize_suite_setup_export(self):
 199         """Add the missing fields to data. Do not write yet.
 200
 201         Should be run at the end of suite setup.
 202         The write is done at next start (or at the end of global teardown).
 203         """
 204         end_time = datetime.datetime.utcnow().strftime(u"%Y-%m-%dT%H:%M:%S.%fZ")
 205         self.raw_data[u"end_time"] = end_time
 206         self.export_pending_data()
 207
 208     def finalize_test_export(self):
 209         """Add the missing fields to data. Do not write yet.
 210
 211         Should be at the end of test teardown, as the implementation
 212         reads various Robot variables, some of them only available at teardown.
 213
 214         The write is done at next start (or at the end of global teardown).
 215         """
 216         end_time = datetime.datetime.utcnow().strftime(u"%Y-%m-%dT%H:%M:%S.%fZ")
 217         message = BuiltIn().get_variable_value(u"\\${TEST_MESSAGE}")
 218         status = BuiltIn().get_variable_value(u"\\${TEST_STATUS}")
 219         test_tags = BuiltIn().get_variable_value(u"\\${TEST_TAGS}")
 220         self.raw_data[u"end_time"] = end_time
 221         self.raw_data[u"tags"] = list(test_tags)
 222         self.raw_data[u"status"] = status
 223         self.raw_data[u"message"] = message
 224         self.export_pending_data()
 225
 226     def finalize_suite_teardown_export(self):
 227         """Add the missing fields to data. Do not write yet.
 228
 229         Should be run at the end of suite teardown
 230         (but before the explicit write in the global suite teardown).
 231         The write is done at next start (or explicitly for global teardown).
 232         """
 233         end_time = datetime.datetime.utcnow().strftime(u"%Y-%m-%dT%H:%M:%S.%fZ")
 234         self.raw_data[u"end_time"] = end_time
 235         self.export_pending_data()