Coverage for tests/conftest.py: 42.86%

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

2 

3from __future__ import annotations 

4 

5from collections import ChainMap 

6from typing import TYPE_CHECKING, Any 

7 

8import pytest 

9from markdown.core import Markdown 

10from mkdocs import config 

11from mkdocs.config.defaults import get_schema 

12 

13if TYPE_CHECKING: 

14 from collections.abc import Iterator 

15 from pathlib import Path 

16 

17 from mkdocstrings import MkdocstringsPlugin 

18 

19 from mkdocstrings_handlers.shell.handler import ShellHandler 

20 

21 

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

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

24 """Yield a MkDocs configuration object. 

25 

26 Parameters: 

27 request: Pytest fixture. 

28 tmp_path: Pytest fixture. 

29 

30 Yields: 

31 MkDocs config. 

32 """ 

33 conf = config.Config(schema=get_schema()) # type: ignore[call-arg] 

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

35 request = request._parent_request 

36 

37 conf_dict = { 

38 "config_file_path": "mkdocs.yml", 

39 "site_name": "foo", 

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

41 "site_dir": str(tmp_path), 

42 "plugins": [{"mkdocstrings": {"default_handler": "shell"}}], 

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

44 } 

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

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

47 

48 conf.load_dict(conf_dict) 

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

50 

51 conf["mdx_configs"] = mdx_configs 

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

53 

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

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

56 yield conf 

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

58 

59 

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

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

62 """Return a plugin instance. 

63 

64 Parameters: 

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

66 

67 Returns: 

68 mkdocstrings plugin instance. 

69 """ 

70 return mkdocs_conf["plugins"]["mkdocstrings"] 

71 

72 

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

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

75 """Return a Markdown instance with MkdocstringsExtension. 

76 

77 Parameters: 

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

79 

80 Returns: 

81 A Markdown instance. 

82 """ 

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

84 

85 

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

87def fixture_handler(plugin: MkdocstringsPlugin, ext_markdown: Markdown) -> ShellHandler: 

88 """Return a handler instance. 

89 

90 Parameters: 

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

92 

93 Returns: 

94 A handler instance. 

95 """ 

96 handler = plugin.handlers.get_handler("shell") 

97 handler._update_env(ext_markdown, config=plugin.handlers._tool_config) 

98 return handler