diff --git a/pytest-backend/README.md b/pytest-backend/README.md index 1e3f290..0ec3cac 100644 --- a/pytest-backend/README.md +++ b/pytest-backend/README.md @@ -1,8 +1,10 @@ # pytest-exasol-backend Plugin -The `pytest-exasol-backend` plugin is a collection of pytest fixtures commonly used for testing -projects related to Exasol. In particular, it provides unified access to both Exasol On-Prem and -SaaS backends. This eliminates the need to build different sets of tests for different backends. +The pytest plugin `pytest-exasol-backend` provides pytest fixtures for using various Exasol database instances in integration tests. + +In particular, the plugin enables accessing both Exasol On-Prem and SaaS backends in a unified way. + +This enables your integration tests to use either backend variant without modification, incl. iterating the test for each backend variant. ## Features @@ -19,10 +21,32 @@ The pytest-exasol-backend plugin can be installed using pip: pip install pytest-exasol-backend ``` +Alternatively via poetry, recommended as `dev` dependency: + +```shell +poetry add pytest-exasol-backend --group dev +``` + ## Usage in Tests -Below is an example of a test that requires access to the database. Note, that by default -this test will run twice - once for each backend. +### PyExasol Connection + +This test accesses the database via [PyExasol](github.com/exasol/pyexasol) and requires an additional (`dev`) dependency to `pyexasol` to be added to your project. + +Note: If the pytest option `--backend all` is specified, then this test will run **twice** - once for each backend. + +```python +import pyexasol + +def test_simple_sql(backend_aware_database_params): + with pyexasol.connect(**backend_aware_database_params) as conn: + value = conn.execute('SELECT 1 FROM DUAL').fetchval() + assert value == 1 +``` + +The following test accesses a specific table within a database schema, and requires +* Database schema `MY_SCHEMA` and table `MY_TABLE` to exist +* Database table `MY_TABLE` to contain 5 rows ```python import pyexasol @@ -33,8 +57,9 @@ def test_number_of_rows_in_my_table(backend_aware_database_params): assert num_of_rows == 5 ``` -Here is an example of a test that requires access to the BucketFS. Again, this test will -run for each backend, unless one of them is disabled in the CLI. +### BucketFS + +This test accesses the [BucketFS](https://docs.exasol.com/db/latest/database_concepts/bucketfs/bucketfs.htm). Again, this test will run for each backend, unless one of them is disabled in the CLI. ```python import exasol.bucketfs as bfs @@ -45,8 +70,9 @@ def test_my_file_exists(backend_aware_bucketfs_params): assert my_bfs_file.exists() ``` -Sometimes it may be necessary to know which backend the test is running with. In such -a case the `backend` fixture can be used, as in the example below. +### Inspect the Selected Backend Variant + +For inquiring the currenty selected backend variant in a test case, you can use the `backend` fixture, as shown below. ```python def test_something_backend_sensitive(backend): @@ -60,35 +86,67 @@ def test_something_backend_sensitive(backend): raise RuntimeError(f'Unknown backend {backend}') ``` -## Selecting Backends in CLI +## Selecting Backends on the Command Line + +There is no default backend specified for testing. + +Please use the `--backend` option to specify the target backend with either `onprem`, `saas`, or `all`. + +The plugin automatically starts the selected backends and shuts them down after the test session has finished. +* A SaaS backend is started via [saas-api-python](https://github.com/exasol/saas-api-python/). +* An On-Prem backend via the [ITDE](https://github.com/exasol/integration-test-docker-environment). +* Additionally you can [use an external or local database](#re-using-an-external-or-local-database). + +Please noe that all selected backends are started preemptively, regardless of their _actual usage_ in tests. + +Therefore, it is important to make sure the backends are not selected where they are not needed, for instance when running unit tests only. + +### Example Command Lines -By default, none of the backends is selected for testing. Please use the `--backend` option to specify the target backend. -The command below runs the tests on an on-prem database. +Run the tests on an On-Prem database: ```shell pytest --backend=onprem my_test_suite.py ``` -This following command runs the test on two backends. +Run the tests on two backends: ```shell pytest --backend=onprem --backend=saas my_test_suite.py ``` -The next command runs the test on all backends, which currently is equivalent to the previous command since there -are only two backends available. +Run the test on all backends—equivalent to the previous command: ```shell pytest --backend=all my_test_suite.py ``` -Please note that all selected backends starts preemptively, regardless of their actual usage in tests. -Therefore, it is important to make sure the backends are not selected where they are not needed, -for instance when running unit tests only. +### (Re-)Using an External or Local Database + +During development you can shorten the time between code changes and running the tests by (re-)using a backend that is already running. + +To save 2-20 minutes each cycle, simply add CLI parameter `--itde-db-version=external`. + +Alternatively, you can export environment variable `PYTEST_ADDOPTS`, e.g. +```shell +export PYTEST_ADDOPTS="--backend=onprem --itde-db-version=external" +``` + +More parameters may be required if your setup deviates from the default values: + +| Option | Default value | +|-----------------------|------------------| +| `--exasol-host` | `localhost` | +| `--exasol-port` | `8563` | +| `--exasol-username` | `sys` | +| `--exasol-password` | `exasol` | +| `--bucketfs-url` | `127.0.0.1:2580` | +| `--bucketfs-username` | `w` | +| `--bucketfs-password` | (none) | -## Setting ITDE parameters in CLI +### Setting ITDE Parameters via CLI Options -Sometimes the default ITDE parameters cannot satisfy the test requirements. The plugin allows setting +Sometimes, the default ITDE parameters cannot satisfy the test requirements. The plugin allows setting some of the parameters of the [api.spawn_test_environment(...)](https://github.com/exasol/integration-test-docker-environment/blob/92cc67b8f9ab78c52106c1c4ba19fe64811bcb2c/exasol_integration_test_docker_environment/lib/api/spawn_test_environment.py#L35) function. The parameter values can be provided in the CLI options. Currently, it is possible to set values of the following parameters: - `--itde-db-mem-size` @@ -97,7 +155,7 @@ function. The parameter values can be provided in the CLI options. Currently, it - `--itde-additional-db-parameter` - `--itde-db-version` -In the example below the tests are run using an instance of the DockerDB with increased memory. +This example runs the tests using an instance of the DockerDB with increased memory. ```shell pytest --backend=onprem --itde-db-mem-size "8 GiB" my_test_suite.py diff --git a/pytest-backend/doc/changes/unreleased.md b/pytest-backend/doc/changes/unreleased.md index ecb975a..c982f3e 100644 --- a/pytest-backend/doc/changes/unreleased.md +++ b/pytest-backend/doc/changes/unreleased.md @@ -1,7 +1,8 @@ # Unreleased -## Internal +## Refactorings * #140: Ensured that a proper project-short-tag is used in SaaS tests. * #141: Added a Merge Gate to the CI Workflow. * #146: Relocked transitive dependency filelock +* #150: Updated user guide and added instructions for (re-)using an external or local database to the `README`