Coverage for tests/conftest.py: 100.00%

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

2 

3from __future__ import annotations 

4 

5from collections.abc import Iterator 

6from typing import TYPE_CHECKING 

7 

8import pytest 

9 

10from tests import helpers 

11 

12if TYPE_CHECKING: 

13 from collections.abc import Iterator 

14 from pathlib import Path 

15 

16 from markdown.core import Markdown 

17 from mkdocs.config.defaults import MkDocsConfig 

18 from mkdocstrings import MkdocstringsPlugin 

19 

20 from mkdocstrings_handlers.python import PythonHandler 

21 

22 

23# -------------------------------------------- 

24# Function-scoped fixtures. 

25# -------------------------------------------- 

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

27def fixture_mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Iterator[MkDocsConfig]: 

28 """Yield a MkDocs configuration object. 

29 

30 Parameters: 

31 request: Pytest fixture. 

32 tmp_path: Pytest fixture. 

33 

34 Yields: 

35 MkDocs config. 

36 """ 

37 with helpers.mkdocs_conf(request, tmp_path) as mkdocs_conf: 

38 yield mkdocs_conf 

39 

40 

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

42def fixture_plugin(mkdocs_conf: MkDocsConfig) -> MkdocstringsPlugin: 

43 """Return a plugin instance. 

44 

45 Parameters: 

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

47 

48 Returns: 

49 mkdocstrings plugin instance. 

50 """ 

51 return helpers.plugin(mkdocs_conf) 

52 

53 

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

55def fixture_ext_markdown(mkdocs_conf: MkDocsConfig) -> Markdown: 

56 """Return a Markdown instance with MkdocstringsExtension. 

57 

58 Parameters: 

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

60 

61 Returns: 

62 A Markdown instance. 

63 """ 

64 return helpers.ext_markdown(mkdocs_conf) 

65 

66 

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

68def fixture_handler(plugin: MkdocstringsPlugin, ext_markdown: Markdown) -> PythonHandler: 

69 """Return a handler instance. 

70 

71 Parameters: 

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

73 

74 Returns: 

75 A handler instance. 

76 """ 

77 return helpers.handler(plugin, ext_markdown) 

78 

79 

80# -------------------------------------------- 

81# Session-scoped fixtures. 

82# -------------------------------------------- 

83@pytest.fixture(name="session_mkdocs_conf", scope="session") 

84def fixture_session_mkdocs_conf( 

85 request: pytest.FixtureRequest, 

86 tmp_path_factory: pytest.TempPathFactory, 

87) -> Iterator[MkDocsConfig]: 

88 """Yield a MkDocs configuration object. 

89 

90 Parameters: 

91 request: Pytest fixture. 

92 tmp_path: Pytest fixture. 

93 

94 Yields: 

95 MkDocs config. 

96 """ 

97 with helpers.mkdocs_conf(request, tmp_path_factory.mktemp("project")) as mkdocs_conf: 

98 yield mkdocs_conf 

99 

100 

101@pytest.fixture(name="session_plugin", scope="session") 

102def fixture_session_plugin(session_mkdocs_conf: MkDocsConfig) -> MkdocstringsPlugin: 

103 """Return a plugin instance. 

104 

105 Parameters: 

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

107 

108 Returns: 

109 mkdocstrings plugin instance. 

110 """ 

111 return helpers.plugin(session_mkdocs_conf) 

112 

113 

114@pytest.fixture(name="session_ext_markdown", scope="session") 

115def fixture_session_ext_markdown(session_mkdocs_conf: MkDocsConfig) -> Markdown: 

116 """Return a Markdown instance with MkdocstringsExtension. 

117 

118 Parameters: 

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

120 

121 Returns: 

122 A Markdown instance. 

123 """ 

124 return helpers.ext_markdown(session_mkdocs_conf) 

125 

126 

127@pytest.fixture(name="session_handler", scope="session") 

128def fixture_session_handler(session_plugin: MkdocstringsPlugin, session_ext_markdown: Markdown) -> PythonHandler: 

129 """Return a handler instance. 

130 

131 Parameters: 

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

133 

134 Returns: 

135 A handler instance. 

136 """ 

137 return helpers.handler(session_plugin, session_ext_markdown)