tests: Add end-to-end tests, many options combinations, using inline-snapshot

duties.py

@@ -217,20 +217,26 @@ def coverage(ctx: Context) -> None:
 
 
 @duty
-def test(ctx: Context, *cli_args: str, match: str = "") -> None:
+def test(ctx: Context, *cli_args: str, match: str = "", snapshot: str = "report") -> None:
     """Run the test suite.
 
     Parameters:
         match: A pytest expression to filter selected tests.
+        snapshot: Whether to "create", "fix", "trim", or "update" snapshots.
     """
     py_version = f"{sys.version_info.major}{sys.version_info.minor}"
     os.environ["COVERAGE_FILE"] = f".coverage.{py_version}"
+    args = list(cli_args)
+    if snapshot == "disable" or not snapshot:
+        args = ["-n", "auto", "--inline-snapshot=disable"]
+    else:
+        args = [f"--inline-snapshot={snapshot}"]
     ctx.run(
         tools.pytest(
             "tests",
             config_file="config/pytest.ini",
             select=match,
             color="yes",
-        ).add_args("-n", "auto", *cli_args),
+        ).add_args(*args),
         title=pyprefix("Running tests"),
     )

pyproject.toml

@@ -90,6 +90,8 @@ dev = [
     "pytest-cov>=5.0",
     "pytest-randomly>=3.15",
     "pytest-xdist>=3.6",
+    "beautifulsoup4>=4.12.3",
+    "inline-snapshot>=0.18",
     "mypy>=1.10",
     "types-markdown>=3.6",
     "types-pyyaml>=6.0",
@@ -107,4 +109,7 @@ dev = [
     "mkdocs-minify-plugin>=0.8",
     # YORE: EOL 3.10: Remove line.
     "tomli>=2.0; python_version < '3.11'",
-]
+]
+
+[tool.inline-snapshot]
+storage-dir = "tests/snapshots"

tests/conftest.py

@@ -2,25 +2,29 @@
 
 from __future__ import annotations
 
-from collections import ChainMap
-from typing import TYPE_CHECKING, Any
+from collections.abc import Iterator
+from typing import TYPE_CHECKING
 
 import pytest
-from markdown.core import Markdown
-from mkdocs.config.defaults import MkDocsConfig
+
+from tests import helpers
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
     from pathlib import Path
 
-    from mkdocs import config
+    from markdown.core import Markdown
+    from mkdocs.config.defaults import MkDocsConfig
     from mkdocstrings.plugin import MkdocstringsPlugin
 
     from mkdocstrings_handlers.python.handler import PythonHandler
 
 
+# --------------------------------------------
+# Function-scoped fixtures.
+# --------------------------------------------
 @pytest.fixture(name="mkdocs_conf")
-def fixture_mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Iterator[config.Config]:
+def fixture_mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Iterator[MkDocsConfig]:
     """Yield a MkDocs configuration object.
 
     Parameters:
@@ -30,34 +34,12 @@ def fixture_mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Itera
     Yields:
         MkDocs config.
     """
-    conf = MkDocsConfig()
-    while hasattr(request, "_parent_request") and hasattr(request._parent_request, "_parent_request"):
-        request = request._parent_request
-
-    conf_dict = {
-        "site_name": "foo",
-        "site_url": "https://example.org/",
-        "site_dir": str(tmp_path),
-        "plugins": [{"mkdocstrings": {"default_handler": "python"}}],
-        **getattr(request, "param", {}),
-    }
-    # Re-create it manually as a workaround for https://github.com/mkdocs/mkdocs/issues/2289
-    mdx_configs: dict[str, Any] = dict(ChainMap(*conf_dict.get("markdown_extensions", [])))
-
-    conf.load_dict(conf_dict)
-    assert conf.validate() == ([], [])
-
-    conf["mdx_configs"] = mdx_configs
-    conf["markdown_extensions"].insert(0, "toc")  # Guaranteed to be added by MkDocs.
-
-    conf = conf["plugins"]["mkdocstrings"].on_config(conf)
-    conf = conf["plugins"]["autorefs"].on_config(conf)
-    yield conf
-    conf["plugins"]["mkdocstrings"].on_post_build(conf)
+    with helpers.mkdocs_conf(request, tmp_path) as mkdocs_conf:
+        yield mkdocs_conf
 
 
 @pytest.fixture(name="plugin")
-def fixture_plugin(mkdocs_conf: config.Config) -> MkdocstringsPlugin:
+def fixture_plugin(mkdocs_conf: MkDocsConfig) -> MkdocstringsPlugin:
     """Return a plugin instance.
 
     Parameters:
@@ -66,11 +48,11 @@ def fixture_plugin(mkdocs_conf: config.Config) -> MkdocstringsPlugin:
     Returns:
         mkdocstrings plugin instance.
     """
-    return mkdocs_conf["plugins"]["mkdocstrings"]
+    return helpers.plugin(mkdocs_conf)
 
 
 @pytest.fixture(name="ext_markdown")
-def fixture_ext_markdown(mkdocs_conf: config.Config) -> Markdown:
+def fixture_ext_markdown(mkdocs_conf: MkDocsConfig) -> Markdown:
     """Return a Markdown instance with MkdocstringsExtension.
 
     Parameters:
@@ -79,7 +61,7 @@ def fixture_ext_markdown(mkdocs_conf: config.Config) -> Markdown:
     Returns:
         A Markdown instance.
     """
-    return Markdown(extensions=mkdocs_conf["markdown_extensions"], extension_configs=mkdocs_conf["mdx_configs"])
+    return helpers.ext_markdown(mkdocs_conf)
 
 
 @pytest.fixture(name="handler")
@@ -92,6 +74,64 @@ def fixture_handler(plugin: MkdocstringsPlugin, ext_markdown: Markdown) -> Pytho
     Returns:
         A handler instance.
     """
-    handler = plugin.handlers.get_handler("python")
-    handler._update_env(ext_markdown, plugin.handlers._config)
-    return handler  # type: ignore[return-value]
+    return helpers.handler(plugin, ext_markdown)
+
+
+# --------------------------------------------
+# Session-scoped fixtures.
+# --------------------------------------------
+@pytest.fixture(name="session_mkdocs_conf", scope="session")
+def fixture_session_mkdocs_conf(
+    request: pytest.FixtureRequest,
+    tmp_path_factory: pytest.TempPathFactory,
+) -> Iterator[MkDocsConfig]:
+    """Yield a MkDocs configuration object.
+
+    Parameters:
+        request: Pytest fixture.
+        tmp_path: Pytest fixture.
+
+    Yields:
+        MkDocs config.
+    """
+    with helpers.mkdocs_conf(request, tmp_path_factory.mktemp("project")) as mkdocs_conf:
+        yield mkdocs_conf
+
+
+@pytest.fixture(name="session_plugin", scope="session")
+def fixture_session_plugin(session_mkdocs_conf: MkDocsConfig) -> MkdocstringsPlugin:
+    """Return a plugin instance.
+
+    Parameters:
+        mkdocs_conf: Pytest fixture (see conftest.py).
+
+    Returns:
+        mkdocstrings plugin instance.
+    """
+    return helpers.plugin(session_mkdocs_conf)
+
+
+@pytest.fixture(name="session_ext_markdown", scope="session")
+def fixture_session_ext_markdown(session_mkdocs_conf: MkDocsConfig) -> Markdown:
+    """Return a Markdown instance with MkdocstringsExtension.
+
+    Parameters:
+        mkdocs_conf: Pytest fixture (see conftest.py).
+
+    Returns:
+        A Markdown instance.
+    """
+    return helpers.ext_markdown(session_mkdocs_conf)
+
+
+@pytest.fixture(name="session_handler", scope="session")
+def fixture_session_handler(session_plugin: MkdocstringsPlugin, session_ext_markdown: Markdown) -> PythonHandler:
+    """Return a handler instance.
+
+    Parameters:
+        plugin: Pytest fixture (see conftest.py).
+
+    Returns:
+        A handler instance.
+    """
+    return helpers.handler(session_plugin, session_ext_markdown)

tests/helpers.py

@@ -0,0 +1,94 @@
+"""Configuration for the pytest test suite."""
+
+from __future__ import annotations
+
+from collections import ChainMap
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+from markdown.core import Markdown
+from mkdocs.config.defaults import MkDocsConfig
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+    import pytest
+    from mkdocstrings.plugin import MkdocstringsPlugin
+
+    from mkdocstrings_handlers.python.handler import PythonHandler
+
+
+@contextmanager
+def mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Iterator[MkDocsConfig]:
+    """Yield a MkDocs configuration object.
+
+    Parameters:
+        request: Pytest request fixture.
+        tmp_path: Temporary path.
+
+    Yields:
+        MkDocs config.
+    """
+    conf = MkDocsConfig()
+    while hasattr(request, "_parent_request") and hasattr(request._parent_request, "_parent_request"):
+        request = request._parent_request
+
+    conf_dict = {
+        "site_name": "foo",
+        "site_url": "https://example.org/",
+        "site_dir": str(tmp_path),
+        "plugins": [{"mkdocstrings": {"default_handler": "python"}}],
+        **getattr(request, "param", {}),
+    }
+    # Re-create it manually as a workaround for https://github.com/mkdocs/mkdocs/issues/2289
+    mdx_configs: dict[str, Any] = dict(ChainMap(*conf_dict.get("markdown_extensions", [])))
+
+    conf.load_dict(conf_dict)
+    assert conf.validate() == ([], [])
+
+    conf["mdx_configs"] = mdx_configs
+    conf["markdown_extensions"].insert(0, "toc")  # Guaranteed to be added by MkDocs.
+
+    conf = conf["plugins"]["mkdocstrings"].on_config(conf)
+    conf = conf["plugins"]["autorefs"].on_config(conf)
+    yield conf
+    conf["plugins"]["mkdocstrings"].on_post_build(conf)
+
+
+def plugin(mkdocs_conf: MkDocsConfig) -> MkdocstringsPlugin:
+    """Return a plugin instance.
+
+    Parameters:
+        mkdocs_conf: MkDocs configuration.
+
+    Returns:
+        mkdocstrings plugin instance.
+    """
+    return mkdocs_conf["plugins"]["mkdocstrings"]
+
+
+def ext_markdown(mkdocs_conf: MkDocsConfig) -> Markdown:
+    """Return a Markdown instance with MkdocstringsExtension.
+
+    Parameters:
+        mkdocs_conf: MkDocs configuration.
+
+    Returns:
+        A Markdown instance.
+    """
+    return Markdown(extensions=mkdocs_conf["markdown_extensions"], extension_configs=mkdocs_conf["mdx_configs"])
+
+
+def handler(plugin: MkdocstringsPlugin, ext_markdown: Markdown) -> PythonHandler:
+    """Return a handler instance.
+
+    Parameters:
+        plugin: Plugin instance.
+
+    Returns:
+        A handler instance.
+    """
+    handler = plugin.handlers.get_handler("python")
+    handler._update_env(ext_markdown, plugin.handlers._config)
+    return handler  # type: ignore[return-value]