#144: Added comment on using fixtures from pytest-plugin pytest-exas… (

#145)

* #144: Added comment on using fixtures from pytest-plugin pytest-exasol-saas
* Update test_saas/integration/confest.py

Co-authored-by: Christoph Pirkl <[email protected]>

doc/changes/unreleased.md

@@ -7,3 +7,7 @@ The current release adds a dependency to plugin `pytest_exasol_saas` and replace
 ## Refactorings
 
 * #141: Used plugin `pytest_exasol_saas`
+
+## Documentation
+
+* #144: Added comment on using fixtures from pytest-plugin `pytest-exasol-saas`

doc/developer_guide/developer_guide.rst

@@ -25,6 +25,60 @@ Setup pre-commit hook(s)
 
     poetry run pre-commit install
 
+Tests
+*****
+
+Pytest Plugins
+--------------
+
+BFSPY declares a dependency to pytest plugin ``pytest-exasol-saas`` which is
+maintained in GitHub repository `pytest-plugins/pytest_saas
+<https://github.com/exasol/pytest-plugins/tree/main/pytest-saas/>`_.  This
+plugin makes additional fixtures available that are used in the saas
+integration tests of BFSPY, see files in folder `test_saas/integration
+<https://github.com/exasol/bucketfs-python/tree/main/test_saas/integration/>`_.
+
+Running Tests in CI Builds
+--------------------------
+
+The test cases in BFSPY are separated in two groups.
+
++-----------------------------+-----------------------------------------+--------------------------------+
+| Group                       | Execution                               | Name of gating GitHub workflow |
++=============================+=========================================+================================+
+| G1) Fast and cheap tests    | On each push to your development branch | Gate 1 - Regular CI            |
++-----------------------------+-----------------------------------------+--------------------------------+
+| G2) Slow or expensive tests | Only on manual approval, see below      | Gate 2 - Allow Merge           |
++-----------------------------+-----------------------------------------+--------------------------------+
+
+This enables fast development cycles while still protecting the main branch
+against build failures.
+
+For BFSPY group G2 particularly contains the tests involving Exasol SaaS
+infrastructure which are creating costs for the database instances temporarily
+created during test execution.
+
+Group G2 is guarded by a dedicated `GitHub Enviroment
+<https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#required-reviewers>`_
+requiring **manual approval** before these tests are executed.
+
+Each of the groups results in a final gating GitHub workflow job that is added to the branch protection of branch ``main``.
+
+So in order to merge a branch to ``main`` branch, the tests of both groups need to be executed and to have terminated succesfully.
+
+Approving Slow Tests
+~~~~~~~~~~~~~~~~~~~~
+
+To approve executing the tests in group G2
+
+* Open your pull request in GitHub
+* Scroll to section "Checks"
+* Locate pending tasks, e.g. "Ask if Slow or Expensive Tests (e.g. SaaS) Should be Run"
+* Click the link "Details" on the right-hand side
+* Click "Review pending Deplopyments"
+* Select the checkbox "slow-tests"
+* Click the green button "Approve and deploy"
+
 Creating a Release
 *******************
 

test_saas/integration/conftest.py

@@ -0,0 +1,2 @@
+# Additional fixtures provided by pytest-plugin pytest_exasol_saas
+# See Developer Guide.