pomelo-pw 0.15.4__tar.gz

pomelo_pw-0.15.4/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+coverage/
+*.cover
+.coverage
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.local
+.env.*.local
+
+output
+build/

pomelo_pw-0.15.4/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.5
+Name: pomelo-pw
+Version: 0.15.4
+Summary: Flow-based UI automation tool powered by Playwright
+Requires-Python: >=3.12
+Requires-Dist: click>=8.0.0
+Requires-Dist: playwright>=1.40.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: visual
+Requires-Dist: pillow>=10.0.0; extra == 'visual'
+Description-Content-Type: text/markdown
+
+# Pomelo PW
+
+[![CI](https://github.com/leoninew/pomelo-pw/actions/workflows/ci.yml/badge.svg)](https://github.com/leoninew/pomelo-pw/actions/workflows/ci.yml)
+
+[English](README.md) | [简体中文](README_CN.md)
+
+Pomelo PW is a Playwright-powered CLI for browser automation. It runs declarative YAML flows, so browser checks can live alongside application code without requiring a custom test harness.
+
+It is intended for repeatable UI checks, scripted workflows, visual comparisons, and agent-assisted browser tasks. Flows validate their parameters before execution and collect screenshots, page snapshots, console errors, and network failures when a step fails.
+
+## What It Provides
+
+- YAML flows with `{{variable}}` substitution and CLI overrides
+- Browser steps for navigation, forms, waits, screenshots, state reuse, conditions, and loops
+- Interactive explorer and recorder for finding selectors and creating starting flows
+- Step-level retries, data-driven runs, and screenshot baseline comparison
+- Native plugin packaging for Claude Code, Codex, and Grok Build
+
+## Install
+
+Pomelo PW requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+# Install the published CLI, then install its browser
+uv tool install pomelo-pw
+pomelo-pw install
+
+# Or invoke the published package once without installing the CLI
+uvx pomelo-pw install
+
+# Work from a source checkout
+uv sync --all-groups --locked
+uv run pomelo-pw install
+```
+
+The `install` command downloads Playwright Chromium for package installations. When run from a source checkout or the standalone binary, Pomelo PW uses an installed system Chrome or Chromium when it can find one.
+
+Install visual comparison support only when flows use screenshot baselines:
+
+```bash
+uv pip install pillow
+```
+
+## Quick Start
+
+Create `smoke.yaml`:
+
+```yaml
+name: example-smoke
+variables:
+  base_url: "https://example.com"
+
+steps:
+  - type: navigate
+    url: "{{base_url}}"
+  - type: screenshot
+    file: "homepage.png"
+  - type: scroll
+    direction: down
+    distance: 500
+  - type: screenshot
+    file: "scrolled.png"
+```
+
+Run and validate it:
+
+```bash
+uvx pomelo-pw validate smoke.yaml
+uvx pomelo-pw run smoke.yaml --headless
+```
+
+Screenshots and failure artifacts are written to `./smoke/` by default. Use `-o <directory>` to choose another output directory.
+
+## Use Pomelo PW
+
+### Find Selectors and Create Flows
+
+```bash
+# Inspect a page and copy a selector from the interactive overlay
+pomelo-pw explore https://example.com
+
+# Record clicks, fills, and Enter presses into a YAML flow
+pomelo-pw record https://example.com recorded-flow.yaml
+```
+
+Prefer selectors based on stable semantics, such as `role=button[name="Continue"]`, over presentation-oriented CSS classes.
+
+### Run Flows
+
+```bash
+# Run visibly with step progress
+pomelo-pw run flow.yaml -v
+
+# Run headlessly and emit the result as JSON
+pomelo-pw run flow.yaml --headless --json
+
+# Override a flow variable for this run
+pomelo-pw run flow.yaml --var base_url=https://staging.example.com
+
+# Validate YAML and step parameters without launching a browser
+pomelo-pw validate flow.yaml
+```
+
+Variables use `{{name}}`; CLI values take precedence over step-level values, which take precedence over flow-level values. The `${name}` form is preserved for JavaScript and shell template literals.
+
+### Author Flows
+
+The following flow shows the common pattern: navigate, interact, wait for a meaningful result, then capture evidence.
+
+```yaml
+name: login-smoke
+variables:
+  base_url: "https://app.example.com"
+  username: "user@example.com"
+  password: "secret"
+
+steps:
+  - type: navigate
+    url: "{{base_url}}/login"
+  - type: fill
+    selector: "input[name='email']"
+    value: "{{username}}"
+  - type: fill
+    selector: "input[name='password']"
+    value: "{{password}}"
+  - type: click
+    selector: "button[type='submit']"
+  - type: wait
+    url_contains: "/dashboard"
+  - type: screenshot
+    file: "dashboard.png"
+```
+
+| Step | Main parameters | Purpose |
+| --- | --- | --- |
+| `navigate` | `url` | Open a page |
+| `click`, `hover`, `press` | `selector` or `key` | Interact with an element or keyboard |
+| `fill`, `type` | `selector`, `value` | Enter text |
+| `select` | `selector`, one of `value` / `label` | Choose an option by HTML value or visible text |
+| `wait` | selector, URL, network, or timing condition | Synchronize with dynamic UI |
+| `screenshot` | `file` | Capture a page or element, optionally against a baseline |
+| `check`, `uncheck` | `selector` | Control checkboxes |
+| `save-state`, `load-state` | `file` | Reuse authenticated browser state |
+| `if`, `loop` | condition or iteration settings | Model branches and repeated actions |
+| `evaluate`, `scroll`, `set-viewport` | step-specific parameters | Run browser-side scripts or adjust the viewport |
+
+List the available steps or inspect any step's exact parameters before writing a flow:
+
+```bash
+pomelo-pw steps
+pomelo-pw spec wait
+pomelo-pw spec select
+```
+
+The [flows/](flows/) directory contains runnable examples for waits, retries, saved state, data-driven runs, conditions, loops, JavaScript evaluation, and visual baselines. The bundled [agent skill](plugins/pomelo-pw/skills/pomelo-pw/SKILL.md) contains agent-oriented guidance and reusable flow templates.
+
+## Develop
+
+Install the locked development environment:
+
+```bash
+uv sync --all-groups --locked
+```
+
+Run the normal quality gates directly with `uv`:
+
+```bash
+uv run --locked --no-sync ruff format --check src tests scripts
+uv run --locked --no-sync ruff check src tests scripts
+uv run --locked --no-sync mypy src tests scripts
+uv run --locked --no-sync pytest
+```
+
+On systems with GNU Make and Bash, `make check` and `make test` wrap those commands. `make test cov=1` also writes an HTML coverage report.
+
+### Refresh the Native Plugin
+
+The repository packages the `pomelo-pw` skill as a native plugin. Validate the package first, then refresh the editable CLI and installed plugin for available agent clients:
+
+```bash
+uv run --locked python scripts/install.py plugin check
+uv tool install --editable . --force
+uv run --locked python scripts/install.py plugin apply
+```
+
+Restart the agent client after applying a plugin update so it loads the new skill.
+
+### Build and Release
+
+```bash
+# Inspect the Git-derived release version
+uv run --locked --no-sync python scripts/version_calc.py
+
+# Apply the calculated version to pyproject.toml and uv.lock
+uv run --locked --no-sync python scripts/version_calc.py --no-dry-run
+
+# Build source and wheel distributions
+uv build
+
+# Build a standalone executable when GNU Make and Bash are available
+make binary
+```
+
+Release versions are derived from Git history. After reviewing the version-file changes, commit them and create the matching `vX.Y.Z` tag; GitHub Actions builds the wheel and platform binaries from that tag.
+
+## Repository Layout
+
+```text
+src/pomelo_pw/       CLI, executor, configuration, and step implementations
+tests/               Unit and integration-style tests
+flows/               Runnable YAML examples
+plugins/pomelo-pw/   Native plugin and agent skill
+docs/                Architecture and process documentation
+scripts/             Plugin synchronization and release helpers
+```
+
+## License
+
+MIT

pomelo_pw-0.15.4/README.md

@@ -0,0 +1,219 @@
+# Pomelo PW
+
+[![CI](https://github.com/leoninew/pomelo-pw/actions/workflows/ci.yml/badge.svg)](https://github.com/leoninew/pomelo-pw/actions/workflows/ci.yml)
+
+[English](README.md) | [简体中文](README_CN.md)
+
+Pomelo PW is a Playwright-powered CLI for browser automation. It runs declarative YAML flows, so browser checks can live alongside application code without requiring a custom test harness.
+
+It is intended for repeatable UI checks, scripted workflows, visual comparisons, and agent-assisted browser tasks. Flows validate their parameters before execution and collect screenshots, page snapshots, console errors, and network failures when a step fails.
+
+## What It Provides
+
+- YAML flows with `{{variable}}` substitution and CLI overrides
+- Browser steps for navigation, forms, waits, screenshots, state reuse, conditions, and loops
+- Interactive explorer and recorder for finding selectors and creating starting flows
+- Step-level retries, data-driven runs, and screenshot baseline comparison
+- Native plugin packaging for Claude Code, Codex, and Grok Build
+
+## Install
+
+Pomelo PW requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+# Install the published CLI, then install its browser
+uv tool install pomelo-pw
+pomelo-pw install
+
+# Or invoke the published package once without installing the CLI
+uvx pomelo-pw install
+
+# Work from a source checkout
+uv sync --all-groups --locked
+uv run pomelo-pw install
+```
+
+The `install` command downloads Playwright Chromium for package installations. When run from a source checkout or the standalone binary, Pomelo PW uses an installed system Chrome or Chromium when it can find one.
+
+Install visual comparison support only when flows use screenshot baselines:
+
+```bash
+uv pip install pillow
+```
+
+## Quick Start
+
+Create `smoke.yaml`:
+
+```yaml
+name: example-smoke
+variables:
+  base_url: "https://example.com"
+
+steps:
+  - type: navigate
+    url: "{{base_url}}"
+  - type: screenshot
+    file: "homepage.png"
+  - type: scroll
+    direction: down
+    distance: 500
+  - type: screenshot
+    file: "scrolled.png"
+```
+
+Run and validate it:
+
+```bash
+uvx pomelo-pw validate smoke.yaml
+uvx pomelo-pw run smoke.yaml --headless
+```
+
+Screenshots and failure artifacts are written to `./smoke/` by default. Use `-o <directory>` to choose another output directory.
+
+## Use Pomelo PW
+
+### Find Selectors and Create Flows
+
+```bash
+# Inspect a page and copy a selector from the interactive overlay
+pomelo-pw explore https://example.com
+
+# Record clicks, fills, and Enter presses into a YAML flow
+pomelo-pw record https://example.com recorded-flow.yaml
+```
+
+Prefer selectors based on stable semantics, such as `role=button[name="Continue"]`, over presentation-oriented CSS classes.
+
+### Run Flows
+
+```bash
+# Run visibly with step progress
+pomelo-pw run flow.yaml -v
+
+# Run headlessly and emit the result as JSON
+pomelo-pw run flow.yaml --headless --json
+
+# Override a flow variable for this run
+pomelo-pw run flow.yaml --var base_url=https://staging.example.com
+
+# Validate YAML and step parameters without launching a browser
+pomelo-pw validate flow.yaml
+```
+
+Variables use `{{name}}`; CLI values take precedence over step-level values, which take precedence over flow-level values. The `${name}` form is preserved for JavaScript and shell template literals.
+
+### Author Flows
+
+The following flow shows the common pattern: navigate, interact, wait for a meaningful result, then capture evidence.
+
+```yaml
+name: login-smoke
+variables:
+  base_url: "https://app.example.com"
+  username: "user@example.com"
+  password: "secret"
+
+steps:
+  - type: navigate
+    url: "{{base_url}}/login"
+  - type: fill
+    selector: "input[name='email']"
+    value: "{{username}}"
+  - type: fill
+    selector: "input[name='password']"
+    value: "{{password}}"
+  - type: click
+    selector: "button[type='submit']"
+  - type: wait
+    url_contains: "/dashboard"
+  - type: screenshot
+    file: "dashboard.png"
+```
+
+| Step | Main parameters | Purpose |
+| --- | --- | --- |
+| `navigate` | `url` | Open a page |
+| `click`, `hover`, `press` | `selector` or `key` | Interact with an element or keyboard |
+| `fill`, `type` | `selector`, `value` | Enter text |
+| `select` | `selector`, one of `value` / `label` | Choose an option by HTML value or visible text |
+| `wait` | selector, URL, network, or timing condition | Synchronize with dynamic UI |
+| `screenshot` | `file` | Capture a page or element, optionally against a baseline |
+| `check`, `uncheck` | `selector` | Control checkboxes |
+| `save-state`, `load-state` | `file` | Reuse authenticated browser state |
+| `if`, `loop` | condition or iteration settings | Model branches and repeated actions |
+| `evaluate`, `scroll`, `set-viewport` | step-specific parameters | Run browser-side scripts or adjust the viewport |
+
+List the available steps or inspect any step's exact parameters before writing a flow:
+
+```bash
+pomelo-pw steps
+pomelo-pw spec wait
+pomelo-pw spec select
+```
+
+The [flows/](flows/) directory contains runnable examples for waits, retries, saved state, data-driven runs, conditions, loops, JavaScript evaluation, and visual baselines. The bundled [agent skill](plugins/pomelo-pw/skills/pomelo-pw/SKILL.md) contains agent-oriented guidance and reusable flow templates.
+
+## Develop
+
+Install the locked development environment:
+
+```bash
+uv sync --all-groups --locked
+```
+
+Run the normal quality gates directly with `uv`:
+
+```bash
+uv run --locked --no-sync ruff format --check src tests scripts
+uv run --locked --no-sync ruff check src tests scripts
+uv run --locked --no-sync mypy src tests scripts
+uv run --locked --no-sync pytest
+```
+
+On systems with GNU Make and Bash, `make check` and `make test` wrap those commands. `make test cov=1` also writes an HTML coverage report.
+
+### Refresh the Native Plugin
+
+The repository packages the `pomelo-pw` skill as a native plugin. Validate the package first, then refresh the editable CLI and installed plugin for available agent clients:
+
+```bash
+uv run --locked python scripts/install.py plugin check
+uv tool install --editable . --force
+uv run --locked python scripts/install.py plugin apply
+```
+
+Restart the agent client after applying a plugin update so it loads the new skill.
+
+### Build and Release
+
+```bash
+# Inspect the Git-derived release version
+uv run --locked --no-sync python scripts/version_calc.py
+
+# Apply the calculated version to pyproject.toml and uv.lock
+uv run --locked --no-sync python scripts/version_calc.py --no-dry-run
+
+# Build source and wheel distributions
+uv build
+
+# Build a standalone executable when GNU Make and Bash are available
+make binary
+```
+
+Release versions are derived from Git history. After reviewing the version-file changes, commit them and create the matching `vX.Y.Z` tag; GitHub Actions builds the wheel and platform binaries from that tag.
+
+## Repository Layout
+
+```text
+src/pomelo_pw/       CLI, executor, configuration, and step implementations
+tests/               Unit and integration-style tests
+flows/               Runnable YAML examples
+plugins/pomelo-pw/   Native plugin and agent skill
+docs/                Architecture and process documentation
+scripts/             Plugin synchronization and release helpers
+```
+
+## License
+
+MIT

pomelo_pw-0.15.4/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "pomelo-pw"
+version = "0.15.4"
+description = "Flow-based UI automation tool powered by Playwright"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "playwright>=1.40.0",
+    "click>=8.0.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+visual = [
+    "pillow>=10.0.0",
+]
+
+[project.scripts]
+pomelo-pw = "pomelo_pw.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pomelo_pw"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/pomelo_pw"]
+
+[dependency-groups]
+dev = [
+    "pyinstaller>=6.18.0",
+    "ruff>=0.15.17",
+    "mypy>=2.1.0",
+    "pytest>=9.0.2",
+    "types-pyyaml>=6.0.12.20260518",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.0.0,<8.0.0",
+]
+
+[tool.mypy]
+python_version = "3.12"
+files = ["src", "tests", "scripts"]
+mypy_path = "src"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+warn_unreachable = true
+pretty = true
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+exclude = ["scripts/install.py"]
+force-exclude = true
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

pomelo_pw-0.15.4/src/pomelo_pw/__init__.py

@@ -0,0 +1,5 @@
+"""Pomelo PW - Flow-based UI Automation Tool."""
+
+from importlib.metadata import version
+
+__version__ = version("pomelo-pw")

pomelo_pw-0.15.4/src/pomelo_pw/__main__.py

@@ -0,0 +1,12 @@
+"""Executable entry point for Pomelo PW."""
+
+from pomelo_pw.cli import cli
+
+
+def main() -> None:
+    """Run the command-line interface."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

pomelo_pw-0.15.4/src/pomelo_pw/browser.py

@@ -0,0 +1,36 @@
+"""Shared Playwright browser setup."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from playwright.async_api import Browser, BrowserContext, Playwright
+
+from pomelo_pw.config import PlaywrightConfig
+
+
+class BrowserLifecycle:
+    """Create browser resources from the resolved Playwright configuration."""
+
+    def __init__(self, config: PlaywrightConfig) -> None:
+        self.config = config
+
+    async def launch(self, playwright: Playwright, *, headless: bool) -> Browser:
+        """Launch Chromium with the configured runtime options."""
+        launch_options: dict[str, Any] = {
+            "headless": headless,
+            "timeout": self.config.timeout,
+            "slow_mo": self.config.slow_mo,
+        }
+        if self.config.executable_path:
+            launch_options["executable_path"] = self.config.executable_path
+        return await playwright.chromium.launch(**launch_options)
+
+    async def new_context(self, browser: Browser) -> BrowserContext:
+        """Create a browser context with the configured viewport."""
+        return await browser.new_context(
+            viewport={
+                "width": self.config.viewport.width,
+                "height": self.config.viewport.height,
+            },
+        )