docs: Updated README, DEVGUIDE, CONTRIBUTION (#23)

Co-authored-by: Simon Meggle <simon.meggle@checkmk.com>

Author: simonmeggle

CONTRIBUTION.md

@@ -1,4 +1,55 @@
-## Oxygen developer guide
+# Oxygen developer guide
+
+WIP - the following section was moved from the README: 
+
+---
+
+## Handlers & Configuration
+
+Handlers are registered in `config.yml` inside the package. Inspect or modify the file via the CLI commands above. A typical entry looks like:
+
+```yaml
+rmkbridge.junit:
+  handler: JUnitHandler
+  keyword: run_junit
+  tags:
+    - rmkbridge-junit
+```
+
+- The dictionary key (`rmkbridge.junit`) must be importable (`import rmkbridge.junit`).
+- `handler` names the class instantiated from that module.
+- `keyword` becomes the Robot Framework keyword (`Run Junit`, `run_junit`, etc.).
+- `tags` are applied to every injected test case.
+- Handlers may define extra settings (for example, the ZAP handler ships `accepted_risk_level`).
+
+### Creating Custom Handlers
+
+1. Extend `rmkbridge.BaseHandler` and implement `parse_results` plus your trigger keyword.
+2. Make your module discoverable (PYTHONPATH or installable package).
+3. Append your configuration with `python -m rmkbridge --add-config path/to/handler_config.yml`.
+4. Conform to the [handler result specification](handler_result_specification.md) when returning parsed suites.
+
+The [developer guide](DEVGUIDE.md) walks through a complete example.
+
+## Developing
+
+Clone the repository and install the development dependencies:
+
+```bash
+pip install -r requirements.txt
+pip install -e .
+```
+
+Robotmk Bridge uses [`invoke`](https://www.pyinvoke.org/) for common tasks:
+
+```bash
+invoke --list
+invoke test
+```
+
+You can also run Robot Framework acceptance suites under `tests/` to validate changes end-to-end.
+---
+
 
 This is a developer guide for Oxygen. We will write a handler for [https://locust.io/](https://locust.io/), which is a performance testing tool.
 

DEVGUIDE.md

@@ -1,223 +1,151 @@
-# Oxygen
+# Robotmk Bridge
 
+<<<<<<< Updated upstream
 Version: 0.1.0  <!-- x-release-please-version -->
+=======
+_**The bridge between automation islands and your monitoring**_
+>>>>>>> Stashed changes
 
-Oxygen is a [Robot Framework](https://robotframework.org/) tool that empowers the user to convert the results of any testing tool or framework to [Robot Framework's reporting](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#screenshots). This consolidates all test reporting together regardless of tools used.
+Robotmk Bridge is a [Robot Framework](https://robotframework.org/) library, listener, and CLI that for external test tools to convert their results into Robot Framework results.
 
-Oxygen has built-in support for three testing frameworks: [JUnit](https://junit.org/junit5/), [Gatling](https://gatling.io/), and [Zed Attack Proxy (ZAP)](https://www.zaproxy.org/).
+It is used in two modes: 
 
-Oxygen is designed to be extensible. Users can create their own *handlers* for other testing framework or tools to transform their reporting into the Robot Framework's `log.html` and `report.html`.
+- In the [Robotmk Bridge Agent Plugin](https://github.com/elabit/robotmk-bridge-plugin) which periodically writes converted results into the [Robotmk](https://robotmk.org) results spool folder.
+- As a **Robot Framework Library** to run external test tools from Robot Framework tests. 
 
-# Table of Contents
-1. [Installation](#installation)
-1. [Keyword documentation](#keyword-documentation)
-1. [Usage](#usage)
-1. [Developing Oxygen](#developing-oxygen)
-1. [License](#license)
-1. [Acknowledgements](#acknowledgments)
+In this way, **any test data** can be imported into [Checkmk](https://checkmk.com) monitoring with the help of Robotmk.
 
-# Installation
 
-To install Oxygen, run the following:
-```
-$ pip install robotframework-oxygen
-```
-
-## Pre-requisites
-
-- Oxygen is supported on Windows, Linux and MacOS
-- [Python 3.10](http://python.org) or above
-- [pip](https://pypi.python.org/pypi/pip) for easy installation
-- [Robot Framework](http://robotframework.org)
-- [additional dependencies](requirements.txt)
-
-To check the Python version on the command line, run:
-```
-$ python --version
-```
-
-# Keyword documentation
-
-[Keyword Documentation](http://eficode.github.io/robotframework-oxygen/)
-
-# Usage
-
-## Example: Robot Framework running other test tools
-
-Main usage scenario for Oxygen is the ability to write acceptance test cases that run your tests in other test tools and integrate the resulting test report as part of Robot Framework's. This means you are able to run all of your testing from Robot Framework and thus having all test reporting consolidated together.
 
-After installing Oxygen, it can be used in the Robot Framework suite to write test cases. For example, to build acceptance tests that run different sets of JUnit tests:
+![](img/architecture.png)
 
-``` RobotFramework
-*** Settings ***
-Library    rmkbridge.RobotmkBridgeLibrary
-
-*** Test cases ***
+## Features
 
-JUnit unit tests should pass
-    [Tags]    testset-1
-    Run JUnit    path/to/mydir/results.xml    java -jar junit.jar --reports-dir=path/to/mydir
-
-JUnit integration tests should pass
-    [Tags]    testset-2
-    Run JUnit    path/to/anotherdir/results.xml    java -jar junit.jar --reports-dir=path/to/anotherdir
-```
+- Unifies third-party test results inside Robot Framework log.html/report.html and the Robotmk Checkmk plug-in.
+- Ships ready-made **handlers**, currently there is support for
+  - [JUnit](https://junit.org/junit5/) 
+  - [Gatling](https://gatling.io/)
+  - [OWASP ZAP](https://www.zaproxy.org/)
+- Provides the dynamic library `rmkbridge.RobotmkBridgeLibrary` plus the listener `rmkbridge.listener` for Robot test suites.
+- Offers a CLI (`python -m rmkbridge`) to transform standalone result files into Robot Framework output.xml artifacts.
+- Lets you implement custom handlers by extending `rmkbridge.BaseHandler`.
 
-Then, run the suite by providing Oxygen as [a listener](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#listener-interface):
+## Installation
 
+```bash
+pip install robotframework-robotmk-bridge
 ```
-$ robot --listener oxygen.listener my_tests.robot
-```
-
-Opening the Robot Framework `log.html` and `report.html`, you should see that test case `JUnit unt tests should pass` has been replaced by Oxygen with test cases matching with what is in the `path/to/mydir/results.xml` JUnit report file. Similarly, test case `JUnit integration tests should pass` has been replaced with results from `path/to/anotherdir/results.xml`; each JUnit test case with its relevant information has a counterpart in the `log.html`. Each JUnit test case is also tagged with the tags from the original Robot Framework test case.
 
-The example above, for the brevity, shows incomplete commands to run JUnit tool from command line. Please refer to [keyword documentation](#keyword-documentation) for more detailed documentation about keyword's arguments, as well as documentation for [Gatling](https://gatling.io/) and [ZAP](https://www.zaproxy.org/) related keywords. And, of course, refer to the particular tool documentation as well.
+## Prerequisites
 
-## Using from command line
+- Windows, Linux, or macOS
+- [Python 3.10+](https://www.python.org/downloads/)
+- [Robot Framework 6.x](https://robotframework.org) (Robot Framework 7+ support is planned)
+- [pip](https://pip.pypa.io/) and any extra [requirements](requirements.txt) your handlers need
 
-In case where you want to run your other testing tools separately, but yet combine results into unified Robot Framework `log.html` and `report.html`, you can use Oxygen's command line interface to convert single result file to single corresponding Robot Framework `output.xml`:
+To verify the installation:
 
-```
-$ python -m oxygen oxygen.junit my_junit_results.xml
+```bash
+python -m rmkbridge --version
 ```
 
-As a convention, the resulting Robot Framework xml file will be named by adding a suffix to the end. In the example above, the resulting Robot Framework xml file would be named `my_junit_results_robot_output.xml`.
 
-**Note** that resulting xml file will also be created at the same location as the original result file. Therefore, when original result files are in another directory:
+## Quickstart
 
-```
-$ python -m oxygen oxygen.gatling path/to/results.log
-```
+### Option 1: Use as a Library to execute Test tools from Robot Framework
+
+This mode consists of two steps:
 
-Then `results_robot_output.xml` will be created under `path/to/`.
+1. Running the tool in Robot Framework
+2. Running the Bridge-Listener
 
-## Extending Oxygen: writing your own handler
+#### Step 1: Running the tool in Robot Framework
 
-### [Read the developer guide on how to write your own handler](DEVGUIDE.md)
+Each supported external test tool comes with a special **trigger keyword** `Run <tool>` to run the tool from inside Robot Framework.
+Depending on the Handler, the keywords support individual arguments. 
 
-You might also want to look at [specification for handler results](handler_result_specification.md)
+```robotframework
+*** Settings ***
+Library    rmkbridge.RobotmkBridgeLibrary
 
-### Configuring your handler to Oxygen
+*** Test Cases ***
+JUnit unit tests should pass
+    Custom Keyword 1
+    Run JUnit    path/to/results.xml    java -jar junit.jar --reports-dir path/to
+    Custom Keyword 2
 
-Oxygen knows about different handlers based on the [`config.yml`](https://github.com/eficode/robotframework-oxygen/blob/master/config.yml) file. This configuration file can be interacted with through Oxygen's command line.
+Gatling regression should stay green
+    Custom Keyword 1
+    Run Gatling    path/to/gatling.log    ${GATLING_HOME}/bin/gatling.sh --simulation MySimulation
+    Custom Keyword 2
 
-The configuration has the following parts:
-```yml
-oxygen.junit:           # Python module. Oxygen will use this key to try to import the handler
-  handler: JUnitHandler # Class that Oxygen will initiate after the handler is imported
-  keyword: run_junit    # Keyword that should be used to run the other test tool
-  tags:                 # List of tags that by default should be added to the test cases converted with this handler
-    - oxygen-junit
-oxygen.zap:
-  handler: ZAProxyHandler
-  keyword: run_zap
-  tags: oxygen-zap
-  accepted_risk_level: 2         # Handlers can have their own command line arguments
-  required_confidence_level: 1   # See https://github.com/eficode/robotframework-oxygen/blob/master/DEVGUIDE.md for more information
+ZAP scan finds no blockers
+    Custom Keyword 1
+    Run Zap    path/to/zap.json    python zap_scan.py
+    Custom Keyword 2
 ```
 
-#### `--add-config`
+#### Step 2: Running the Listener
 
-This argument is used to add new handler configuration to Oxygen:
+Now execute the suite with the Robotmk Bridge listener so the external reports are injected into the output:
 
 ```bash
-$ python -m oxygen --add-config path/to/your_handler_config.yml
+robot --listener rmkbridge.listener tests/my_suite.robot
 ```
 
-This file is read and appended to the Oxygen's `config.yml`. Based on the key, Oxygen will try to import you handler.
-
-### `--reset-config`
+Robotmk Bridge creates Test Results using the following rules: 
 
-This argument is used to return Oxygen's `config.yml` back to the state it was when the tool was installed:
+- **trigger keywords** (which run the tools) become **Test Cases**.
+- Keywords _before_ the trigger keyword are wrapped into a **Test Setup keyword**.
+- Keywords _before_ the trigger keyword are wrapped into a **Test Teardown keyword**.
 
-```bash
-$ python -m oxygen --reset-config
-```
-
-The command **does not** verify the operation from the user, so be careful.
+## Option 2: Command Line Usage to convert existing results
 
-### `--print-config`
+Use the CLI when you need to convert tool reports without running Robot Framework suites:
 
-This argument prints the current configuration of Oxygen:
 ```bash
-$ python -m oxygen --print-config
-Using config file: /path/to/oxygen/src/oxygen/config.yml
-oxygen.gatling:
-  handler: GatlingHandler
-  keyword: run_gatling
-  tags: oxygen-gatling
-oxygen.junit:
-  handler: JUnitHandler
-  keyword: run_junit
-  tags:
-  - oxygen-junit
-oxygen.zap:
-  accepted_risk_level: 2
-  handler: ZAProxyHandler
-  keyword: run_zap
-  required_confidence_level: 1
-  tags: oxygen-zap
-
-$
+python -m rmkbridge rmkbridge.junit --result-file path/to/results.xml
 ```
-Because you can add the configuration to the same handler multiple times, note that only the last entry is in effect.
-
-## `utils` module
-
-In [utils module](https://github.com/eficode/robotframework-oxygen/blob/master/src/oxygen/utils.py), you will find assortment of functionalities that you might want to leverage when writing your own handler.
-
-### `run_command_line()`
 
-Most of the time, handlers want to run the other test tool through command line. For this, `utils` provides `run_command_line()` that wraps Python's [`subprocess`](https://docs.python.org/3/library/subprocess.html) module for more easier to use when writing your handler.
+- The converted file gets created next to the source as `*_robot_output.xml`.
+- Similar to trigger keywords, each handler also exposes its own CLI flags. List them with `python -m rmkbridge rmkbridge.junit --help`.
+- Global switches:
+  - `python -m rmkbridge --print-config`
+  - `python -m rmkbridge --add-config path/to/custom_handler.yml`
+  - `python -m rmkbridge --reset-config`
 
-`run_command_line()` takes following arguments:
-- `cmd`: the command to be executed in a subprocess
-- `check_return_code`: if set to `True`, will raise an exception if the `cmd` fails in the subprocess. **Note** that this fails the keyword and, thus, the execution of the test case is stopped. If you want to enable test case to continue even after `run_command_line()` has failed, you should disable it by setting `False`. It is often a good idea to allow user using your handler's keyword to decide how they want the command line execution to affect the test case
-- `env`: a dictionary of environment variables that should be passed to the subprocess. By default, `run_command_line()` inherits the environment from the current Python process as well as from modifications done by the Robot Framework command line arguments (ie. `--pythonpath`)
 
-# Developing Oxygen
 
-## Setup
+## Keyword Documentation
 
-Clone the Oxygen repository to the environment where you want to the run the tool.
+- [Open the generated keyword reference](docs/index.html)
+- Regenerate locally when you add handlers:
 
-Oxygen requires a set of dependencies to be installed. Dependencies are listed in the `requirements.txt` file:
-```
-$ pip install -r requirements.txt
-```
-
-Also install the package itself as editable: 
-
-```
-$ pip install -e .
-```
+  ```bash
+  python -m robot.libdoc rmkbridge.RobotmkBridgeLibrary docs/RobotmkBridgeLibrary-$(python -c "import rmkbridge; print(rmkbridge.VERSION)").html
+  ```
 
-## Tasks
+## 🤝 Contribute Your Own Handlers!
 
-Oxygen uses task runner tool [`invoke`](http://www.pyinvoke.org/) to run tests, build the project, etc.
+The Robotmk Bridge is an open-source project — and we’d love to see it grow with the help of the community!
+Our goal is to make Robotmk a truly multi-purpose integration layer for all kinds of test results.
 
-Please refer to the available tasks for the project:
-```
-$ invoke --list
-```
-
-and the task file [`tasks.py`](https://github.com/eficode/robotframework-oxygen/blob/master/tasks.py).
+If you’re working with a testing tool that isn’t supported yet, consider developing your own Bridge Handler and sharing it with others.
+Every new handler expands what Robotmk can do and helps bring monitoring and test automation even closer together.
 
-### Tests 
-
-```
-$ invoke test
-```
+Pull requests, discussions, and ideas are always welcome!
 
-(Metadata test in Test explorer will stay red)
+Read more: 
 
+- [How to write your own Handler in Python](./DEVGUIDE.md)
+- [How to contribute ot the project](./CONTRIBUTION.md)
 
 
-# License
+## License & Acknowledgements
 
-Details of project licensing can be found in the [LICENSE](LICENSE) file in the project repository.
 
-# Acknowledgments
+Special thanks to Eficdoe Oy, Finland. RobotmkBridge is based on their project [robotframework-oxygen](https://github.com/eficode/robotframework-oxygen?tab=readme-ov-file#developing-oxygen). 
 
-See [ACKNOWLEDGEMENTS](./ACKNOWLEDGEMENTS.md) for more information.
+See [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md) for the roots of the project and credits.  
+Released under the [MIT License](LICENSE).