dhis2w-browser

A dhis2w plugin pack for Playwright-driven DHIS2 UI automation: dashboard, map and visualization screenshots, a logged-in browser session from any profile, and Personal Access Token minting. It lives in its own repository so that installing dhis2w-client or dhis2w-cli never pulls in Chromium.

Documentation: https://winterop-com.github.io/dhis2w-browser/

Install

uv tool install 'dhis2w-cli[browser]'   # the d2w CLI with this pack
playwright install chromium             # one-off; the browser the flows drive

Library-only consumers (no CLI) can uv add dhis2w-browser on its own.

Surface

The CLI lives on the main d2w entry point as a plugin; there's no separate dhis2w-browser binary. Workflows mount under d2w browser <subcommand>:

d2w browser pat --url http://localhost:8080 --username admin --password district
d2w browser dashboard screenshot --output-dir /tmp/out --only <uid>
d2w browser viz screenshot --output-dir /tmp/out --only <uid>
d2w browser map screenshot --output-dir /tmp/out --only <uid>

Library callers import from dhis2w_browser directly:

Headless vs headful

Headless by default. Two ways to flip to visible:

1. Env var: DHIS2_HEADFUL=1 (or true/yes/on) — applies to every Playwright entry point in this package.
2. Explicit kwarg: logged_in_page(..., headless=False) — overrides env.

The d2w browser pat CLI command defaults to headful (--headful) so first-time users can watch the login; pass --headless to flip.

Why: automation wants headless for speed; humans debugging a flow want to see it. One env var covers every caller (CLI, library, tests) uniformly. See docs/decisions.md 2026-04-17.

Example

import asyncio
from dhis2w_browser import PatOptions, create_pat


async def main() -> None:
    token = await create_pat(
        "http://localhost:8080",
        "admin",
        "district",
        options=PatOptions(
            name="automation-bot",
            expires_in_days=90,
            allowed_methods=["GET", "POST"],
        ),
    )
    print(token)  # d2p_...


asyncio.run(main())

Architecture

See docs/architecture/browser.md for the longer write-up: why PAT creation has to go through a browser (DHIS2 gates /api/apiToken behind a session cookie), how logged_in_page drives the React login form, and what's on the roadmap.

Development

make install      # uv sync --all-groups
make lint         # ruff, mypy, pyright
make test         # the suite, without the live-stack Playwright tests
make test-slow    # the live-stack tests: a running DHIS2 and `playwright install chromium`
make docs         # the documentation site, strictly

The pack releases the same version as the dhis2w host; see CLAUDE.md.