Merge pull request #703 from enzbang/pytest-plugin

Create a pytest plugin to reuse fixtures in other projects

.github/workflows/ci.yaml

@@ -31,7 +31,7 @@ jobs:
       - name: Run Tox
         run: tox
         env:
-            TOXENV: py${{ matrix.python-version}}-ci-xdist-cov
+            TOXENV: py${{ matrix.python-version}}-xdist-cov
 
   security:
     runs-on: ubuntu-latest

.gitignore

@@ -3,6 +3,7 @@ __pycache__
 /.cache
 /.coverage*
 /.coveragerc
+/coverage.xml
 /.idea
 /dist/
 /build/

NEWS.md

@@ -1,9 +1,9 @@
 
-# Version 22.5.0 (2023-??-??) *NOT RELEASED YET*
+# Version 22.5.0 (2024-??-??) *NOT RELEASED YET*
 
-* Nothing
+* Add e3.pytest plugin to reuse fixtures in other projects
 
-# Version 22.4.0 (2023-01-18)
+# Version 22.4.0 (2024-01-18)
 
 * Security enhancements:
   * e3.net.smtp.sendmail uses to ``SMTP_SSL`` by default

docs/source/index.rst

@@ -14,7 +14,7 @@ Welcome to e3-core's documentation!
    quickstart
    decision_graph
    plugins
-   requirements
+   pytest
 
 
 

docs/source/pytest.rst

@@ -0,0 +1,85 @@
+Using the e3 pytest plugin
+==========================
+
+Introduction
+------------
+
+``e3-core`` contains a ``pytest`` plugin that is discovered automatically when
+installed. The plugin provides several features: it generates a results file
+compatible with anod when the environment variable ``RESULTS_DIR`` is defined.
+It provides a simple setup for running coverage (on top of the pytest-cov
+plugin). And it provides a env_protect fixture that is automatically activated.
+
+
+Activating e3-core pytest plugins
+---------------------------------
+
+To activate the e3-core pytest plugin, you need to install e3-core and pass
+the option ``--e3`` to pytest.
+
+env_protect
+^^^^^^^^^^^
+
+When activated, the plugin will register the ``env_protect`` feature to ensure
+that all tests are run in isolation. All changes to the environment done in
+each test won't impact other tests. Also, each test is run in a separate temp
+directory, you won't have to cleanup the files that the tests create.
+
+``env_protect`` also sets some environment variables such as:
+
+* ``TZ=UTC`` to ensure a consistent timezone handling
+* ``E3_ENABLE_FEATURE=""`` to discard any specific features supported by e3
+* ``E3_CONFIG=/dev/null`` to avoid having a specific e3 config read by the tests
+
+And the e3 DEBUG log level is activated for each tests.
+
+Coverage
+^^^^^^^^
+
+When running pytest with ``--e3`` and ``--cov`` options, pytest will
+automatically generate an exclude list for lines matching the following
+patterns:
+
+* ``all: no cover``
+* ``if TYPE_CHECKING:``
+* ``@abstractmethod``
+* ``# os-specific``
+* ``defensive code``
+* ``assert_never(),``
+
+And ``<os>-only`` with ``<os>`` different from the local OS, so if you're
+running a test on Linux, ``windows-only`` and ``darwin-only`` will be discared.
+
+The opposite ``<os>: no cover`` is also supported.
+
+Specific test for the windows platform are also detected:
+
+* ``if sys.platform == win32``
+* ``if sys.platform != win32``
+* ``unix-only``
+
+You can also skip complete files by creating an ``omit file`` in
+``tests/coverage/omit-file-<os>``. The file should contain a filename per line.
+
+Finally, the option ``--e3-cov-rewrite <origin> <dest>`` changes the paths
+reported by coverage. If you run ``--e3-cov-rewrite
+.tox/py311/cov-xdist/lib-site-packages src`` instead of seeing reports of files in
+``.tox/py311-cov-xdist/lib/site-packages/e3/`` the report will show files
+in the repository ``src/e3/``.
+
+``require_tool`` fixture
+------------------------
+
+``e3.pytest`` provides a function ``require_tool`` that generates a fixture
+allowing to skip tests if a tool is missing. For instance, to create a fixture
+that will skip tests if ``git`` is not installed run:
+
+.. code-block:: python
+
+   from e3.pytest import require_tool
+
+   git = require_tool("git")
+
+   # Use it in a test that will run only if git is installed
+   def test_git_fixture(git):
+       ...

pyproject.toml

@@ -61,6 +61,7 @@ test = [
 ]
 check = [
   "mypy==1.8.0",
+  "pytest",  # for the pytest plugin
   "bandit",
   "pip-audit",
   "types-colorama",
@@ -97,9 +98,28 @@ file-cache = "e3.store.cache.backends.filecache:FileCache"
 [project.entry-points."sandbox_scripts"]
 anod = "e3.anod.sandbox.scripts:anod"
 
+[project.entry-points."pytest11"]
+pytest = "e3.pytest"
+
 [tool.setuptools.dynamic]
 version = {file = "VERSION"}
 
+[tool.coverage.report]
+fail_under = 90
+
+[tool.coverage.run]
+branch = true
+omit = [
+   "*mypy.py"
+]
+
+[tool.coverage.html]
+title = "e3 coverage report"
+
+[tool.pytest.ini_options]
+addopts = "--failed-first --disable-socket --e3"
+
+
 [tool.mypy]
 # Ensure mypy works with namespace in which there is no toplevel
 # __init__.py. Explicit_package_bases means that that mypy_path