push

Author: aaazzam

README.md

@@ -66,6 +66,9 @@ Fence blocks (` ``` `) starting with the `python`, `python3` or `py` language de
 * Python (.py) files, within docstrings of classes and functions
 * `.md`, `.mdx` and `.svx` files
 
+Other code fence languages are ignored unless you explicitly map them to a
+custom runner.
+
 ## Skipping tests
 
 To exclude a Python code fence from testing, add a `notest` info string to the
@@ -178,6 +181,45 @@ With `retry:3`, the test runs up to 4 times total (1 initial attempt + 3 retries
 - All exceptions trigger retries (AssertionError, RuntimeError, etc.)
 - When using a continuation block, only the failing block retries
 
+### Custom runners and languages
+
+Python code fences use the built-in runner by default. Other languages can be
+collected by registering a custom runner and returning its name from the
+`pytest_markdown_docs_runner_name_for_language` hook:
+
+```python
+# conftest.py
+import pytest_markdown_docs
+
+
+@pytest_markdown_docs.register_runner()
+class TextRunner(pytest_markdown_docs.DefaultRunner):
+    def runtest(self, test, args):
+        assert "expected output" in test.source
+
+
+def pytest_markdown_docs_runner_name_for_language(language):
+    if language == "text":
+        return "TextRunner"
+```
+
+With this conftest, `text` fences are collected as tests:
+
+````markdown
+```text
+expected output
+```
+````
+
+You can also select a runner for a single fence by adding `runner:<name>` to the
+info string:
+
+````markdown
+```text runner:TextRunner
+expected output
+```
+````
+
 ### Compatibility with Material for MkDocs
 
 Material for Mkdocs is not compatible with the default syntax.
@@ -209,6 +251,7 @@ The following options can be specified using MDX comments:
 * fixture:<name>: Apply named pytest fixtures to the code block.
 * continuation: Continue from the previous code block, allowing you to carry over state.
 * retry:<count>: Automatically retry the test up to the specified number of times if it fails.
+* runner:<name>: Run the code block with a registered custom runner.
 
 This approach allows you to add metadata to the code block without modifying the code fence itself, making it particularly useful in MDX environments.
 

src/pytest_markdown_docs/__init__.py

@@ -0,0 +1,3 @@
+from pytest_markdown_docs._runners import DefaultRunner, register_runner
+
+__all__ = ["DefaultRunner", "register_runner"]

src/pytest_markdown_docs/_runners.py

@@ -10,7 +10,7 @@
 from pytest_markdown_docs.definitions import FenceTestDefinition
 
 _default_runner: typing.Optional["_Runner"] = None
-_registered_runners = {}
+_registered_runners: typing.Dict[str, "_Runner"] = {}
 
 
 class _Runner(metaclass=abc.ABCMeta):

src/pytest_markdown_docs/hooks.py

@@ -9,6 +9,13 @@ def pytest_markdown_docs_globals() -> typing.Dict[str, typing.Any]:
     return {}
 
 
+@pytest.hookspec(firstresult=True)
+def pytest_markdown_docs_runner_name_for_language(
+    language: str,
+) -> typing.Optional[str]:
+    """Return a registered runner name for a code fence language."""
+
+
 @pytest.hookspec(firstresult=True)
 def pytest_markdown_docs_markdown_it() -> "MarkdownIt":
     """Configure a custom markdown_it.MarkdownIt parser."""

src/pytest_markdown_docs/plugin.py

@@ -29,6 +29,7 @@
 logger = logging.getLogger("pytest-markdown-docs")
 
 MARKER_NAME = "markdown-docs"
+_PYTHON_FENCE_LANGUAGES = frozenset(("py", "python", "python3"))
 
 
 class FenceSyntax(Enum):
@@ -60,6 +61,15 @@ def _get_asyncio_runner(fixture_request):
         return None
 
 
+def _runner_name_for_language_from_config(config):
+    def runner_name_for_language(language: str) -> typing.Optional[str]:
+        return config.hook.pytest_markdown_docs_runner_name_for_language(
+            language=language
+        )
+
+    return runner_name_for_language
+
+
 class MarkdownInlinePythonItem(pytest.Item):
     def __init__(
         self,
@@ -173,6 +183,9 @@ def extract_fence_tests(
     source_path: pathlib.Path,
     markdown_type: str = "md",
     fence_syntax: FenceSyntax = FenceSyntax.default,
+    runner_name_for_language: typing.Optional[
+        typing.Callable[[str], typing.Optional[str]]
+    ] = None,
 ) -> typing.Generator[FenceTestDefinition, None, None]:
     tokens = markdown_it_parser.parse(markdown_string)
 
@@ -203,27 +216,31 @@ def extract_fence_tests(
             if i >= 2 and is_mdx_comment(tokens[i - 2]):
                 code_options |= extract_options_from_mdx_comment(tokens[i - 2].content)
 
-        if lang in ("py", "python", "python3") and "notest" not in code_options:
-            start_line = (
-                start_line_offset + block.map[0] + 1
-            )  # actual code starts on +1 from the "info" line
-            if "continuation" not in code_options:
-                prev = ""
-
-            add_blank_lines = start_line - prev.count("\n")
-            code_block = prev + ("\n" * add_blank_lines) + block.content
-
-            fixture_names = get_prefixed_strings(code_options, "fixture:")
+        if lang is not None and "notest" not in code_options:
             runner_names = get_prefixed_strings(code_options, "runner:")
             if len(runner_names) == 0:
                 runner_name = None
+                if runner_name_for_language is not None:
+                    runner_name = runner_name_for_language(lang)
+                if runner_name is None and lang not in _PYTHON_FENCE_LANGUAGES:
+                    continue
             elif len(runner_names) > 1:
                 raise Exception(
                     f"Multiple runners are not supported, use a single one instead: {runner_names}"
                 )
             else:
                 runner_name = runner_names[0]
 
+            start_line = (
+                start_line_offset + block.map[0] + 1
+            )  # actual code starts on +1 from the "info" line
+            if "continuation" not in code_options:
+                prev = ""
+
+            add_blank_lines = start_line - prev.count("\n")
+            code_block = prev + ("\n" * add_blank_lines) + block.content
+
+            fixture_names = get_prefixed_strings(code_options, "fixture:")
             retry_counts = get_prefixed_strings(code_options, "retry:")
             if len(retry_counts) == 0:
                 max_retries = 0
@@ -389,6 +406,9 @@ def find_object_tests_recursive(
                         docstring_offset,
                         source_path=self.path,
                         fence_syntax=fence_syntax,
+                        runner_name_for_language=_runner_name_for_language_from_config(
+                            self.config
+                        ),
                     )
                 ):
                     found_test = ObjectTestDefinition(i, obj_name, fence_test)
@@ -420,6 +440,9 @@ def collect(self):
                 start_line_offset=0,
                 markdown_type=self.path.suffix.replace(".", ""),
                 fence_syntax=fence_syntax,
+                runner_name_for_language=_runner_name_for_language_from_config(
+                    self.config
+                ),
             )
         ):
             yield MarkdownInlinePythonItem.from_parent(