Create pytest_plugin (#409)

Extracts the suite's `conftest` into a pytest plugin.
Removes the autouse on the fixtures to prevent automatic
invocation when libvcs is installed.

Author: tony

.coveragerc

@@ -1,14 +1,21 @@
 [run]
+parallel = 1
+branch = 1
+
 omit =
-    */_*
-    pkg/*
-    */log.py
+    docs/conf.py
+    */_compat.py
     */conftest.py
 
 [report]
+skip_covered = True
+show_missing = True
 exclude_lines =
-    pragma: no cover
-    def __repr__
-    raise NotImplementedError
-    if __name__ == .__main__.:
-    def parse_args
+    \#\s*pragma: no cover
+    ^\s*raise NotImplementedError\b
+    ^\s*return NotImplemented\b
+    ^\s*assert False(,|$)
+    ^\s*assert_never\(
+
+    ^\s*if TYPE_CHECKING:
+    ^\s*@overload( |$)

.github/workflows/tests.yml

@@ -43,8 +43,11 @@ jobs:
           poetry run python -V
 
       - name: Test with pytest
-        run: poetry run py.test --cov=./ --cov-report=xml
-
+        run: poetry run py.test --cov=./ --cov-append --cov-report=xml
+        env:
+          COV_CORE_SOURCE: .
+          COV_CORE_CONFIG: .coveragerc
+          COV_CORE_DATAFILE: .coverage.eager
       - uses: codecov/codecov-action@v3
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

docs/conf.py

@@ -161,6 +161,7 @@
 intersphinx_mapping = {
     "py": ("https://docs.python.org/3", None),
     "pip": ("https://pip.pypa.io/en/latest/", None),
+    "pytest": ("https://docs.pytest.org/en/stable/", None),
     "vcspull": ("https://vcspull.git-pull.com/", None),
     "gp-libs": ("https://gp-libs.git-pull.com/", None),
 }

docs/index.md

@@ -12,6 +12,7 @@ quickstart
 url/index
 cmd/index
 sync/index
+pytest-plugin
 ```
 
 ```{toctree}

docs/pytest-plugin.md

@@ -0,0 +1,93 @@
+(pytest_plugin)=
+
+# `pytest` plugin
+
+Create git, svn, and hg repos on the fly in [pytest].
+
+```{seealso} Using libvcs?
+
+Do you want more flexbility? Correctness? Power? Defaults changed? [Connect with us] on the tracker, we want to know
+your case, we won't stabilize APIs until we're sure everything is by the book.
+
+[connect with us]: https://github.com/vcs-python/libvcs/discussions
+
+```
+
+```{module} libvcs.pytest_plugin
+
+```
+
+[pytest]: https://docs.pytest.org/
+
+## Usage
+
+Install `libvcs` via the python package manager of your choosing, e.g.
+
+```console
+$ pip install libvcs
+```
+
+The pytest plugin will automatically be detected via pytest, and the fixtures will be added.
+
+## Fixtures
+
+`pytest-vcs` works through providing {ref}`pytest fixtures <pytest:fixtures-api>` - so read up on
+those!
+
+The plugin's fixtures guarantee a fresh git repository very test.
+
+(recommended-fixtures)=
+
+## Recommended fixtures
+
+These are fixtures are automatically used when the plugin is enabled and `pytest` is ran.
+
+- Creating temporary, test directories for:
+  - `/home/` ({func}`home_path`)
+  - `/home/${user}` ({func}`user_path`)
+- Setting your home directory
+  - Patch `$HOME` to point to {func}`user_path` ({func}`set_home`)
+- Set default configuration
+
+  - `.gitconfig`, via {func}`gitconfig`:
+  - `.hgrc`, via {func}`hgconfig`:
+
+  These are set to ensure you can correctly clone and create repositories withou. without extra
+  warnings.
+
+## Bootstrapping pytest in your `conftest.py`
+
+The most common scenario is you will want to configure the above fixtures with `autouse`.
+
+_Why doesn't the plugin automatically add them?_ It's part of being a decent pytest plugin and
+python package: explicitness.
+
+(set_home)=
+
+### Setting a temporary home directory
+
+```python
+import pytest
+
+@pytest.fixture(autouse=True)
+def setup(
+    set_home: None,
+):
+    pass
+```
+
+## See examples
+
+View libvcs's own [tests/](https://github.com/vcs-python/libvcs/tree/master/tests)
+
+## API reference
+
+```{eval-rst}
+.. automodule:: libvcs.pytest_plugin
+    :members:
+    :inherited-members:
+    :private-members:
+    :show-inheritance:
+    :member-order: bysource
+`
+```

pyproject.toml

@@ -26,6 +26,7 @@ classifiers = [
   "Development Status :: 4 - Beta",
   "License :: OSI Approved :: MIT License",
   "Environment :: Console",
+  "Framework :: Pytest",
   "Intended Audience :: Developers",
   "Operating System :: POSIX",
   "Operating System :: MacOS :: MacOS X",
@@ -128,6 +129,9 @@ lint = [
   "types-docutils",
 ]
 
+[tool.poetry.plugins.pytest11]
+libvcs = "libvcs.pytest_plugin"
+
 [tool.mypy]
 strict = true