From 4c821a92b27c23cbf3961321165ab35a46c862d8 Mon Sep 17 00:00:00 2001 From: Daniel Date: Thu, 7 Dec 2023 17:07:12 +0100 Subject: [PATCH 1/4] update docs in readme, add CLI section --- README.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 79 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3418450..cbde1f8 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,93 @@ # pytest-abra -...description... + +Pytest-Abra is an installable python package design to test instances created with [abra](https://docs.coopcloud.tech/abra/). After installation, you will have two things: + +- `abratest` CLI command + +- `pytest-abra` Pytest plugin + +## CLI (abratest) + +The easiest way to call abratest is via the helper script in `main.py`. You can also directly call abratest via terminal, but you will have to make sure that the requirements below are met. To do that, you can call `abratest` with: + +```bash +abratest [arguments] +``` + +The cli command abratest has 3 **required arguments**: + +- `--env_paths`: list of the .env files used in the test +- `--recipes_dir`: directory of all available abra recipes +- `--output_dir`: target directory for all test results + +It is also absolutely necessary, that python can import from `recipes_dir`. This can be achieved by adding the path to the `PYTHONPATH` environment variable **before** the python interpreter is started, i.e. before `abratest` is called. + +### env_paths [string] + +The variable env_paths consists of one or more paths pointing at .env files. The paths are separated with ";". These .env files are actually configuration files for `abra` recipes, but `pytest-abra` uses the same files for test configuration. + +To run `abratest` with these `.env` configuration files + +``` +/path/to/config_1.env +/path/to/config_2.env +/path/to/config_3.env +``` + +we simply call + +``` +abratest --env_paths /path/to/config_1.env;/path/to/config_2.env;/path/to/config_3.env +``` + +Under the hood, each `.env` file in `--env_paths` will create one instance of a `Runner` subclass. Let's say we have `wordpress_configuration.env` containing `TYPE=wordpress`. This will create an instance of `RunnerWordpress`. This class has to be imported from `recipes_dir`. + +### recipes_dir [string] + +The required argument `--recipes_dir` has to point to the directory, where all the abra recipes are stored. We cann call `abratest` with + +``` +abratest --recipes_dir /path/to/abra/recipes +``` + +``` +DIR recipes_dir [contains abra recipes] +│ +├── DIR authentik [authentik recipe] +│ ├── [files from authentik recipe] +│ └── DIR tests_authentik [pytest tests for authentik] +│ ├── FILE runner_authentik.py # containing RunnerAuthentik class +│ └── [pytest_files] +│ +└── DIR wordpress [wordpress recipe] + ├── [files from wordpress recipe] + └── DIR tests_wordpress [pytest tests for wordpress] + ├── FILE runner_wordpress.py # containing RunnerWordpress class + └── [pytest_files] +``` + +The class `RunnerWordpress` will be imported via + +```python +from wordpress.tests_wordpress.runner_wordpress import RunnerWordpress +``` + +which requires that python can find and import from the module `wordpress`. One way to achive this is by adding recipes_dir to the environment variable PYTHONPATH before +i.e. abratest cannot do this itself +-> workaround? +todo # Usage To use pytest-abra, follow these steps: -## 1. GIT Clone +## 1. GIT clone [with & without Docker] To clone with submodules, use these git commands: ```bash git clone --recurse-submodules +// optional: git submodule update --init // add submodule after normal cloning git submodule update --remote // update submodules ``` -- 2.47.2 From 9121128935712c114c69a2a615b38aa622ba6c61 Mon Sep 17 00:00:00 2001 From: Daniel Date: Thu, 7 Dec 2023 17:15:12 +0100 Subject: [PATCH 2/4] remove PYTHONPATH stuff, add sys.path.append to create_runner_dict instead --- main.py | 6 ------ pytest_abra/coordinator.py | 7 +++++++ 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/main.py b/main.py index 9de2d4f..00a451c 100644 --- a/main.py +++ b/main.py @@ -31,12 +31,6 @@ ENV_PATHS = ";".join([x.as_posix() for x in ENV_FILES]) RECIPES_DIR = Path("../recipes").resolve() OUTPUT_DIR = Path("./test-output").resolve() -# -------------------------------- pythonpath -------------------------------- # - -# add recipes dir to pythonpath, so that python imports from there are possible -# the custom classes of Runner will be imported from there -os.environ["PYTHONPATH"] = RECIPES_DIR.as_posix() - # ------------------------------------ run ----------------------------------- # subprocess.run( diff --git a/pytest_abra/coordinator.py b/pytest_abra/coordinator.py index fb0f422..74c4ea2 100644 --- a/pytest_abra/coordinator.py +++ b/pytest_abra/coordinator.py @@ -1,5 +1,6 @@ import importlib import re +import sys from pathlib import Path from loguru import logger @@ -90,11 +91,17 @@ class Coordinator: "wordpress": RunnerWordpress, "nextcloud": RunnerNextcloud, } + + The Runner classes are automatically imported with importlib. The imports are successful + because recipes_dir is added to sys.path. """ RUNNER_DICT: dict[str, type["Runner"]] = dict() runner_discovery_pattern = re.compile("Runner.+") + # make it possible to import modules from recipes_dir + sys.path.append(recipes_dir.as_posix()) + for module_path in recipes_dir.rglob("*/runner*.py"): rel_path = module_path.relative_to(recipes_dir).as_posix().replace("/", ".").replace(".py", "") module = importlib.import_module(rel_path) -- 2.47.2 From 607606f51e5e2803a906a0d01b591e4fe8bdf29d Mon Sep 17 00:00:00 2001 From: Daniel Date: Thu, 7 Dec 2023 17:16:15 +0100 Subject: [PATCH 3/4] remove PYTHONPATH stuff --- README.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/README.md b/README.md index cbde1f8..5927d17 100644 --- a/README.md +++ b/README.md @@ -20,8 +20,6 @@ The cli command abratest has 3 **required arguments**: - `--recipes_dir`: directory of all available abra recipes - `--output_dir`: target directory for all test results -It is also absolutely necessary, that python can import from `recipes_dir`. This can be achieved by adding the path to the `PYTHONPATH` environment variable **before** the python interpreter is started, i.e. before `abratest` is called. - ### env_paths [string] The variable env_paths consists of one or more paths pointing at .env files. The paths are separated with ";". These .env files are actually configuration files for `abra` recipes, but `pytest-abra` uses the same files for test configuration. @@ -72,11 +70,6 @@ The class `RunnerWordpress` will be imported via from wordpress.tests_wordpress.runner_wordpress import RunnerWordpress ``` -which requires that python can find and import from the module `wordpress`. One way to achive this is by adding recipes_dir to the environment variable PYTHONPATH before -i.e. abratest cannot do this itself --> workaround? -todo - # Usage To use pytest-abra, follow these steps: -- 2.47.2 From c88d743453ea5b985e2f0ac4694bca515edc828f Mon Sep 17 00:00:00 2001 From: Daniel Date: Thu, 7 Dec 2023 17:18:52 +0100 Subject: [PATCH 4/4] small changes --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5927d17..54fd681 100644 --- a/README.md +++ b/README.md @@ -42,12 +42,14 @@ Under the hood, each `.env` file in `--env_paths` will create one instance of a ### recipes_dir [string] -The required argument `--recipes_dir` has to point to the directory, where all the abra recipes are stored. We cann call `abratest` with +The required argument `--recipes_dir` has to point to the directory, where all the abra recipes are stored. We can call `abratest` with ``` abratest --recipes_dir /path/to/abra/recipes ``` +The expected dir structure inside of `recipes_dir` is as follows: + ``` DIR recipes_dir [contains abra recipes] │ @@ -64,7 +66,7 @@ DIR recipes_dir [contains abra recipes] └── [pytest_files] ``` -The class `RunnerWordpress` will be imported via +The class `RunnerWordpress` will be automatically imported by `importlib`, which is equivalent to ```python from wordpress.tests_wordpress.runner_wordpress import RunnerWordpress -- 2.47.2