Getting Started

This guide covers package installation, test discovery configuration, and integration with test runners.

Installation

Install asciidoctest via pip:

pip install asciidoctest

To install with development and documentation dependencies:

pip install -e ".[test,docs]"

Pytest Integration

asciidoctest registers automatically as a pytest plugin. Running pytest discovers .adoc files and docstrings in your workspace.

pytest

Pytest Configuration

Configure collection options in pyproject.toml or pytest.ini:

[pytest]
asciidoctest_mode = eager
asciidoctest_split_sections = true

Or specify flags on the command line:

pytest --asciidoctest-mode=eager --asciidoctest-split-sections

The --asciidoctest-split-sections option splits document test collection into individual pytest items per test block, formatted as <Section_Title>::asciidoctest_block_<N>, allowing targeted test selection with pytest -k <Pattern>.

Unittest Integration

To use asciidoctest with standard library unittest, wrap files or modules using DocFileSuite or DocTestSuite:

import unittest
from asciidoctest import DocFileSuite

def suite():
    return DocFileSuite("README.adoc")

if __name__ == "__main__":
    unittest.main(defaultTest="suite")

Testing in Pyodide & WebAssembly

AsciiDoctest is pure Python and compatible with Pyodide environments.

Coexistence with `pytest-pyodide`

AsciiDoctest initializes _fixtureinfo on its test items (AsciiDocItem and DocstringTestItem), allowing it to run alongside pytest-pyodide.

Strategies for Pyodide Frontend Libraries

In-Wasm Direct Test Runners: Install asciidoctest into Pyodide via micropip and run tests directly in the Pyodide WebAssembly environment using DocFileSuite, DocTestSuite, or extract_and_run_docstring_tests.
Host Pytest Bridge: In host test suites using pytest-pyodide, extract doctest blocks using asciidoctest.parser.parse_adoc_tests and dispatch them into the browser VM using the driver (e.g., selenium.run_python).
Mocked Host Verification: For fast feedback, mock browser DOM and js globals during local pytest runs, reserving in-browser Pyodide runs for CI integration stages.

State Management (`shared` & `reset`) in Pyodide

Frontend and browser-based Python applications maintain state across operations. AsciiDoctest’s execution markers map to WebAssembly workflows:

Stateful Tutorials ([source,python,shared]): Re-initializing WebAssembly modules, opening IndexedDB handles, or creating canvas contexts on every snippet is inefficient. Using shared allows multi-step browser tutorials where connection objects and state carry sequentially from block to block.
Parallel Named Scopes (shared="<name>"): Isolate distinct browser components or concurrent workers in the same document without collision.
Explicit & Section Boundaries (reset and == Section): When transitioning between tutorial chapters or independent widgets, use [source,python,reset] or top-level section headings to clear Python shared state.
Python State vs. DOM Teardown: Note that while reset and == Section clear Python’s internal namespace dictionaries, host JavaScript artifacts (such as DOM nodes attached to document.body or event listeners added to window) persist in the browser engine unless explicitly removed in Python code or test fixtures.

State Models Quick Reference

Marker / Directive	State Model	Description
(No marker)	Static Listing	Skipped by default; runs in eager fallback if unmarked document.
`test`	Isolated & Ephemeral (`{}`)	Fresh, isolated namespace; mutations discarded after block finishes.
`shared`	Persistent Timeline	Continuous, sequential document-level shared notebook timeline.
`shared, test`	Ephemeral Snapshot Copy	Snapshot copy of shared state; mutations discarded after block finishes.
`shared="name"`	Parallel Named Scope	Parallel named context scope maintaining independent persistent state.
`reset`	Explicit State Reset	Explicit reset of default & named shared states from that block forward.
`== Section`	Automatic Boundary Reset	Automatic section boundary reset of default & named shared states.

< Index | Executable State Models >