{"id":6828,"library":"pytest-markdown-docs","title":"pytest-markdown-docs","description":"pytest-markdown-docs is a pytest plugin that collects and executes Python code blocks found within Markdown files and Python docstrings as tests. It allows developers to ensure that documentation examples remain correct and up-to-date by integrating them into the standard pytest test suite. The library is currently at version 0.9.2 and follows an active, though not strictly fixed, release cadence.","status":"active","version":"0.9.2","language":"en","source_language":"en","source_url":"https://github.com/modal-labs/pytest-markdown-docs","tags":["pytest","testing","markdown","documentation","doctest","plugin"],"install":[{"cmd":"pip install pytest-markdown-docs","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core testing framework, required for plugin functionality. Requires pytest>=7.0.0.","package":"pytest","optional":false}],"imports":[],"quickstart":{"code":"import pytest\n\n# Save this content as README.md\nreadme_content = \"\"\"\n# My Project\n\nThis is a sample project with a Python code example.\n\n```python\ndef add(a, b):\n    return a + b\n\nassert add(1, 2) == 3\nassert add(-1, 1) == 0\n```\n\nAnother block that should be skipped:\n```python notest\nprint('This code should not run as a test')\nassert False # This would fail if not skipped\n```\n\"\"\"\n\nwith open('README.md', 'w') as f:\n    f.write(readme_content)\n\n# To run this, save the above content as a Python file (e.g., quickstart.py),\n# then execute from your terminal:\n# python -c \"import quickstart\" # Creates README.md\n# pytest --markdown-docs README.md\n#\n# Expected output will show 2 passed tests from the first code block.","lang":"python","description":"To use pytest-markdown-docs, install it and then simply invoke pytest with the `--markdown-docs` flag, pointing it to your Markdown files or Python modules containing docstrings. The plugin will discover and run code fences tagged as `python`, `python3`, or `py`."},"warnings":[{"fix":"Always run `pytest --markdown-docs` to enable markdown/docstring test collection.","message":"The plugin's test collection is only activated when the `--markdown-docs` command-line flag is explicitly passed to pytest. Simply installing the plugin is not enough.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of this limitation when debugging failures in such blocks. Focus on the code content rather than exact line numbers in these specific cases.","message":"Traceback line numbers for code within docstring-inlined snippets or continuation blocks might be inaccurate or confusing compared to standard Python files, as the plugin's internal handling of source locations is 'hacky'.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your assert statements are clear. For complex data structures, consider explicitly printing values before the assertion to aid debugging.","message":"Assertions within Markdown code fences are not rewritten by pytest to provide rich, detailed comparison diffs like they are for standard Python test functions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade `pytest-markdown-docs` to version 0.9.0 or newer to ensure compatibility with `pytest` versions 7.0.0 and above. The current version (0.9.2) explicitly requires `pytest>=7.0.0`.","message":"Older versions of `pytest-markdown-docs` (before 0.9.x) might have had compatibility issues with `pytest > 7.0.0` due to internal API changes in pytest.","severity":"breaking","affected_versions":"<0.9.0"},{"fix":"Use the `notest` info string for examples or snippets that should not be executed as part of your test suite.","message":"To prevent a specific Python code fence from being collected as a test, add `notest` to its info string (e.g., ````python notest````). Otherwise, any `python`, `python3`, or `py` code fence will be treated as a test.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}