Skip to content

Installed-user verification pilot and generated documentation

Project home · Executable scenarios · Latest CI runs and documentation artifacts

Five examples document observable behavior: root help, missing-plugin recovery, installed reporter discovery, validating the pinned reporter's example bundle, and useful failure for a missing manifest. pytest-bdd executes the Gherkin scenarios through tests/features/test_journeys.py. Each command starts a fresh container from the existing root-only or reporting image, installed from packaged wheels. Networking is disabled; only fixture data is mounted, never application source. The reporting image installs the explicit release in reporter-release.txt. This pilot does not exercise the interactive user's installation network journey.

Run and browse

On a prepared Linux Docker host with Task and uv:

task setup
task verify
task package
task images
task test:features
task features:results
task docs

Preview artifacts/docs/html/ using the HTTP instructions below. The manual has navigation and search, command reference generated by Zensical's mkdocs-click Markdown extension from the candidate root and reporter wheels' actual Click objects, and terminal help captured from both installed images. The reference imports those wheels and their runtime dependencies from an isolated package directory, not src/. Repository Markdown guides are staged from their canonical files with local links rewritten to rendered pages; they are not maintained as duplicate prose. Tool versions are pinned in uv.lock. See the renderer decision.

To exercise actual browser behavior as well as generated links and command sections:

task docs:test:setup
uv run --locked --no-sync --group docs-test playwright install --with-deps chromium
task test:docs

The browser install is explicit tooling setup. CI runs these checks on Linux amd64; mobile viewport emulation is not testing on an actual Android device. Optional DOCS_BROWSER_EXECUTABLE=/path/to/chromium selects an existing compatible browser.

The scenarios page is generated from the same parsed feature file used by the BDD tests, with automated test identities and actual JUnit outcomes. The JSON and Markdown map lives in artifacts/features/. Missing cases are NOT_RUN, skipped cases are SKIPPED, and failures/errors remain failures. No product-wide feature coverage percentage is inferred from this small set. Build docs after running tests for current evidence; local XML describes the last invocation, not a new run. Malformed, duplicate and unexpected results fail generation.

Visible CI evidence

The existing native package build job runs the scenarios on amd64 and arm64 after building its candidate artifacts. Existing regression jobs remain. Its existing JUnit publisher ingests artifacts/feature-tests.xml alongside the unit and installed and documentation-browser reports into expanded checks and job summaries with named cases and failure details. Raw JUnit retains captured commands, exits and output. A second summary table maps each scenario to its test and status. Test failures remain failing job steps; documentation/report generation is attempted after failure and cannot turn them green.

documentation-VERSION-ARCHITECTURE contains docs/html/index.html and the feature JSON/Markdown map. Download and extract the entire tree, then preview it over HTTP as described below. CI links the artifact in the run summary; retention is 14 days, matching test evidence. The downloadable artifact remains available independently of the hosted manual. Fork token limitations remain those documented in development. See Pages publication and live verification.

Preview a downloaded manual

Extract the entire artifact, keeping docs/html/assets/ and all HTML files together. Opening index.html directly is not supported by every browser or file provider. In particular, Android content:// document URLs may prevent sibling pages, styles and scripts from resolving, leaving unstyled text or broken navigation/search even when the full artifact is present. Opening commands.html directly can help diagnose this; it does not establish that navigation or search works. The reported Android behavior has not been confirmed fixed.

Prefer the verified hosted manual once deployed (see Pages publication). For a local preview on a computer with Python 3 and a browser, run this from the extracted artifact directory:

python3 -m http.server 8000 --bind 127.0.0.1 --directory docs/html

Then visit http://127.0.0.1:8000/ in a browser on that same computer. For a local repository build, use --directory artifacts/docs/html instead. Keep the server bound to loopback; stop it with Ctrl-C. This is a local preview, not a hosting setup or a promise of Android file-provider compatibility. Verify navigation, styles and interactive search in the browser; an HTTP response alone is not that verification.

The former generated-help.html address redirects to terminal-help.html with an ordinary fallback link. Published command and option bookmarks remain aliases to the corresponding current command section; options are rendered together in that section. The old commands.html#installed-terminal-help bookmark offers a link to the terminal-help page. search.html?q=... remains a usable search entry page with the normal Search control; old query terms must be entered again. These compatibility pages do not change command behavior or the reporter pin.

Independent review and limits

Review the changed journeys and adjacent behavior using the built candidate assets in a fresh environment. Record one comment per manually exercised scenario, with commands, expected/actual output, artifact identity and a collapsed transcript. Do not call automated runs independent manual verification. No merge is requested until the separately arranged review is complete.

For a bounded repeat of these checks, download the package artifact from the same CI run, restore it under dist/, load image-ARCHITECTURE.tar and reporting-image-ARCHITECTURE.tar with docker load -i, and fetch the pinned example fixtures with uv run --locked --no-sync python tools/fetch_reporter.py. Then run task test:features, task features:results and task docs. Keep the root wheel, images and dist/wheels/ from the same run. Each JUnit transcript records the image name; generated help also records image content IDs.

Existing unit/distribution suites separately test network installation, versions, completion, grading/rendering, package metadata and uninstall independence. This pilot neither replaces those suites nor claims exhaustive errors, Windows/macOS, manual review, or historical feature trends. A local Linux amd64 pass does not establish arm64 or the hosted publisher's rendering. Verify both passing and failing rendered results in CI before claiming publication adoption complete.