Metadata-Version: 2.4
Name: appium-live-view
Version: 0.1.3
Summary: Build a standalone, interactive HTML live view from an Appium page source (XML) + screenshot
License-Expression: MIT
Project-URL: Homepage, https://github.com/v-dermichev/appium-live-view-plugin
Keywords: appium,allure,inspector,screenshot,xml,testing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# appium-live-view (Python)

Build a standalone, interactive HTML **live view** — the Appium Inspector
experience (hover to highlight, click to inspect attributes + locators, a
selectable source tree, an XPath tester) — from a page source (XML) + screenshot.
No server, no browser, no Node: one function returns a self-contained HTML string
you can attach to Allure or save anywhere.

It's the Python counterpart of the [Appium plugin / JS renderer](../README.md).
The interactive CSS + JS are shared verbatim with the JS renderer (generated by
`tools/extract-assets.mjs`), so both produce the same live view.

## Install

```bash
pip install ./python          # from this repo
# or, once published:
pip install appium-live-view
```

## Use

```python
from appium_live_view import build_live_view_html
import allure

html = build_live_view_html(
    driver.page_source,                 # XML string
    driver.get_screenshot_as_png(),     # raw PNG bytes (also accepts base64 or a data: URI)
    title="Login screen",
    platform_name=driver.capabilities.get("platformName"),
)
allure.attach(html, "Live view", allure.attachment_type.HTML)
```

A pytest failure hook is a natural home:

```python
import pytest, allure
from appium_live_view import build_live_view_html

@pytest.hookimpl(hookwrapper=True)
def pytest_runtest_makereport(item, call):
    outcome = yield
    report = outcome.get_result()
    driver = getattr(item.instance, "driver", None)
    if report.when == "call" and report.failed and driver is not None:
        html = build_live_view_html(driver.page_source, driver.get_screenshot_as_png())
        allure.attach(html, "Live view", allure.attachment_type.HTML)
```

## API

`build_live_view_html(xml=None, screenshot=None, *, title=None, platform_name=None, selected_path=None, context=None, webview_rect=None, parsed=None) -> str`

- `xml` — Appium page source (`driver.page_source`).
- `screenshot` — raw PNG `bytes`, a base64 `str`, or a full `data:` URI. Optional
  (overlays still work without it).
- `selected_path` — dot-separated node path to pre-select (e.g. the element a step
  acted on).
- `context` — `"web"` / `"native"` to force locator style + coordinate handling
  (else auto-detected from the snapshot root).
- `webview_rect` — `{"x", "y", "width", "height"}` in CSS px: the WebView's
  on-screen rectangle, for a full-device screenshot (iOS Safari / a hybrid WebView
  below a native bar). Overlays are offset by `x`/`y`. Not needed for a
  web-viewport screenshot (Android Chrome).

Also exported: `parse_source`, `parse_coordinates`, `suggest_locators`,
`absolute_xpath`, and `WEB_SNAPSHOT_JS`.

## WebView / hybrid context

In a WebView context `driver.page_source` is HTML without coordinates. Run the
DOM snapshot script in the webview to capture tags + attributes + bounds, then
render with `context="web"` (CSS + DOM-XPath locators):

```python
from appium_live_view import WEB_SNAPSHOT_JS, build_live_view_html

source = driver.execute_script(WEB_SNAPSHOT_JS)          # in the webview context
html = build_live_view_html(source, driver.get_screenshot_as_png(), context="web")
```

The snapshot records on-device geometry (`devicePixelRatio`, viewport, `screen`
size), so overlays scale per device and a **web-viewport** screenshot (Android
Chrome) lines up automatically. A **full-device** screenshot (iOS Safari, or a
hybrid WebView below a native bar) has the web content offset from the top; that
offset isn't visible to the page, so pass the WebView's on-screen rectangle (CSS
px, e.g. from Appium's native context) as `webview_rect`:

```python
html = build_live_view_html(
    source, driver.get_screenshot_as_png(), context="web",
    webview_rect={"x": 0, "y": 59, "width": 393, "height": 659},
)
```

## Notes

- **Interactivity inline in Allure 3:** hover and click-to-pin and the source tree
  are pure CSS and work inline; copy, the XPath tester and the download buttons
  need JavaScript, which Allure strips from inline attachments. Open the attachment
  standalone, or apply the report patch in
  [`../examples/allure-inline-interactive/`](../examples/allure-inline-interactive/).
- **Requires Python 3.8+**, no third-party dependencies.
