Changelog

This document lists notable changes and releases for asciidoctest.

0.2.0a6 - 2026-09-16

Added

  • Programmatic API — run_adoc_tests (Issue #20):

  • Introduced asciidoctest.run_adoc_tests(source, *, setup_globs=None, mode="explicit", fail_fast=False) -> TestSuiteResult as the primary entry point for running AsciiDoc tests without requiring pytest.

  • Accepts .adoc files, .py files, directories, types.ModuleType instances, or raw AsciiDoc content strings.

  • Returns a TestSuiteResult TypedDict with total, passed, failed, and failures keys.

  • setup_globs injects variables into the test execution namespace (e.g., setup_globs={"ENGINE": "dag"}).

  • test_docstrings is an alias for extract_and_run_docstring_tests.

  • fail_fast Option for Docstring Testing (Issue #4):

    • extract_and_run_docstring_tests now accepts fail_fast: bool = True.

    • When fail_fast=False, all failures are collected and returned in result["failures"] rather than raising immediately.

  • TestFailureDetail TypedDict captures name, message, lineno, got, and want for each failure.

  • Structured Result TypedDicts:

  • TestSuiteResult and TestFailureDetail are exported from asciidoctest and included in __all__.

  • Integration Test Suite (Issue #21):

  • Added tests/integration/test_golem_integration.py exercising the programmatic API end-to-end: module docstring testing, setup_globs injection, fail_fast behavior, module collision isolation, failure line number reporting, and tolerant include handling.

  • Build Modernization:

  • Migrated build backend from setuptools.build_meta to hatchling.build.

  • Added Hatch environment scripts: test, cov-report, lint, format, typecheck, docs-build, docs-serve.

  • Configured [tool.hatch.envs.default] with installer = "uv" for fast installs.

  • Added committed pylock.toml lockfile.

  • CI Matrix Expansion:

    • Extended .github/workflows/ci.yml Python version matrix to ["3.10", "3.11", "3.12", "3.13", "3.14"].

    • Added astral-sh/setup-uv@v3 step for uv caching and installation.

Fixed

  • Module Name Collision in pytest Docstring Collector (Issue #8):

    • DocstringTestItem.runtest() in pytest_plugin.py now derives a unique module name using the file’s path relative to rootdir (prefixed _asciidoctest_), preventing same-named files in different subdirectories from colliding in sys.modules.

    • Applied the same fix to _run_tests_on_py_file() in docstring_extractor.py.

    • The dynamically loaded module is removed from sys.modules after execution (via finally block) to preserve test isolation.

Changed

  • Strict Type Checking: [tool.mypy] is configured with strict = true; all modules pass mypy --strict with zero errors.

  • Coverage Gate: [tool.coverage.report] is configured with fail_under = 97; coverage gate is enforced automatically.

  • Upgraded Dependencies:

  • Upgraded asciidoctrine dependency constraint to >=0.2.0a8.

  • Upgraded asciidocstring dependency constraint to >=0.1.0a11.

  • Updated requires-python = ">=3.10".

  • Updated __all__ in asciidoctest/__init__.py: Exports AsciiDocTestFailure, DocFileSuite, DocTestSuite, run_adoc_tests, extract_and_run_docstring_tests, test_docstrings, TestSuiteResult, TestFailureDetail.

0.2.0a5 - 2026-09-05

Added

  • Granular Pytest Node IDs per Section or Block (Issue #12):

  • Added --asciidoctest-split-sections command-line flag and asciidoctest_split_sections ini configuration option to split AsciiDoc document test collection into individual pytest items per test block.

  • Test items are named after their section title and 1-based block index (<Section_Title>::asciidoctest_block_<N>), enabling targeted execution and filtering via pytest -k <Pattern>.

  • Updated AsciiDocItem.reportinfo() to report exact 1-based source line numbers for individual test blocks when section splitting is enabled.

  • Pyodide & WebAssembly Testing Guidance:

    • Added architectural documentation in README.adoc and docs/getting-started.adoc for testing frontend and browser-focused libraries in Pyodide/WebAssembly.

  • Documented testing strategies: in-Wasm direct execution via micropip (DocFileSuite, DocTestSuite, extract_and_run_docstring_tests), host pytest-pyodide driver bridges, and dual-target mock workflows.

  • Detailed state lifecycle management in WebAssembly, including sequential persistent state (shared), parallel named scopes (shared="<name>"), boundary resets (reset and == Section), and the distinction between Python namespace cleanup and host browser DOM teardown.

Fixed

  • Pytest Runner Configuration Warnings:

    • Removed unrecognized asyncio_default_fixture_loop_scope setting from pyproject.toml and test fixtures, eliminating PytestConfigWarning during test execution.

Changed

  • Upgraded Dependencies:

    • Upgraded asciidoctrine dependency constraint to >=0.2.0a7 (incorporating support for hanging list item continuations, backslash-escaped delimiters, and dot-ordered list items preceding source blocks).

  • Upgraded asciidocstring dependency constraint to >=0.1.0a9.

  • Upstream Compatibility & Test Coverage:

  • Added upstream compatibility regression suite in tests/test_asciidoctrine_020a7_compat.py covering list continuations, escaped delimiters/macros, and ordered lists.

  • Added unit and integration tests for section splitting in tests/test_section_node_ids.py and tests/test_plugin_coverage.py, expanding the test suite to 121 passing tests with zero warnings.

0.2.0a4 - 2026-08-31

Added

  • Direct Python Source Code & Docstring Doctest Extraction (Issue #3):

  • Full AST Node Traversal: Static AST docstring extraction via _DocstringVisitor now extracts docstrings from functions, async functions, classes, nested classes, and nested methods using hierarchical dot-notation naming (e.g., OuterClass.InnerClass.method_docstring).

  • Multi-target Execution Support: asciidoctest.extract_and_run_docstring_tests now seamlessly accepts Python source file paths (str or pathlib.Path), module/package directories (recursively discovering .py files), imported module name strings, or loaded types.ModuleType instances.

  • Per-symbol Scope Isolation: Each symbol’s docstring doctests execute in an independent copy of module globals (dict(module.__dict__)), preventing state mutation and leakage between separate functions or methods.

  • Contextual Failure Traces: Failure traces format with [filepath:symbol_name] identifying the exact location of doctest assertion failures.

Fixed

  • Pytest Custom Item Fixture Compatibility:

    • Initialized _fixtureinfo on custom pytest test items (AsciiDocItem and DocstringTestItem), eliminating AttributeError: 'AsciiDocItem' object has no attribute '_fixtureinfo' when running alongside third-party plugins like pytest-pyodide.

Changed

  • Upgraded Dependencies:

  • Upgraded asciidoctrine dependency requirement to >=0.2.0a5 (table cols DSL, block title attachments 119, attached inline macros 120, Lark parser memoization).

  • Upgraded asciidocstring dependency requirement to >=0.1.0a8 (AsciiDoc docstrings style guide, semantic docstring model compatibility).

  • Added lark>=1.3.1 dependency constraint.

  • Test Suite & Coverage Quality:

    • Increased unit test coverage across __init__.py, pytest_plugin.py, and unittest_integration.py (achieving 100% statement coverage on unittest_integration.py and 109 passing tests).

    • Configured asyncio_default_fixture_loop_scope = "function" to eliminate test runner deprecation warnings.

0.2.0a3 - 2026-08-22

Added

  • Section Scoping, Named Contexts & Reset Markers (Issue #2):

    • AST Section Boundary Scoping: Automatic shared state reset when traversing across top-level section boundaries (==), isolating independent document chapters, classes, and topics while preserving sequential state flow within each section.

  • Named Context Scopes: Introduced [source,python,shared="<name>"] support to allow multiple independent, persistent state timelines within the same document.

  • Explicit Reset Markers: Added [source,python,reset] and [source,python,reset,shared] directives (also accepting shared="none" or shared="reset") to clear all accumulated shared state and named contexts on demand.

  • Direct Doctest Extraction API (Issue #3):

    • Added asciidoctest.extract_and_run_docstring_tests(source_path_or_module, mode="explicit") for programmatic discovery and execution of doctests from Python source files, package directories, or imported module objects.

    • Added find_docstrings_in_py_file in asciidoctest.parser for AST-based static docstring discovery without running module code during parsing.

  • PEP 561 Type Information: Added asciidoctest/py.typed marker (PEP 561) so downstream projects using mypy or pyright receive full type information from asciidoctest.

  • Top-level AsciiDocTestFailure export: AsciiDocTestFailure is now re-exported from asciidoctest.__init__ and included in __all__, enabling from asciidoctest import AsciiDocTestFailure without submodule access.

  • Contextual failure messages: AsciiDocTestFailure raised during directory or module docstring extraction now includes [filepath:symbol] context so the failing file and function are immediately identifiable.

  • State model quick-reference table: Added a comprehensive marker/namespace cheatsheet table to docs/getting-started.adoc and docs/state-models.adoc.

Fixed

  • Tolerant Illustrative Includes (Issue #1):

    • Disabled include preprocessing by default (preprocess_directives=False) during AsciiDoc doctest parsing, allowing illustrative or documentation-only include::...[] macros without requiring target files to exist on disk.

  • Pytest pre-filter spacing tolerance (DX): Updated the .py file pre-filter in pytest_plugin.py from a plain string check ("[source,python") to a regex (re.search(r"\[source\s*,\s*python", content)), correctly handling AsciiDoc block headers with spaces after commas (e.g. [source, python, test]).

  • shared="none" and shared="reset" not triggering reset (Issue #10): block_get_shared_context now correctly treats shared="none" and shared="reset" (case-insensitive) as falsy values that do not create named contexts, consistent with the CHANGELOG documentation.

Changed

  • Upgraded Dependencies:

    • Upgraded asciidoctrine dependency requirement to >=0.2.0a2.

  • Upgraded asciidocstring dependency requirement to >=0.1.0a7.

  • mypy --strict compliance: Resolved all 32 strict typing violations across parser.py, runner.py, unittest_integration.py, and pytest_plugin.py. mypy --strict asciidoctest now reports zero errors.

0.2.0a2 - 2026-07-31

Added

  • Security Policy & Documentation:

    • Added SECURITY.adoc and dedicated Sphinx security.adoc page outlining execution safety context, supported version matrix, and responsible disclosure workflow.

Changed

  • Upgraded Dependencies:

    • Upgraded asciidoctrine dependency constraint to >=0.1.0a11 to leverage configurable custom URI schemes, bare URL and email autolink features, list continuations, and Post-AST syntax checks.

    • Upgraded asciidocstring dependency constraint to >=0.1.0a6.

  • Documentation & Styling:

    • Published multi-page HTML documentation site using sphinx_rtd_theme styled with AsciiDoctrine’s forest-green dark theme overrides.

0.2.0a1 - 2026-07-17

Added

  • Unified Symmetric Namespace and State Model:

  • Established identical, symmetric execution and namespace isolation rules for both interactive REPL and non-interactive script blocks.

  • Isolated & Ephemeral (test): Run in a clean copy of the initial namespace, keeping them fully isolated from subsequent side-effects by default.

  • Persistent & Stateful (shared): Run in the sequential shared globals (like a continuous notebook), allowing variables to persist top-to-bottom across both script and interactive blocks.

  • Ephemeral Copy (shared, test): Run in a temporary snapshot copy of the shared globals, enabling access to preceding variables while safely discarding local mutations when the block ends.

  • No Marker: Treated as a static listing and skipped by default.

  • Intelligent eager Mode Safety Guard:

    • In eager mode, unmarked listings are only run as isolated test blocks if the document contains zero explicit markers. If any block in the file has explicit attributes or roles, eager mode is bypassed/disabled for that file.

Refactored

  • Centralized Block Marker Inspection:

  • Refactored internal parsing to centralize block marker extraction (block_has_test_marker and block_has_shared_marker), eliminating duplication across the parser and runner.

  • Verifiable Documentation Terminology:

    • Re-framed the project documentation and README.adoc around verifiable and stateful narrative documentation rather than Literate Programming.

0.1.0a4 - 2026-07-16

Added

  • Traverser Safety Guard: Introduced SafeTestBlockExtractorVisitor to safely bypass raw strings or child objects without a .name attribute during AST traversal, preventing crashes on complex unparsed text blocks.

  • Pytest Discovery Constraints: Configured testpaths under [tool.pytest.ini_options] in pyproject.toml to restrict search patterns to tests/ and README.adoc, preventing slow recursive runs over external directories.

Changed

  • Upgraded dependencies:

    • Bumped asciidocstring requirement to >=0.1.0a4 to support the latest safe parsing mode releases.

0.1.0a3 - 2026-07-14

Changed

  • Upgraded dependencies:

    • Upgraded asciidoctrine to >=0.1.0a8.

    • Upgraded asciidocstring to >=0.1.0a3.

  • Documentation Casing: Aligned all references to asciidoctest / AsciiDoctest to follow standard casing style guide rules (using Title Case AsciiDoctest for prose, and lowercase backticks asciidoctest for code).

0.1.0a2 - 2026-07-13

Added

  • Optional test dependencies group: Added a [project.optional-dependencies] section to pyproject.toml with a test target including pytest and pytest-cov.

  • Advanced test coverage validation: Added robust unit and integration tests covering parser exceptions, doctest unexpected exceptions, and class-level unittest TestCase helpers (achieving 97% code coverage).

  • Footnote macros compatibility verification: Added a validation suite (tests/test_footnotes.py) confirming compatibility with the newly introduced anonymous and named footnotes in the parsing pipeline.

Changed

  • Upgraded dependencies:

  • Bumped asciidoctrine version requirement to >=0.1.0a7 to leverage parser newline normalization and native footnotes.

  • Changed asciidocstring version constraint to >=0.1.0a2.

Fixed

  • Removed trailing newline workaround: Cleaned up manual trailing-newline appending in parser.py, as standard line termination issues have been natively resolved in the upgraded upstream parser.

0.1.0a1 - 2026-07-11

Added

  • Initial Release: Released asciidoctest as an alpha utility.

  • Core sequential runner: Designed a sequential execution engine supporting variable-state propagation and detailed line mappings.

  • Pytest integration: Added file collection hooks and detailed repr-failure reporting.

  • Unittest integration: Added standard library TestSuite compatibility wrappers (DocFileSuite and DocTestSuite).

< Security Policy | Index >