From 3e6023726d8475327cd746067561dfacb0d3439a Mon Sep 17 00:00:00 2001
From: Christoph Kuhnke <github@kuhnke.net>
Date: Fri, 14 Jun 2024 13:57:26 +0200
Subject: [PATCH] =?UTF-8?q?=20#144:=20Added=20comment=20on=20using=20fixtu?=
 =?UTF-8?q?res=20from=20pytest-plugin=20pytest-exas=E2=80=A6=20(#145)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

Co-authored-by: Christoph Pirkl <4711730+kaklakariada@users.noreply.github.com>
---
 doc/changes/unreleased.md               |  4 ++
 doc/developer_guide/developer_guide.rst | 54 +++++++++++++++++++++++++
 test_saas/integration/conftest.py       |  2 +
 3 files changed, 60 insertions(+)
 create mode 100644 test_saas/integration/conftest.py

diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md
index e043d65d..c0d363e8 100644
--- a/doc/changes/unreleased.md
+++ b/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`
diff --git a/doc/developer_guide/developer_guide.rst b/doc/developer_guide/developer_guide.rst
index a3bbc1e4..f9c2abab 100644
--- a/doc/developer_guide/developer_guide.rst
+++ b/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
 *******************
 
diff --git a/test_saas/integration/conftest.py b/test_saas/integration/conftest.py
new file mode 100644
index 00000000..ea00c590
--- /dev/null
+++ b/test_saas/integration/conftest.py
@@ -0,0 +1,2 @@
+# Additional fixtures provided by pytest-plugin pytest_exasol_saas
+# See Developer Guide.