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

Uploaded Python 3

File details

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

File metadata

  • Download URL: dhis2w_browser-1.2.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.2.0.tar.gz
Algorithm Hash digest
SHA256 bd64350a3f18654e8e6d5eadb6283b74f500fcb3468b25c67f3b3b88ec5d5c3a
MD5 0bc047f0c640125df1655f67f5a0a24e
BLAKE2b-256 4098833788820eb9afe015f9537ce7441afda2afc36f4be455fbe8776d6662ad

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: dhis2w_browser-1.2.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.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 4dc0b332c4cd08e503e8e9ff70f4da0d6d3058d62fb854643df57150969f1d14
MD5 363f30427057567b39f5b2e45b0d9e4b
BLAKE2b-256 54e7b5c60b2c14b95c903f2419e6a26235a3556a32ebc1fb4c17a3c2cb2d7f85

See more details on using hashes here.

Provenance

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