diff --git a/tests/conftest.py b/tests/conftest.py index 3be27ba..b81fc56 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -1 +1,86 @@ """Configuration for the pytest test suite.""" + +from __future__ import annotations + +from collections import ChainMap + +import pytest +from markdown.core import Markdown +from mkdocs import config + +try: + from mkdocs.config.defaults import get_schema +except ImportError: + + def get_schema() -> tuple[tuple]: # noqa: WPS440 + """Fallback for old versions of MkDocs. + + Returns: + The default schema. + """ + return config.DEFAULT_SCHEMA + + +@pytest.fixture(name="mkdocs_conf") +def fixture_mkdocs_conf(request, tmp_path): + """Yield a MkDocs configuration object. + + Parameters: + request: Pytest fixture. + tmp_path: Pytest fixture. + + Yields: + MkDocs config. + """ + conf = config.Config(schema=get_schema()) + while hasattr(request, "_parent_request") and hasattr(request._parent_request, "_parent_request"): # noqa: WPS437 + request = request._parent_request # noqa: WPS437 + + 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(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) + + +@pytest.fixture(name="plugin") +def fixture_plugin(mkdocs_conf): + """Return a plugin instance. + + Parameters: + mkdocs_conf: Pytest fixture: [tests.conftest.fixture_mkdocs_conf][]. + + Returns: + mkdocstrings plugin instance. + """ + plugin = mkdocs_conf["plugins"]["mkdocstrings"] + plugin.md = Markdown(extensions=mkdocs_conf["markdown_extensions"], extension_configs=mkdocs_conf["mdx_configs"]) + return plugin + + +@pytest.fixture(name="ext_markdown") +def fixture_ext_markdown(plugin): + """Return a Markdown instance with MkdocstringsExtension. + + Parameters: + plugin: Pytest fixture: [tests.conftest.fixture_plugin][]. + + Returns: + A Markdown instance. + """ + return plugin.md diff --git a/tests/test_cli.py b/tests/test_cli.py deleted file mode 100644 index 652c09d..0000000 --- a/tests/test_cli.py +++ /dev/null @@ -1,23 +0,0 @@ -"""Tests for the `cli` module.""" - -import pytest - -from mkdocstrings import cli - - -def test_main(): - """Basic CLI test.""" - assert cli.main([]) == 0 - - -def test_show_help(capsys): - """ - Show help. - - Arguments: - capsys: Pytest fixture to capture output. - """ - with pytest.raises(SystemExit): - cli.main(["-h"]) - captured = capsys.readouterr() - assert "mkdocstrings-python" in captured.out diff --git a/tests/test_collector.py b/tests/test_collector.py new file mode 100644 index 0000000..2351343 --- /dev/null +++ b/tests/test_collector.py @@ -0,0 +1,25 @@ +"""Tests for the handlers.python module.""" + +import pytest + +from mkdocstrings.handlers.python.collector import CollectionError, PythonCollector + + +def test_collect_missing_module(): + """Assert error is raised for missing modules.""" + collector = PythonCollector() + with pytest.raises(CollectionError): + collector.collect("aaaaaaaa", {}) + + +def test_collect_missing_module_item(): + """Assert error is raised for missing items within existing modules.""" + collector = PythonCollector() + with pytest.raises(CollectionError): + collector.collect("mkdocstrings.aaaaaaaa", {}) + + +def test_collect_module(): + """Assert existing module can be collected.""" + collector = PythonCollector() + assert collector.collect("mkdocstrings", {}) diff --git a/tests/test_themes.py b/tests/test_themes.py new file mode 100644 index 0000000..779e443 --- /dev/null +++ b/tests/test_themes.py @@ -0,0 +1,40 @@ +"""Tests for the different themes we claim to support.""" + +import sys + +import pytest + + +@pytest.mark.parametrize( + "plugin", + [ + {"theme": "mkdocs"}, + {"theme": "readthedocs"}, + {"theme": {"name": "material"}}, + ], + indirect=["plugin"], +) +@pytest.mark.parametrize( + "module", + [ + "mkdocstrings.extension", + "mkdocstrings.inventory", + "mkdocstrings.loggers", + "mkdocstrings.plugin", + "mkdocstrings.handlers.base", + "mkdocstrings.handlers.python", + "mkdocstrings.handlers.rendering", + ], +) +@pytest.mark.skipif(sys.version_info < (3, 7), reason="material is not installed on Python 3.6") +def test_render_themes_templates_python(module, plugin): + """Test rendering of a given theme's templates. + + Parameters: + module: Parametrized argument. + plugin: Pytest fixture: [tests.conftest.fixture_plugin][]. + """ + handler = plugin.handlers.get_handler("python") + handler.renderer._update_env(plugin.md, plugin.handlers._config) # noqa: WPS437 + data = handler.collector.collect(module, {}) + handler.renderer.render(data, {})