From e5c4ba724468e711d1f2d9e54ee3a5670f9c8c8c Mon Sep 17 00:00:00 2001 From: Tattoo Date: Tue, 31 Oct 2023 13:32:32 +0200 Subject: [PATCH] README: document utils. Fixes #12 --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index 56628d6..ab3d31d 100644 --- a/README.md +++ b/README.md @@ -160,6 +160,19 @@ $ ``` 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. + +`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 Clone the Oxygen repository to the environment where you want to the run the tool.