New version of cetk-cli's public documentation, 2.2.1.0.dev14+g6ff26a7

Author: GitLab CI

VERSION

@@ -1 +1 @@
-2.3.1.0
+2.2.1.0.dev14+g6ff26a7

docs/cel/index.md

@@ -0,0 +1,32 @@
+# comlet Embedded Library (cEL)
+
+A cEL is a pure software library that extends the capability of the [control environment](../control_env/index.md)
+and therefore the possibilities for test automation[^1].
+This can be done by providing interfaces to additional tools[^2] or implementing additional protocol layer to communicate
+with the SUT[^3].
+
+Each cEL brings along a well-defined, low-level keyword library for Robot Framework on top of which new (user) keyword libraries
+may be implemented.
+
+??? example "Examples for already available cEL"
+    - OCR Library: Extends test cases with the power of text recognition (by [Tesseract](https://github.com/tesseract-ocr/tesseract){target="_blank"})
+    - MAVLink Library: Extends test cases to communicate with airborne drones by [MAVLink](https://mavlink.io/){target="_blank"} protocol
+    - SCPI Library: Extends test cases to be able to talk to various [SCPI protocol](https://en.wikipedia.org/wiki/Standard_Commands_for_Programmable_Instruments){target="_blank"}
+      enabled hardware measurement devices
+    - ADB Library: Extends test cases to be able to talk to mobile devices by [ADB](https://developer.android.com/tools/adb?hl=en){target="_blank"}
+    - Qt Squish Library: Extends test cases to be able to utilize [Qt's Squish GUI testing tool](https://www.qt.io/quality-assurance/squish)
+    - MQTT Library: Extends test cases to be able to talk to IIoT devices via MQTT
+    - NETIO M2M JSON API Library: Extends test cases to be able to talk to [NETIO devices](https://www.netio-products.com/en)
+      via their [M2M JSON API](https://www.netio-products.com/en/software/open-api){target="_blank"}
+    - Cleware USB Multiplexer Library: Extends test cases to be able to control USB Multiplexer [by Cleware](https://www.cleware-shop.de/epages/63698188.sf/en_GB/?ViewObjectPath=%2FShops%2F63698188){target="_blank"}
+    - Public Transport Protocol Library: Extends test cases to be able to communicate with IBIS-IP[^4] and ITxPT devices
+    - XLM Schema Validation Library: Extends test cases to be able to validate XML strings against an XML schema
+
+??? info "Do you need a library implemented?"
+    We are happy to help you out if you have the need for a particular library implementation.
+    Feel free to contact [our sales](mailto:[email protected]?subject=cEL Inquiry) for further details.
+
+[^1]: Besides the already available Robot Framework ecosystem
+[^2]: Those tools need to run in the control environment as well
+[^3]: Either via hardware interface already available (only on premise) and/or [cESD](../cesd/index.md)
+[^4]: [VDV 301 Standard](https://www.vdv.de/ip-kom-oev.aspx){target="_blank"}

docs/cesd/index.md

@@ -0,0 +1,31 @@
+# comlet Embedded Simulation Device (cESD)
+
+A cESD is an embedded device, provided by comlet, that extends the control environment's capabilities to connect to and
+communicate with the SUT interfaces. It is used whenever a pure software library like a [cEL](../cel/index.md) is not enough
+(e.g., because the physical layer is missing or a certain timing is needed).
+
+## On Premise
+
+With the [on premise control environment](../control_env/index.md), the cESD is mainly used to connect to the SUT
+by a low level hardware interface that is not available through the on premise host (or any kind of third-party adapter).
+
+Communication between the control environment and SUT is established by REST API that is unique and specialized
+for the respective hardware interface.
+
+??? example "Examples for already available cESD"
+    - Relay: This cESD offers up to three relais to be opened and closed
+    - DAC: This cESD offers up to two 8 channel 12 Bit digital analog converter
+
+## Cloud
+
+For the [cloud service control environment](../control_env/cloud.md), the cESD is the bridge between the public network
+to the cloud service and the internal company network where the SUT is usually part of. Therefore, a cESD is also the only
+connection to the SUT's interfaces.
+
+The communication protocol in this context is MQTTS.
+
+---
+
+??? info "Do you need an interface engineered?"
+    We are happy to help you out if you have the need for a particular interface implementation.
+    Feel free to contact [our sales](mailto:[email protected]?subject=cESD Inquiry) for further details.

docs/cli/config.md

@@ -0,0 +1,12 @@
+Configuration can be given by three different entities:
+
+* TOML file within [`Source Home`](../home_folder/source_home.md#configuration-file-for-cetk-cli)
+* Environment variables
+* [CLI options](global_options.md)
+
+The TOML file has the lowest prio and the CLI options the highest. The TOML file is good to define fallback defaults
+and is part of the [`init` command](init.md). Environment variables are good to control CI/CD processes and are documented
+together with their respective [global option](global_options.md).
+
+!!! note
+    [`Source Home`](../home_folder/source_home.md) can only be configured by CLI option.

docs/cli/default_options.md

@@ -0,0 +1,118 @@
+# Default Options
+Each executable gets a carefully curated set of default options that is the result of many hours and projects of enterprise
+test automation.
+
+## robot
+
+### Tags
+#### `not_ready`
+Tag to be used for test cases that shall be skipped, i.e., their result is ignored.
+
+#### `no_logging`
+Tag for keywords that shall not log anything. This is useful if a keyword handles sensitive data like secrets.
+
+#### `dont_run`
+Tag for test cases that shall not be run at all.
+
+### Test Case Randomization
+Tests within test suites are randomized regarding their execution order. This is a proven way to identify unwanted side
+effects between test cases.
+
+### Run Empty Test Suites
+If test cases are selected based on `--include` or `--exclude` this will make sure, test suites do not fail if no test case
+has been selected.
+
+### Reports and Logs
+#### `cetk_xunit.xml`
+Report in xUnit format that can be processed by most of the common CI/CD processors.
+
+#### `cetk_log.html`
+Detailed log for every keyword called from every test case in every test suite in HTML format.
+
+#### `cetk_report.html`
+Overview/Summary report in HTML format that can be used as a dashboard.
+
+#### `cetk_output.xml`
+XML output with all raw information/details in a machine-processable way.
+
+### Global Variables
+#### `RESOURCES`
+Global variable `${RESOURCES}` that can be used to reference the `resources` sub-folder from [`Source Home`](../home_folder/source_home.md).
+
+### Default Output Directory
+[`Output Home`](../home_folder/output_home.md) is set as default output directory where all the [reports and logs](#reports-and-logs) are saved.
+
+### Additions to `PYTHONPATH`
+#### `<Source Home>/libraries`
+Adds the `libraries` sub-folder from [`Source Home`](../home_folder/source_home.md) as an additional python path.
+
+### Log level
+Configures the log level to enable `TRACE` logs but visually show only `INFO` level as default in HTML log.
+This makes sure no detail is missed if a test case fails, but the HTML is not overloaded with unnecessary details by default.
+
+## rebot
+
+### Tags
+#### `no_logging`
+Tag for keywords that shall not log anything. This is useful if a keyword handles sensitive data like secrets.
+
+#### `dont_run`
+Tag for test cases that shall not be run at all.
+
+### Process Empty Test Suites
+If test suites have no test cases, this will make sure `rebot` will not fail while processing.
+
+### Reports and Logs
+#### `cetk_xunit_merged.xml`
+Merged xUnit log.
+
+#### `cetk_log_merged.html`
+Merged HTML log.
+
+#### `cetk_report_merged.html`
+Merged HTML report.
+
+#### `cetk_output_merged.xml`
+Merged XML report (raw data).
+
+### Default Output Directory
+[`Output Home`](../home_folder/output_home.md) is set as default output directory where all the merged [reports and logs](#reports-and-logs) are saved.
+
+### Additions to `PYTHONPATH`
+#### `<Source Home>/libraries`
+Adds the `libraries` sub-folder from [`Source Home`](../home_folder/source_home.md) as an additional python path.
+
+### Log level
+Configures the log level to enable `TRACE` logs but visually show only `INFO` level as default in HTML log.
+This makes sure no detail is missed if a test case fails, but the HTML is not overloaded with unnecessary details by default.
+
+## libdoc
+
+### Additions to `PYTHONPATH`
+#### `<Source Home>/libraries`
+Adds the `libraries` sub-folder from [`Source Home`](../home_folder/source_home.md) as an additional python path.
+
+### Default Output Documentation File
+Defines `<Output Home>/cetk_libdoc.html` as default output file and HTML format.
+
+## testdoc
+
+### Tags
+#### `dont_run`
+Tag for test cases that shall not be run at all.
+
+### Default Output Documentation File
+Defines `<Output Home>/cetk_testdoc.html` as default output file and HTML format.
+
+## robocop
+
+### Default config
+Default config for linting that fits perfectly with the beautifier `robotidy`.
+
+### Default Output Report
+Defines `<Output Home>/cetk_lint_report.html` as default output report.
+
+## robotidy
+
+### Default config
+Default config for beautifying that fits perfectly with the linter `robocop`.

docs/cli/global_options.md

@@ -0,0 +1,176 @@
+# Global Options
+Global options can be used before and for every sub-command but may not be processed by every [control environment](../control_env/index.md).
+
+??? example
+    ````shell
+    cetk [global option] [sub-command] ...
+    ````
+
+## Options
+
+### `--help` / `-h`
+Show help/usage details and exit.
+
+- Default: None
+- Supported control environment(s): All
+- Environment variable(s): None
+
+### `--version`
+Show `cetk-cli`'s version and exit.
+
+- Default: None
+- Supported control environment(s): All
+- Environment variable(s): None
+
+---
+
+### `--project-name` (str)
+Set a project name used for Docker compose environment and its network.
+
+- Default: `cetk`
+- Supported control environment(s): Native, Docker
+- Environment variable(s): `CETK_PROJECT_NAME`
+
+### `--source-home` / `-s` (path)
+Set the common [`Source Home`](../home_folder/source_home.md) path for all [supported executables](../control_env/index.md#supported-executables).
+
+- Default: Current working directory
+- Supported control environment(s): All
+- Environment variable(s): None
+
+??? note
+    The [control environment](../control_env/index.md#environment-variables) will set `CETK_SOURCE_HOME` during run-time,
+    even though [`Source Home`](../home_folder/source_home.md) cannot be [configured](config.md) by environment variable (or TOML file).
+
+### `--output-home` / `-o` (path)
+Set the common [`Output Home`](../home_folder/output_home.md) path for all [supported executables](../control_env/index.md#supported-executables).
+
+- Default: `<Source Home>/artifacts`
+- Supported control environment(s): All
+- Environment variable(s): `CETK_OUTPUT_HOME`
+
+??? note
+    The [control environment](../control_env/index.md#environment-variables) will set `CETK_OUPUT_HOME` during run-time,
+    regardless from which [configuration entity](config.md) `OUTPUT HOME` has been configured.
+
+### `--environment` (choice)
+Define the control environment to be used.
+
+- Choices: `native`, `docker`, `cloud`
+- Default: `native`
+- Supported control environment(s): All
+- Environment variable(s): `CETK_ENVIRONMENT`
+
+??? note
+    The [control environment](../control_env/index.md#environment-variables) will set `CETK_ENVIRONMENT` during run-time,
+    regardless from which [configuration entity](config.md) `environment` has been configured.
+
+---
+
+### `--verbose` / `-v`
+Show log messages in the terminal (stderr).
+
+- Default: disabled
+- Supported control environment(s): All
+- Environment variable(s): `CETK_VERBOSE`, `CETK_ENABLE_VERBOSE`[^1]
+
+### `--enable-file-logging`
+Enable logging into a file (for default file location, see `--log-file`)
+
+- Default: enabled (by TOML configuration file)
+- Supported control environment(s): All
+- Environment variable(s): `CETK_FILE_LOGGING`, `CETK_ENABLE_FILE_LOGGING`[^1]
+
+### `--log-file` (file path)
+Specify different path/file name for the log file (if enabled).
+
+- Default: `<Output Home>/cetk.log`
+- Supported control environment(s): All
+- Environment variable(s): `CETK_LOG_FILE`
+
+---
+
+### `--compose-file` (file path)
+Docker compose file to be used for Docker compose environment.
+Option can be used several times.
+
+- Default: None
+- Supported control environment(s): native, docker
+- Environment variable(s): `CETK_COMPOSE_FILES`
+
+### `--compose-dotenv-file` (file path)
+Dotenv (`.env`) file passed to Docker compose environment.
+
+- Default: None
+- Supported control environment(s): native, docker
+- Environment variable(s): `CETK_COMPOSE_DOTENV_FILE`
+
+### `--compose-executable-name` (str)
+Name of the executable to be used to control `compose`.
+
+- Default: `docker`
+- Supported control environment(s): native, docker
+- Environment variable(s): `CETK_COMPOSE_EXECUTABLE_NAME`
+
+### `--compose-executable-path` (path)
+Alternative search path for executable that controls `compose`.
+
+- Default: System/User `PATH`
+- Supported control environment(s): native, docker
+- Environment variable(s): `CETK_COMPOSE_EXECUTABLE_PATH`
+
+### `--compose-verbose`
+Enable verbose mode for compose executable
+
+- Default: disabled
+- Supported control environment(s): native, docker
+- Environment variable(s): `CETK_COMPOSE_VERBOSE`, `CETK_COMPOSE_ENABLE_VERBOSE`[^1]
+
+---
+
+### `--docker-image` (str)
+The name/tag of the control environment Docker image.
+
+- Default: None
+- Supported control environment(s): docker
+- Environment variable(s): `CETK_DOCKER_IMAGE`
+
+??? note
+    The [docker control environment](../control_env/docker.md#environment-variables) will set `CETK_DOCKER_IMAGE` during run-time,
+    regardless from which [configuration entity](config.md) `docker image` has been configured.
+
+---
+
+### `--cloud-api-key` (str)
+API key to authorize against cETK cloud service. This key can be
+obtained from the cloud service "developer" portal as a self-service.
+
+- Default: None
+- Supported control environment(s): cloud
+- Environment variable(s): `CETK_CLOUD_API_KEY`
+
+### `--cloud-customer-id` (str)
+Customer ID to access customer-specific cETK cloud service API. This ID is
+given by comlet upon valid/active subscription.
+
+- Default: None
+- Supported control environment(s): cloud
+- Environment variable(s): `CETK_CLOUD_CUSTOMER_ID`
+
+### `--cloud-add-upload-path` (path)
+Additional [`Output Home`](../home_folder/output_home.md) or [`Temp Home`](../home_folder/temp_home.md) path from which files are uploaded to
+cETK cloud service as sources (not filtered and non-recursive). Option can be given multiple times.
+
+- Default: None
+- Supported control environment(s): cloud
+- Environment variable(s): `CETK_CLOUD_ADD_UPLOAD_PATHS`
+
+### `--cloud-force-upload`
+Forces upload of sources to cETK cloud service — even if they exist.
+
+- Default: disabled
+- Supported control environment(s): cloud
+- Environment variable(s): `CETK_CLOUD_FORCE_UPLOAD`, `CETK_CLOUD_ENABLE_FORCE_UPLOAD`[^1]
+
+[^1]: The `ENABLE` environment variable just needs to be defined, its value does not matter to enable the option.
+      Whereas the "normal" variable needs to have a truth-y or false-y value