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:

Entry point	Purpose
`dhis2w_browser.logged_in_page(url, username, password)`	Async context manager yielding a `(BrowserContext, Page)` tuple logged into DHIS2 via the React login form.
`dhis2w_browser.session_from_cookie(url, jsessionid)`	Fast-path variant — inject a pre-minted `JSESSIONID` instead of driving the login form.
`dhis2w_browser.create_pat(url, username, password, options=...)`	Mint a Personal Access Token V2 (`POST /api/apiToken`) through an authenticated browser session. Returns the `d2p_...` token string. DHIS2 only returns the token value once — store it immediately.
`dhis2w_browser.drive_oauth2_login(profile_name, *, username, password)`	Run `d2w profile login <name> --no-browser` end-to-end — spawns the CLI, reads the authorize URL from its stderr, and drives Chromium through the DHIS2 React login + Spring AS consent screen + loopback redirect. Returns an `OAuth2LoginResult` model.
`dhis2w_browser.drive_login_form(auth_url, *, username, password)`	Lower-level companion to `drive_oauth2_login` — navigates Chromium to an already-built authorize URL, fills the login form + consent screen, waits for the loopback redirect. For wiring Playwright into an in-process `OAuth2Auth.redirect_capturer`.
`dhis2w_browser.capture_dashboard(...)` / `capture_visualization(...)` / `capture_map(...)`	Render a DHIS2 dashboard / chart / map as a PNG via the respective web app. Banner + background-trim helpers available for report-friendly output.

Headless vs headful

Headless by default. Two ways to flip to visible:

Env var: DHIS2_HEADFUL=1 (or true/yes/on) — applies to every Playwright entry point in this package.
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.

Metadata

Release files for dhis2w-browser 1.30.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dhis2w-browser 1.30.1
File	Size	Uploaded
dhis2w_browser-1.30.1.tar.gz	36.2 kB	Sep 29, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for dhis2w-browser 1.30.1
File	Interpreter	ABI	Platform	Reset
dhis2w_browser-1.30.1-py3-none-any.whl 48.4 kB Sep 29, 2026	Python 3	none	any	Details

Total release size: 84.6 kB

Release files / dhis2w_browser-1.30.1.tar.gz

Download URL	dhis2w_browser-1.30.1.tar.gz
Size	36.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`b76d805555a917ba68a9736fc3786bad47d629720cfb54387527c3aac3eb34a6`
BLAKE2b-256 checksum How to use checksums	`994729f06f8efb501d6114c38a227107b835b8ea5ddfb7cb0d097e686bea95e1`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/winterop-com/dhis2w-browser
Publishing commit: github.com/winterop-com/dhis2w-browser/tree/6550f36823ce7eb238586e79d91aceff3b9d8642

Workflow

Publishing configuration: github.com/winterop-com/dhis2w-browser/blob/6550f36823ce7eb238586e79d91aceff3b9d8642/.github/workflows/pypi-publish.yml
Publishing logs: github.com/winterop-com/dhis2w-browser/actions/runs/36615986917/attempts/1

Artifact

Subject: dhis2w_browser-1.30.1.tar.gz
SHA-256 checksum: b76d805555a917ba68a9736fc3786bad47d629720cfb54387527c3aac3eb34a6 Verifying attestations

Release files / dhis2w_browser-1.30.1-py3-none-any.whl

Download URL	dhis2w_browser-1.30.1-py3-none-any.whl
Size	48.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`720f3e66ab1435f734be6650d95bb656d6ce9f498285146061f14b11a6625094`
BLAKE2b-256 checksum How to use checksums	`15034e8b2c4f5c5a7121961431526adde65470578544fe709a79bcf42f1d4a9d`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/winterop-com/dhis2w-browser
Publishing commit: github.com/winterop-com/dhis2w-browser/tree/6550f36823ce7eb238586e79d91aceff3b9d8642

Workflow

Publishing configuration: github.com/winterop-com/dhis2w-browser/blob/6550f36823ce7eb238586e79d91aceff3b9d8642/.github/workflows/pypi-publish.yml
Publishing logs: github.com/winterop-com/dhis2w-browser/actions/runs/36615986917/attempts/1

Artifact

Subject: dhis2w_browser-1.30.1-py3-none-any.whl
SHA-256 checksum: 720f3e66ab1435f734be6650d95bb656d6ce9f498285146061f14b11a6625094 Verifying attestations