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.1.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.1.0-py3-none-any.whl (22.8 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: dhis2w_browser-1.1.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.1.0.tar.gz
Algorithm Hash digest
SHA256 ffe1b501bd96f195e428d8daaee152a4c51bacc341a0b70d2479aae8d781046e
MD5 8a022ce5db67cf64837626186c7822e2
BLAKE2b-256 dbd1dc87cd5426fb93467394e7a6cd95cf3d43f08ae8ccd45dd993151e3b17f3

See more details on using hashes here.

Provenance

The following attestation bundles were made for dhis2w_browser-1.1.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.1.0-py3-none-any.whl.

File metadata

  • Download URL: dhis2w_browser-1.1.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.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 fecb9674688ba0f6a733e8a8d2b6baee8ab76174ea366ddb2c8e57dd9ff5e66d
MD5 26fa216c44b0b9fca72be15495c16cba
BLAKE2b-256 a907e22d3a5cabc108fa2814bb9cc8bd8d5e66f1eb0dbcaccddbb7d4d6db50da

See more details on using hashes here.

Provenance

The following attestation bundles were made for dhis2w_browser-1.1.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