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

Or specify the flag on the command line:

pytest --asciidoctest-mode=eager

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")

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.