docs/model/current/top.rst

   1 ..
   2    Copyright (c) 2021 Cisco and/or its affiliates.
   3    Licensed under the Apache License, Version 2.0 (the "License");
   4    you may not use this file except in compliance with the License.
   5    You may obtain a copy of the License at:
   6 ..
   7        http://www.apache.org/licenses/LICENSE-2.0
   8 ..
   9    Unless required by applicable law or agreed to in writing, software
  10    distributed under the License is distributed on an "AS IS" BASIS,
  11    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12    See the License for the specific language governing permissions and
  13    limitations under the License.
  14
  15
  16 CSIT model
  17 ^^^^^^^^^^
  18
  19 This document describes what is currently implemented in CSIT,
  20 especially the export side (UTI), not import side (PAL).
  21
  22 Version
  23 ~~~~~~~
  24
  25 This document is valid for CSIT model version 1.0.0.
  26
  27 It is recommended to use semantic versioning: https://semver.org/
  28 That means, if the new model misses a field present in the old model,
  29 bump the major version. If the new model adds a field
  30 not present in the old model, bump the minor version.
  31 Any other edit in the implmenetation (or documentation) bumps the patch version.
  32 If you change value type or formatting,
  33 consider whether the parser (PAL) understands the new value correctly.
  34 Renaming a field is the same as adding a new one and removing the old one.
  35 Parser (PAL) has to know exact major version and minimal minor version,
  36 and unless bugs, it can ignore patch version and bumped minor version.
  37
  38 UTI
  39 ~~~
  40
  41 UTI stands for Unified Test Interface.
  42 It mainly focuses on exporting information gathered during test run
  43 into JSON output files.
  44
  45 Output Structure
  46 -----------------
  47
  48 UTI outputs come in filesystem tree structure (single tree), where directories
  49 correspond to suite levels and files correspond to suite setup, suite teardown
  50 or any test case at this level of suite.
  51 The directory name comes from SUITE_NAME Robot variable (the last part
  52 as the previous parts are higher level suites), converted to lowercase.
  53 If the suite name contains spaces (Robot converts underscores to spaces),
  54 they are replaced with underscores.
  55
  56 The filesystem tree is rooted under tests/ (as suites in git are there),
  57 and for each component (test case, suite setup, suite teardown)
  58 two files are generated.
  59 The "raw" variant is suitable for debugging (can contain lower level logging),
  60 while the "info" variant is suitable for processing by PAL
  61 (can contain derivative values so PAL does not need to compute them
  62 on every download).
  63 Their structure and content is mostly identical, model definition mentions
  64 if a particular subschema is not identical in the two variants.
  65 It is possible to convert from raw to info, but not the other way.
  66
  67 Although we expect only ASCII text in the exported files,
  68 we manipulate files using UTF-8 encoding,
  69 so if Robot Framework uses a non-ascii character, it will be handled.
  70
  71 JSON schemas
  72 ------------
  73
  74 CSIT model is formally defined as a collection of JSON schema documents,
  75 one for each output file type.
  76
  77 The current version specifies only one output file type:
  78 Info output for test case.
  79
  80 The authoritative JSON schema documents are in JSON format.
  81 Git repository also contains YAML formatted document and conversion utility,
  82 which simplifies maintaining of the JSON document
  83 (no need to track brackets and commas), but are not authoritative.