dhis2w-browser

Playwright-based helpers for DHIS2 UI automation. Separate from dhis2w-client so API-only callers never pull in Chromium.

Install

uv add 'dhis2w-cli[browser]'            # pulls dhis2w-browser alongside the main CLI
playwright install chromium           # one-off; pulls the actual browser driver

Library-only consumers (no CLI) can install 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:

  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.

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.3.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for mortenoh from gravatar.com mortenoh

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: Morten Hansen

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

LicenseRef-Proprietary
View SPDX License List

Requires

Python >=3.13

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dhis2w_browser-1.0.0.tar.gz (16.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

dhis2w_browser-1.0.0-py3-none-any.whl (22.8 kB view details)

Uploaded Python 3

File details

Details for the file dhis2w_browser-1.0.0.tar.gz.

File metadata

  • Download URL: dhis2w_browser-1.0.0.tar.gz
  • Upload date:
  • Size: 16.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for dhis2w_browser-1.0.0.tar.gz
Algorithm Hash digest
SHA256 949ce8abecc9a610cd5156dc213711339f6947325795e2562d7933bb9223e2bb
MD5 8d3a07c71d5f07bf08f70821a3a27d85
BLAKE2b-256 4e8f73dd47f83d672573c75d72289a332236060dca37ae7ddb2f512459a2d171

See more details on using hashes here.

Provenance

The following attestation bundles were made for dhis2w_browser-1.0.0.tar.gz:

Publisher: pypi-publish.yml on winterop-com/dhis2w-utils

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file dhis2w_browser-1.0.0-py3-none-any.whl.

File metadata

  • Download URL: dhis2w_browser-1.0.0-py3-none-any.whl
  • Upload date:
  • Size: 22.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for dhis2w_browser-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 9d4ad3dd9803835aff1c3505e34b225064d8891e4cfd31837268138fc68d95cb
MD5 0b03d598165fdf1d649bc94c0e39aa38
BLAKE2b-256 dd363b3ccd77ce88f0a96df2258fabc0a93cbfef6fce4b08932c9a9111254014

See more details on using hashes here.

Provenance

The following attestation bundles were made for dhis2w_browser-1.0.0-py3-none-any.whl:

Publisher: pypi-publish.yml on winterop-com/dhis2w-utils

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page