AsciiDoctest Documentation

Welcome to the official documentation for AsciiDoctest — the executable documentation runner and narrative testing tool for AsciiDoc (.adoc) files and Python docstrings.

What is AsciiDoctest?

AsciiDoctest parses, collects, and verifies Python code blocks directly from AsciiDoc (.adoc) documents and Python docstrings. It uses AST-based structural parsing powered by asciidoctrine and asciidocstring to ensure that your tutorials, user guides, and docstrings remain continuously accurate and verified against your codebase.

Why Doctests?

Traditional software testing separates test code from documentation, which can lead to documentation drift. As APIs evolve, code examples in tutorials and docstrings can become outdated.

Executable doctests address this by turning documentation into testable examples:

  • Prevent Documentation Drift — Code examples in your guides and docstrings are executed and validated during testing.

  • Executable Narratives — Write guides where documentation and test cases share a single source of truth.

  • Verify Examples — Ensure that tutorial steps and examples in your documentation work as written.

Why AsciiDoc?

AsciiDoc provides structured document architecture with readable syntax:

  • Clear Syntax — AsciiDoc offers structured document capabilities with concise markup ([source,python]).

  • Rich Structure — AsciiDoc natively supports block attributes, callouts, tables, cross-references, and modular document includes (include::[]).

  • Block Attributes & Roles — AsciiDoc provides attribute syntax (e.g., [source,python,shared] or [source,python,test]) to attach execution metadata directly to code blocks.

Why AsciiDoctest?

Standard doctest extraction based on regular expressions can struggle with complex markup, nested blocks, callouts, or custom block attributes.

AsciiDoctest brings AST-level testing to AsciiDoc:

  • AST-Based Parsing — Uses asciidoctrine and asciidocstring to parse document syntax trees, preserving source coordinates, block boundaries, and nested elements.

  • Execution State Models — Provides consistent state models (test for isolated execution, shared for stateful sequential guides, and shared, test for ephemeral snapshots) across interactive REPL (>>>) and script blocks.

  • Test Runner Integration — Integrates with pytest through automated test discovery, with standard library unittest suite adapters (DocFileSuite, DocTestSuite), and programmatic execution via run_adoc_tests.

Key Features

  • AST-Based Docstring & Document Parsing — Extracts test blocks using document syntax trees.

  • Flexible Execution Modes:

    • explicit (default): Only executes blocks with test, shared, or reset markers.

  • eager: Automatically tests all [source,python] listings as isolated blocks when no explicit markers exist in the document.

  • Test Runner Support — Direct integration with pytest, unittest, and programmatic execution via run_adoc_tests.

Documentation Sections

  • Getting Started — Package installation, pytest configuration, and unittest integration.

  • Executable State Models — Isolated, persistent shared, and ephemeral copy execution namespaces.

  • Developer Handbook — Architecture overview, test suite design, and development commands.

  • Security Policy — Supported versions, execution safety context, and vulnerability reporting.

  • Changelog — Release notes and version history.

Next: Getting Started >