dhis2w-browser 0.5.3__tar.gz

dhis2w_browser-0.5.3/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.3
+Name: dhis2w-browser
+Version: 0.5.3
+Summary: Playwright-based helpers for DHIS2 UI automation.
+Author: Morten Hansen
+Author-email: Morten Hansen <morten@winterop.com>
+Requires-Dist: dhis2w-client>=0.5.0,<0.6
+Requires-Dist: pillow>=12.2.0
+Requires-Dist: playwright>=1.58
+Requires-Dist: pydantic>=2.13
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# dhis2-browser
+
+Playwright-based helpers for DHIS2 UI automation. Separate from `dhis2-client` so API-only callers never pull in Chromium.
+
+## Install
+
+```bash
+uv add 'dhis2-cli[browser]'            # pulls dhis2-browser alongside the main CLI
+playwright install chromium           # one-off; pulls the actual browser driver
+```
+
+Library-only consumers (no CLI) can install `dhis2-browser` on its own.
+
+## Surface
+
+The CLI lives on the main `dhis2` entry point as a plugin; there's no separate `dhis2-browser` binary. Workflows mount under `dhis2 browser <subcommand>`:
+
+```bash
+dhis2 browser pat --url http://localhost:8080 --username admin --password district
+dhis2 browser dashboard screenshot --output-dir /tmp/out --only <uid>
+dhis2 browser viz screenshot --output-dir /tmp/out --only <uid>
+dhis2 browser map screenshot --output-dir /tmp/out --only <uid>
+```
+
+Library callers import from `dhis2_browser` directly:
+
+| Entry point | Purpose |
+| --- | --- |
+| `dhis2_browser.logged_in_page(url, username, password)` | Async context manager yielding a `(BrowserContext, Page)` tuple logged into DHIS2 via the React login form. |
+| `dhis2_browser.session_from_cookie(url, jsessionid)` | Fast-path variant — inject a pre-minted `JSESSIONID` instead of driving the login form. |
+| `dhis2_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. |
+| `dhis2_browser.drive_oauth2_login(profile_name, *, username, password)` | Run `dhis2 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. |
+| `dhis2_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`. |
+| `dhis2_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 `dhis2 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
+
+```python
+import asyncio
+from dhis2_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.

dhis2w_browser-0.5.3/README.md

@@ -0,0 +1,71 @@
+# dhis2-browser
+
+Playwright-based helpers for DHIS2 UI automation. Separate from `dhis2-client` so API-only callers never pull in Chromium.
+
+## Install
+
+```bash
+uv add 'dhis2-cli[browser]'            # pulls dhis2-browser alongside the main CLI
+playwright install chromium           # one-off; pulls the actual browser driver
+```
+
+Library-only consumers (no CLI) can install `dhis2-browser` on its own.
+
+## Surface
+
+The CLI lives on the main `dhis2` entry point as a plugin; there's no separate `dhis2-browser` binary. Workflows mount under `dhis2 browser <subcommand>`:
+
+```bash
+dhis2 browser pat --url http://localhost:8080 --username admin --password district
+dhis2 browser dashboard screenshot --output-dir /tmp/out --only <uid>
+dhis2 browser viz screenshot --output-dir /tmp/out --only <uid>
+dhis2 browser map screenshot --output-dir /tmp/out --only <uid>
+```
+
+Library callers import from `dhis2_browser` directly:
+
+| Entry point | Purpose |
+| --- | --- |
+| `dhis2_browser.logged_in_page(url, username, password)` | Async context manager yielding a `(BrowserContext, Page)` tuple logged into DHIS2 via the React login form. |
+| `dhis2_browser.session_from_cookie(url, jsessionid)` | Fast-path variant — inject a pre-minted `JSESSIONID` instead of driving the login form. |
+| `dhis2_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. |
+| `dhis2_browser.drive_oauth2_login(profile_name, *, username, password)` | Run `dhis2 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. |
+| `dhis2_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`. |
+| `dhis2_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 `dhis2 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
+
+```python
+import asyncio
+from dhis2_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.

dhis2w_browser-0.5.3/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "dhis2w-browser"
+version = "0.5.3"
+description = "Playwright-based helpers for DHIS2 UI automation."
+readme = "README.md"
+authors = [{ name = "Morten Hansen", email = "morten@winterop.com" }]
+requires-python = ">=3.13"
+dependencies = [
+  "dhis2w-client>=0.5.0,<0.6",
+  "pillow>=12.2.0",
+  "playwright>=1.58",
+  "pydantic>=2.13",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"

dhis2w_browser-0.5.3/src/dhis2w_browser/__init__.py

@@ -0,0 +1,58 @@
+"""Playwright-based helpers for DHIS2 UI automation."""
+
+from dhis2w_browser.dashboard import (
+    CaptureResult,
+    DashboardTarget,
+    add_banner,
+    capture_dashboard,
+    slugify,
+    switch_dashboard,
+    trim_background,
+)
+from dhis2w_browser.maps import (
+    MapCaptureResult,
+    MapTarget,
+    add_map_banner,
+    capture_map,
+    slugify_map,
+)
+from dhis2w_browser.oauth2 import OAuth2LoginResult, drive_login_form, drive_oauth2_login
+from dhis2w_browser.pat import PatAttribute, PatOptions, PatPayload, create_pat
+from dhis2w_browser.session import logged_in_page, resolve_headless, session_from_cookie
+from dhis2w_browser.visualization import (
+    VisualizationCaptureResult,
+    VisualizationTarget,
+    add_viz_banner,
+    capture_visualization,
+    slugify_viz,
+)
+
+__all__ = [
+    "CaptureResult",
+    "DashboardTarget",
+    "MapCaptureResult",
+    "MapTarget",
+    "OAuth2LoginResult",
+    "PatAttribute",
+    "PatOptions",
+    "PatPayload",
+    "VisualizationCaptureResult",
+    "VisualizationTarget",
+    "add_banner",
+    "add_map_banner",
+    "add_viz_banner",
+    "capture_dashboard",
+    "capture_map",
+    "capture_visualization",
+    "create_pat",
+    "drive_login_form",
+    "drive_oauth2_login",
+    "logged_in_page",
+    "resolve_headless",
+    "session_from_cookie",
+    "slugify",
+    "slugify_map",
+    "slugify_viz",
+    "switch_dashboard",
+    "trim_background",
+]

dhis2w_browser-0.5.3/src/dhis2w_browser/dashboard.py

@@ -0,0 +1,358 @@
+"""Full-page screenshot helpers for DHIS2 dashboards.
+
+The DHIS2 dashboard app is a React SPA where each dashboard item loads its
+own plugin iframe. Three quirks the helpers in this module paper over:
+
+1. **Lazy-load via viewport intersection.** The app only materialises a
+   plugin iframe when its slot scrolls into view. Programmatic `scrollTop`
+   doesn't fire the intersection observers — real `mouse.wheel` events are
+   required.
+
+2. **Nested render detection.** There's no single "dashboard ready" event.
+   The only reliable way to know an item has rendered is to poke the inner
+   plugin iframe for substantial content (canvas / svg / leaflet /
+   highcharts / img / long text). A plateau detector covers items that
+   never fully render (data issues, bad expressions) so one stuck chart
+   doesn't block the whole capture.
+
+3. **Session-spanning hash navigation.** Switching dashboards via a fresh
+   URL forces a full reload (re-auth, re-init). Setting
+   `iframe.contentWindow.location.hash = '/{uid}'` swaps dashboards in
+   place — saves 3+ seconds per capture on big batches.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from PIL import Image, ImageDraw, ImageFont
+from pydantic import BaseModel, ConfigDict
+
+if TYPE_CHECKING:
+    from playwright.async_api import Page
+
+
+class DashboardTarget(BaseModel):
+    """One dashboard the caller wants captured — uid + display name + item count."""
+
+    model_config = ConfigDict(frozen=True)
+
+    uid: str
+    display_name: str
+    item_count: int
+
+
+class CaptureResult(BaseModel):
+    """Outcome of one dashboard capture — output file + render-completion stats."""
+
+    model_config = ConfigDict(frozen=True)
+
+    uid: str
+    display_name: str
+    output_path: Path
+    items_expected: int
+    items_rendered: int
+
+
+def slugify(name: str) -> str:
+    """Produce a filename-safe slug from a dashboard display name."""
+    stripped = name.lower().strip()
+    stripped = re.sub(r"[^\w\s-]", "", stripped)
+    stripped = re.sub(r"[\s_-]+", "-", stripped)
+    return stripped.strip("-") or "dashboard"
+
+
+async def hide_chrome(page: Page) -> None:
+    """Hide DHIS2's outer header + the inner dashboard-app toolbar via injected CSS.
+
+    The header is on the outer page; the dashboard toolbar is inside the
+    plugin-host iframe (DHIS2's apps are iframed off the apps shell).
+    """
+    await page.evaluate(
+        """() => {
+            const header = document.querySelector('header');
+            if (header) header.style.display = 'none';
+            const iframe = document.querySelector('iframe');
+            if (iframe) {
+                iframe.style.top = '0';
+                iframe.style.height = '100vh';
+            }
+        }"""
+    )
+    await page.evaluate(
+        """() => {
+            const iframe = document.querySelector('iframe');
+            if (!iframe || !iframe.contentDocument) return;
+            const doc = iframe.contentDocument;
+            const toolbar = doc.querySelector('[data-test="dashboard-bar"]')
+                || doc.querySelector('div[class*="toolbar"]');
+            if (toolbar) toolbar.style.display = 'none';
+        }"""
+    )
+
+
+async def count_rendered_items(page: Page) -> int:
+    """Count `.react-grid-item` slots whose inner plugin iframe has rendered content.
+
+    "Rendered" = the inner iframe's body contains a canvas, an SVG with
+    substantive paths/rects, a leaflet/highcharts container, or an image, or
+    the body's innerText is non-trivial (long text items). Cross-origin
+    inner iframes throw on `contentDocument` access — swallow those; they're
+    either app-iframes we can't inspect or plugin fallbacks that don't
+    matter for render detection.
+    """
+    raw = await page.evaluate(
+        """() => {
+            const outer = document.querySelector('iframe');
+            if (!outer || !outer.contentDocument) return 0;
+            const items = outer.contentDocument.querySelectorAll('.react-grid-item');
+            let count = 0;
+            items.forEach(el => {
+                const inner = el.querySelector('iframe');
+                if (!inner) {
+                    // Items without an inner iframe (text blocks, etc.) — check the
+                    // slot itself.
+                    if (el.innerText.trim().length > 30) count++;
+                    return;
+                }
+                try {
+                    const doc = inner.contentDocument;
+                    if (!doc || !doc.body) return;
+                    const has = doc.querySelector('canvas')
+                        || doc.querySelector('svg path')
+                        || doc.querySelector('svg rect')
+                        || doc.querySelector('table td')
+                        || doc.querySelector('[class*="leaflet"]')
+                        || doc.querySelector('[class*="highcharts"]')
+                        || doc.querySelector('video')
+                        || doc.querySelector('img[src]')
+                        || doc.body.innerText.trim().length > 100;
+                    if (has) count++;
+                } catch {
+                    // Cross-origin iframe — skip.
+                }
+            });
+            return count;
+        }"""
+    )
+    return int(raw) if isinstance(raw, (int, float)) else 0
+
+
+async def wait_for_render(
+    page: Page,
+    expected: int,
+    *,
+    timeout_seconds: float = 90.0,
+    poll_seconds: float = 2.0,
+    plateau_polls: int = 3,
+) -> int:
+    """Block until `expected` items have rendered, or the count plateaus.
+
+    Returns the highest `count_rendered_items(page)` result observed. The
+    plateau detector gives up gracefully after `plateau_polls` consecutive
+    unchanged polls — one stuck chart doesn't stall the rest of the pipeline.
+    """
+    deadline = asyncio.get_event_loop().time() + timeout_seconds
+    rendered = 0
+    stable_count = 0
+    last_rendered = -1
+    while asyncio.get_event_loop().time() < deadline:
+        rendered = await count_rendered_items(page)
+        if rendered >= expected:
+            return rendered
+        if rendered == last_rendered:
+            stable_count += 1
+            if stable_count >= plateau_polls:
+                return rendered
+        else:
+            stable_count = 0
+        last_rendered = rendered
+        await asyncio.sleep(poll_seconds)
+    return rendered
+
+
+async def get_content_height(page: Page) -> int:
+    """Measure the furthest `.react-grid-item.bottom` so the viewport sizes right."""
+    height = await page.evaluate(
+        """() => {
+            const iframe = document.querySelector('iframe');
+            if (!iframe || !iframe.contentDocument) return 2000;
+            const items = iframe.contentDocument.querySelectorAll('.react-grid-item');
+            let maxBottom = 0;
+            items.forEach(el => {
+                const rect = el.getBoundingClientRect();
+                if (rect.bottom > maxBottom) maxBottom = rect.bottom;
+            });
+            return maxBottom || 2000;
+        }"""
+    )
+    return int(height)
+
+
+async def scroll_to_load_all_items(page: Page, *, steps: int = 20, step_pixels: int = 800) -> None:
+    """Scroll through the dashboard with real `mouse.wheel` events to trigger lazy loading.
+
+    Programmatic `scrollTop` doesn't fire DHIS2's intersection-observer hooks;
+    only real wheel events prompt the app to materialise plugin iframes that
+    are still offscreen. Clicks into the dashboard area first so the inner
+    iframe has focus, scrolls down to the bottom, then back up so the first
+    items are re-visible when the screenshot fires.
+    """
+    for _ in range(15):
+        count = await page.evaluate(
+            """() => {
+                const f = document.querySelector('iframe');
+                if (!f || !f.contentDocument) return 0;
+                return f.contentDocument.querySelectorAll('.react-grid-item').length;
+            }"""
+        )
+        if count > 0:
+            break
+        await asyncio.sleep(1)
+    await page.mouse.click(700, 400)
+    await asyncio.sleep(0.5)
+    for _ in range(steps):
+        await page.mouse.wheel(0, step_pixels)
+        await asyncio.sleep(0.4)
+    for _ in range(steps):
+        await page.mouse.wheel(0, -step_pixels)
+        await asyncio.sleep(0.15)
+    await asyncio.sleep(2)
+
+
+async def switch_dashboard(page: Page, dashboard_uid: str, *, settle_seconds: float = 5.0) -> None:
+    """Swap the inner iframe's hash to the given dashboard UID — no full reload.
+
+    The dashboard app reads the hash off its own location and re-renders in
+    place, dropping the prior grid items and building new ones. Settling
+    time gives the grid time to materialise before the caller starts
+    checking render completion.
+    """
+    await page.evaluate(
+        f"""() => {{
+            const iframe = document.querySelector('iframe');
+            if (iframe && iframe.contentWindow) {{
+                iframe.contentWindow.location.hash = '/{dashboard_uid}';
+            }}
+        }}"""
+    )
+    await asyncio.sleep(settle_seconds)
+
+
+def trim_background(path: Path) -> None:
+    """Crop uniform-colour edges off the bottom + right of a screenshot (in-place)."""
+    img = Image.open(path)
+    pixels = img.load()
+    if pixels is None:  # pragma: no cover — Pillow always returns PixelAccess for PNGs
+        return
+    width, height = img.size
+    background = pixels[width - 1, height - 1]
+
+    crop_y = height
+    for y in range(height - 1, -1, -1):
+        if not all(pixels[x, y] == background for x in range(0, width, 10)):
+            crop_y = min(y + 20, height)
+            break
+
+    crop_x = width
+    for x in range(width - 1, -1, -1):
+        if not all(pixels[x, y] == background for y in range(0, crop_y, 10)):
+            crop_x = min(x + 20, width)
+            break
+
+    if crop_x < width or crop_y < height:
+        img.crop((0, 0, crop_x, crop_y)).save(path)
+
+
+def add_banner(
+    path: Path,
+    dashboard_name: str,
+    *,
+    instance_url: str,
+    username: str,
+    item_count: int,
+    timestamp: datetime | None = None,
+) -> None:
+    """Prepend a dark info banner above the screenshot (in-place)."""
+    when = timestamp or datetime.now(tz=UTC)
+    img = Image.open(path)
+    width, height = img.size
+
+    banner_height = 36
+    banner = Image.new("RGB", (width, banner_height), (55, 63, 81))
+    draw = ImageDraw.Draw(banner)
+
+    font: ImageFont.ImageFont | ImageFont.FreeTypeFont
+    try:
+        font = ImageFont.truetype("/System/Library/Fonts/SFNSMono.ttf", 14)
+    except OSError:
+        try:
+            font = ImageFont.truetype("/System/Library/Fonts/Menlo.ttc", 14)
+        except OSError:
+            font = ImageFont.load_default()
+
+    instance = re.sub(r"https?://", "", instance_url)
+    text = (
+        f"  {dashboard_name}  |  {instance}  |  {item_count} items  |  {when.strftime('%Y-%m-%d %H:%M')}  |  {username}"
+    )
+    draw.text((10, 10), text, fill=(220, 225, 234), font=font)
+
+    result = Image.new("RGB", (width, banner_height + height))
+    result.paste(banner, (0, 0))
+    result.paste(img.convert("RGB"), (0, banner_height))
+    result.save(path)
+
+
+async def capture_dashboard(
+    page: Page,
+    target: DashboardTarget,
+    output_path: Path,
+    *,
+    viewport_width: int = 1400,
+    viewport_height_expanded: int = 8000,
+    render_timeout_seconds: float = 90.0,
+) -> CaptureResult:
+    """Screenshot one dashboard, assuming `page` is already on the dashboard app.
+
+    Caller handles switching between dashboards (via `switch_dashboard`) or
+    initial navigation. This function handles: reset viewport → scroll-trigger
+    lazy loads → wait for renders → resize viewport to fit content → hide
+    chrome → capture full page.
+    """
+    await page.set_viewport_size({"width": viewport_width, "height": 900})
+
+    if target.item_count == 0:
+        # Empty dashboard — skip the scroll+wait dance; just hide chrome + snap.
+        await hide_chrome(page)
+        await page.screenshot(path=str(output_path), full_page=True)
+        return CaptureResult(
+            uid=target.uid,
+            display_name=target.display_name,
+            output_path=output_path,
+            items_expected=0,
+            items_rendered=0,
+        )
+
+    await scroll_to_load_all_items(page)
+    await page.set_viewport_size({"width": viewport_width, "height": viewport_height_expanded})
+    await asyncio.sleep(3)
+
+    rendered = await wait_for_render(page, target.item_count, timeout_seconds=render_timeout_seconds)
+
+    content_height = await get_content_height(page) + 50
+    await page.set_viewport_size({"width": viewport_width, "height": content_height})
+    await asyncio.sleep(2)
+
+    await hide_chrome(page)
+    await page.screenshot(path=str(output_path), full_page=True)
+    return CaptureResult(
+        uid=target.uid,
+        display_name=target.display_name,
+        output_path=output_path,
+        items_expected=target.item_count,
+        items_rendered=rendered,
+    )