Coverage for tests/conftest.py: 93.02%

1"""Configuration for the pytest test suite.""" 

2 

3from __future__ import annotations 

4 

5from collections import ChainMap 

6from typing import TYPE_CHECKING, Any, Iterator 

7 

8import pytest 

9from markdown.core import Markdown 

10from mkdocs import config 

11from mkdocs.config.defaults import MkDocsConfig 

12 

13if TYPE_CHECKING: 

14 from pathlib import Path 

15 

16 from mkdocstrings.plugin import MkdocstringsPlugin 

17 

18 from mkdocstrings_handlers.c.handler import CHandler 

19 

20 

21@pytest.fixture(name="mkdocs_conf") 

22def fixture_mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Iterator[config.Config]: 

23 """Yield a MkDocs configuration object.""" 

24 conf = MkDocsConfig() 

25 while hasattr(request, "_parent_request") and hasattr(request._parent_request, "_parent_request"): 

26 request = request._parent_request 

27 

28 conf_dict = { 

29 "site_name": "foo", 

30 "site_url": "https://example.org/", 

31 "site_dir": str(tmp_path), 

32 "plugins": [{"mkdocstrings": {"default_handler": "c"}}], 

33 **getattr(request, "param", {}), 

34 } 

35 # Re-create it manually as a workaround for https://github.com/mkdocs/mkdocs/issues/2289 

36 mdx_configs: dict[str, Any] = dict(ChainMap(*conf_dict.get("markdown_extensions", []))) 

37 

38 conf.load_dict(conf_dict) 

39 assert conf.validate() == ([], []) 

40 

41 conf["mdx_configs"] = mdx_configs 

42 conf["markdown_extensions"].insert(0, "toc") # Guaranteed to be added by MkDocs. 

43 

44 conf = conf["plugins"]["mkdocstrings"].on_config(conf) 

45 conf = conf["plugins"]["autorefs"].on_config(conf) 

46 yield conf 

47 conf["plugins"]["mkdocstrings"].on_post_build(conf) 

48 

49 

50@pytest.fixture(name="plugin") 

51def fixture_plugin(mkdocs_conf: config.Config) -> MkdocstringsPlugin: 

52 """Return a plugin instance. 

53 

54 Parameters: 

55 mkdocs_conf: Pytest fixture (see conftest.py). 

56 

57 Returns: 

58 mkdocstrings plugin instance. 

59 """ 

60 return mkdocs_conf["plugins"]["mkdocstrings"] 

61 

62 

63@pytest.fixture(name="ext_markdown") 

64def fixture_ext_markdown(mkdocs_conf: config.Config) -> Markdown: 

65 """Return a Markdown instance with MkdocstringsExtension. 

66 

67 Parameters: 

68 mkdocs_conf: Pytest fixture (see conftest.py). 

69 

70 Returns: 

71 A Markdown instance. 

72 """ 

73 return Markdown(extensions=mkdocs_conf["markdown_extensions"], extension_configs=mkdocs_conf["mdx_configs"]) 

74 

75 

76@pytest.fixture(name="handler") 

77def fixture_handler(plugin: MkdocstringsPlugin, ext_markdown: Markdown) -> CHandler: 

78 """Return a handler instance. 

79 

80 Parameters: 

81 plugin: Pytest fixture (see conftest.py). 

82 

83 Returns: 

84 A handler instance. 

85 """ 

86 handler = plugin.handlers.get_handler("c") 

87 handler._update_env(ext_markdown, plugin.handlers._config) 

88 return handler # type: ignore[return-value]