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, export_tg_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         export_tg_type_and_version()
 171
 172     def start_suite_teardown_export(self):
 173         """Set new file path, initialize data for the suite teardown.
 174
 175         This has to be called explicitly at start of suite teardown,
 176         otherwise Robot likes to postpone initialization
 177         until first call by a data-adding keyword.
 178
 179         File path is set based on suite.
 180         """
 181         self.warn_on_bad_export()
 182         start_time = datetime.datetime.utcnow().strftime(
 183             u"%Y-%m-%dT%H:%M:%S.%fZ"
 184         )
 185         suite_name = BuiltIn().get_variable_value(u"\\${SUITE_NAME}")
 186         suite_id = suite_name.lower().replace(u" ", u"_")
 187         suite_path_part = os.path.join(*suite_id.split(u"."))
 188         self.raw_file_path = os.path.join(
 189             self.output_dir, suite_path_part, u"teardown.raw.json"
 190         )
 191         self.raw_data = dict()
 192         self.raw_data[u"version"] = Constants.MODEL_VERSION
 193         self.raw_data[u"start_time"] = start_time
 194         self.raw_data[u"suite_name"] = suite_name
 195         # "end_time" and "duration" is added on flush.
 196         self.raw_data[u"hosts"] = set()
 197         self.raw_data[u"log"] = list()
 198
 199     def finalize_suite_setup_export(self):
 200         """Add the missing fields to data. Do not write yet.
 201
 202         Should be run at the end of suite setup.
 203         The write is done at next start (or at the end of global teardown).
 204         """
 205         end_time = datetime.datetime.utcnow().strftime(u"%Y-%m-%dT%H:%M:%S.%fZ")
 206         self.raw_data[u"end_time"] = end_time
 207         self.export_pending_data()
 208
 209     def finalize_test_export(self):
 210         """Add the missing fields to data. Do not write yet.
 211
 212         Should be at the end of test teardown, as the implementation
 213         reads various Robot variables, some of them only available at teardown.
 214
 215         The write is done at next start (or at the end of global teardown).
 216         """
 217         end_time = datetime.datetime.utcnow().strftime(u"%Y-%m-%dT%H:%M:%S.%fZ")
 218         message = BuiltIn().get_variable_value(u"\\${TEST_MESSAGE}")
 219         status = BuiltIn().get_variable_value(u"\\${TEST_STATUS}")
 220         test_tags = BuiltIn().get_variable_value(u"\\${TEST_TAGS}")
 221         self.raw_data[u"end_time"] = end_time
 222         self.raw_data[u"tags"] = list(test_tags)
 223         self.raw_data[u"status"] = status
 224         self.raw_data[u"message"] = message
 225         self.export_pending_data()
 226
 227     def finalize_suite_teardown_export(self):
 228         """Add the missing fields to data. Do not write yet.
 229
 230         Should be run at the end of suite teardown
 231         (but before the explicit write in the global suite teardown).
 232         The write is done at next start (or explicitly for global teardown).
 233         """
 234         end_time = datetime.datetime.utcnow().strftime(u"%Y-%m-%dT%H:%M:%S.%fZ")
 235         self.raw_data[u"end_time"] = end_time
 236         self.export_pending_data()