Deploying to gh-pages from @ 3e60237 🚀

_sources/changes/unreleased.md.txt

@@ -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`

_sources/developer_guide/developer_guide.rst.txt

@@ -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
 *******************
 

changes/unreleased.html

@@ -297,6 +297,12 @@ <h2>Refactorings<a class="headerlink" href="#refactorings" title="Permalink to t
 <li><p>#141: Used plugin <code class="docutils literal notranslate"><span class="pre">pytest_exasol_saas</span></code></p></li>
 </ul>
 </section>
+<section id="documentation">
+<h2>Documentation<a class="headerlink" href="#documentation" title="Permalink to this heading">¶</a></h2>
+<ul class="simple">
+<li><p>#144: Added comment on using fixtures from pytest-plugin <code class="docutils literal notranslate"><span class="pre">pytest-exasol-saas</span></code></p></li>
+</ul>
+</section>
 </section>
 
         </article>
@@ -357,6 +363,7 @@ <h2>Refactorings<a class="headerlink" href="#refactorings" title="Permalink to t
 <li><a class="reference internal" href="#">Unreleased</a><ul>
 <li><a class="reference internal" href="#summary">Summary</a></li>
 <li><a class="reference internal" href="#refactorings">Refactorings</a></li>
+<li><a class="reference internal" href="#documentation">Documentation</a></li>
 </ul>
 </li>
 </ul>

developer_guide/developer_guide.html

@@ -308,6 +308,62 @@ <h3>Setup pre-commit hook(s)<a class="headerlink" href="#setup-pre-commit-hook-s
 </div>
 </section>
 </section>
+<section id="tests">
+<h2>Tests<a class="headerlink" href="#tests" title="Permalink to this heading">¶</a></h2>
+<section id="pytest-plugins">
+<h3>Pytest Plugins<a class="headerlink" href="#pytest-plugins" title="Permalink to this heading">¶</a></h3>
+<p>BFSPY declares a dependency to pytest plugin <code class="docutils literal notranslate"><span class="pre">pytest-exasol-saas</span></code> which is
+maintained in GitHub repository <a class="reference external" href="https://github.com/exasol/pytest-plugins/tree/main/pytest-saas/">pytest-plugins/pytest_saas</a>.  This
+plugin makes additional fixtures available that are used in the saas
+integration tests of BFSPY, see files in folder <a class="reference external" href="https://github.com/exasol/bucketfs-python/tree/main/test_saas/integration/">test_saas/integration</a>.</p>
+</section>
+<section id="running-tests-in-ci-builds">
+<h3>Running Tests in CI Builds<a class="headerlink" href="#running-tests-in-ci-builds" title="Permalink to this heading">¶</a></h3>
+<p>The test cases in BFSPY are separated in two groups.</p>
+<div class="table-wrapper docutils container">
+<table class="docutils align-default">
+<thead>
+<tr class="row-odd"><th class="head"><p>Group</p></th>
+<th class="head"><p>Execution</p></th>
+<th class="head"><p>Name of gating GitHub workflow</p></th>
+</tr>
+</thead>
+<tbody>
+<tr class="row-even"><td><p>G1) Fast and cheap tests</p></td>
+<td><p>On each push to your development branch</p></td>
+<td><p>Gate 1 - Regular CI</p></td>
+</tr>
+<tr class="row-odd"><td><p>G2) Slow or expensive tests</p></td>
+<td><p>Only on manual approval, see below</p></td>
+<td><p>Gate 2 - Allow Merge</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+<p>This enables fast development cycles while still protecting the main branch
+against build failures.</p>
+<p>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.</p>
+<p>Group G2 is guarded by a dedicated <a class="reference external" href="https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#required-reviewers">GitHub Enviroment</a>
+requiring <strong>manual approval</strong> before these tests are executed.</p>
+<p>Each of the groups results in a final gating GitHub workflow job that is added to the branch protection of branch <code class="docutils literal notranslate"><span class="pre">main</span></code>.</p>
+<p>So in order to merge a branch to <code class="docutils literal notranslate"><span class="pre">main</span></code> branch, the tests of both groups need to be executed and to have terminated succesfully.</p>
+<section id="approving-slow-tests">
+<h4>Approving Slow Tests<a class="headerlink" href="#approving-slow-tests" title="Permalink to this heading">¶</a></h4>
+<p>To approve executing the tests in group G2</p>
+<ul class="simple">
+<li><p>Open your pull request in GitHub</p></li>
+<li><p>Scroll to section “Checks”</p></li>
+<li><p>Locate pending tasks, e.g. “Ask if Slow or Expensive Tests (e.g. SaaS) Should be Run”</p></li>
+<li><p>Click the link “Details” on the right-hand side</p></li>
+<li><p>Click “Review pending Deplopyments”</p></li>
+<li><p>Select the checkbox “slow-tests”</p></li>
+<li><p>Click the green button “Approve and deploy”</p></li>
+</ul>
+</section>
+</section>
+</section>
 <section id="creating-a-release">
 <h2>Creating a Release<a class="headerlink" href="#creating-a-release" title="Permalink to this heading">¶</a></h2>
 <section id="prepare-the-release">
@@ -452,6 +508,14 @@ <h4>One of the release steps failed (Partial Release)<a class="headerlink" href=
 <li><a class="reference internal" href="#setup-pre-commit-hook-s">Setup pre-commit hook(s)</a></li>
 </ul>
 </li>
+<li><a class="reference internal" href="#tests">Tests</a><ul>
+<li><a class="reference internal" href="#pytest-plugins">Pytest Plugins</a></li>
+<li><a class="reference internal" href="#running-tests-in-ci-builds">Running Tests in CI Builds</a><ul>
+<li><a class="reference internal" href="#approving-slow-tests">Approving Slow Tests</a></li>
+</ul>
+</li>
+</ul>
+</li>
 <li><a class="reference internal" href="#creating-a-release">Creating a Release</a><ul>
 <li><a class="reference internal" href="#prepare-the-release">Prepare the Release</a></li>
 <li><a class="reference internal" href="#triggering-the-release">Triggering the Release</a></li>