boxprobe-scout 0.1.3__tar.gz

boxprobe_scout-0.1.3/.forgejo/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish Scout
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "pyproject.toml"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build and publish to Forgejo Package Registry
+        run: |
+          FORGEJO_TOKEN=$(grep -E '^FORGEJO_TOKEN=' /takumi/qa/.env.qa | cut -d= -f2-)
+          cd /takumi/qa/scout || { git clone "http://oauth2:${FORGEJO_TOKEN}@forgejo:3000/core/scout.git" /takumi/qa/scout && cd /takumi/qa/scout; }
+          git fetch "http://oauth2:${FORGEJO_TOKEN}@forgejo:3000/core/scout.git" main
+          git reset --hard FETCH_HEAD
+
+          # Build
+          UV_URL="https://github.com/astral-sh/uv/releases/latest/download/uv-x86_64-unknown-linux-musl.tar.gz"
+          wget -qO- "$UV_URL" | tar xz -C /usr/local/bin --strip-components=1
+          rm -rf dist/
+          uv build
+
+          # Publish
+          uv publish \
+            --publish-url http://forgejo:3000/api/packages/core/pypi \
+            --username __token__ \
+            --password "${FORGEJO_TOKEN}" \
+            dist/*

boxprobe_scout-0.1.3/.forgejo/workflows/test.yml

@@ -0,0 +1,22 @@
+name: Test
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      UV_LINK_MODE: copy
+    steps:
+      - name: Checkout and run tests
+        run: |
+          UV_URL="https://github.com/astral-sh/uv/releases/latest/download/uv-x86_64-unknown-linux-musl.tar.gz"
+          wget -qO- "$UV_URL" | tar xz -C /usr/local/bin --strip-components=1
+          FORGEJO_TOKEN=$(grep -E '^FORGEJO_TOKEN=' /takumi/qa/.env.qa | cut -d= -f2-)
+          cd /takumi/qa/scout || { git clone "http://oauth2:${FORGEJO_TOKEN}@forgejo:3000/core/scout.git" /takumi/qa/scout && cd /takumi/qa/scout; }
+          git fetch "http://oauth2:${FORGEJO_TOKEN}@forgejo:3000/core/scout.git" main
+          git reset --hard FETCH_HEAD
+          uv sync --extra dev
+          uv run pytest tests/ -x --tb=short -m "not e2e"

boxprobe_scout-0.1.3/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,74 @@
+name: Bug report
+description: Report something that doesn't work as expected
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing a bug. Please complete every field — incomplete
+        reports usually take a round-trip to triage.
+
+  - type: input
+    id: scout-version
+    attributes:
+      label: scout version
+      description: Output of `scout --version` or `pip show boxprobe-scout`
+      placeholder: "0.1.3"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      description: Output of `python --version`
+      placeholder: "3.12.7"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Linux
+        - macOS
+        - Windows
+        - Other (describe in reproduction)
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: |
+        Minimal scenario file or CLI invocation that triggers the issue.
+        Trim to the smallest case that still fails.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: What actually happened
+      description: Include the full traceback if there is one.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else
+      description: |
+        Logs, screenshots, `result.json` snippets, diff report HTML — whatever
+        helps narrow it down.

boxprobe_scout-0.1.3/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question / general discussion
+    url: https://github.com/boxprobe/scout/discussions
+    about: For questions about usage, design decisions, or open-ended discussion — please use Discussions instead of Issues.
+  - name: Security issues
+    url: mailto:contact@boxprobe.com
+    about: Please report security issues privately by email, not via public Issues.

boxprobe_scout-0.1.3/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,42 @@
+name: Feature request
+description: Suggest a new capability or behavior change
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        scout's scope is deliberately narrow: UI-driven API regression
+        testing. Features that broaden the scope need a strong case. Please
+        explain the use case before proposing a solution.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What can't you do today, or what's painful?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: |
+        How would you want this to work? Concrete API sketches or CLI
+        examples are more useful than abstract descriptions.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Workarounds you've tried, or other tools that solve this.
+
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Scope check
+      options:
+        - label: This is about UI-driven API regression testing (not a generic test runner / load tester / contract testing feature)
+          required: true

boxprobe_scout-0.1.3/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,29 @@
+<!--
+Thanks for the PR! A few quick checks before submitting:
+-->
+
+## What this changes
+
+<!-- One-paragraph summary of the change and its motivation. -->
+
+## Type
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor (no behavior change)
+- [ ] Docs / formatting
+- [ ] Test only
+
+## Checklist
+
+- [ ] Linked issue (or this is a trivial doc/typo PR)
+- [ ] Tests added or updated for behavior changes
+- [ ] `uv run pytest tests/ -x --tb=short -m "not e2e"` passes locally
+- [ ] `uv run ruff check scout/ tests/` passes
+- [ ] `uv run pyright scout/` passes
+- [ ] Externally-observable surfaces flagged (scenario file format, diff report HTML, CLI flags)
+
+## Notes for reviewers
+
+<!-- Anything reviewers should know: tricky parts, why a specific approach
+was chosen, follow-ups deliberately deferred. -->

boxprobe_scout-0.1.3/.github/workflows/ci.yml

@@ -0,0 +1,85 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint and type-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Sync dependencies
+        run: uv sync --extra dev
+
+      - name: ruff check
+        run: uv run ruff check scout/ tests/
+
+      - name: ruff format check
+        run: uv run ruff format --check scout/ tests/
+
+      - name: pyright
+        run: uv run pyright scout/
+
+  test:
+    name: Test on Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python }}
+        run: uv python install ${{ matrix.python }}
+
+      - name: Sync dependencies
+        run: uv sync --extra dev --python ${{ matrix.python }}
+
+      - name: Run tests (no e2e)
+        run: uv run --python ${{ matrix.python }} pytest tests/ -x --tb=short -m "not e2e"
+
+  build:
+    name: Build wheel and sdist
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build
+        run: uv build
+
+      - name: Inspect wheel metadata
+        run: |
+          unzip -p dist/boxprobe_scout-*.whl '*/METADATA' | head -30
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 14

boxprobe_scout-0.1.3/.github/workflows/release.yml

@@ -0,0 +1,101 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    name: Build sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Verify wheel metadata version matches tag
+        run: |
+          tag="${GITHUB_REF_NAME}"
+          expected="${tag#v}"
+          actual=$(unzip -p dist/boxprobe_scout-*.whl '*/METADATA' | awk '/^Version:/ {print $2; exit}')
+          if [ "$actual" != "$expected" ]; then
+            echo "Tag $tag implies version $expected, but wheel built version $actual"
+            exit 1
+          fi
+          echo "Tag and wheel agree on version $actual"
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/boxprobe-scout
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: [publish-pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Extract changelog section
+        id: changelog
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          # Pull lines between [version] header and the next ## header
+          awk -v v="$version" '
+            $0 ~ "^## \\["v"\\]" {flag=1; next}
+            flag && /^## \[/ {exit}
+            flag {print}
+          ' CHANGELOG.md > /tmp/release-notes.md
+          if [ ! -s /tmp/release-notes.md ]; then
+            echo "No changelog entry for $version" > /tmp/release-notes.md
+          fi
+          echo "notes_path=/tmp/release-notes.md" >> "$GITHUB_OUTPUT"
+
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            --title "$GITHUB_REF_NAME" \
+            --notes-file "${{ steps.changelog.outputs.notes_path }}" \
+            dist/*

boxprobe_scout-0.1.3/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+.python-version
+.ruff_cache/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+htmlcov/
+*.sqlite
+.scout/

boxprobe_scout-0.1.3/AGENTS.md

@@ -0,0 +1,7 @@
+# Agent Constraints
+
+1. **Run tests before committing**: `uv run pytest tests/ -x --tb=short`
+2. **Don't touch unrelated code** — scope changes to the task at hand
+3. **Conventional commits** — `feat:`, `fix:`, `test:`, `refactor:`, `docs:`
+4. **Don't add dependencies** without explicit approval
+5. **All Python commands via `uv run`** — never bare `python` or `pip`

boxprobe_scout-0.1.3/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to scout are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+once it reaches `1.0.0`. While in `0.x`, breaking changes may occur between
+minor versions; patch versions remain backward-compatible bug fixes.
+
+## [Unreleased]
+
+## [0.1.3] - 2026-05-16
+
+Initial public release on PyPI. Prior `0.1.x` versions were distributed
+internally via a private package registry; this is the first cut intended
+for external consumers.
+
+### Features at this version
+
+- `scout run` — execute pre-recorded Python scenarios via Playwright,
+  capture API traffic through a recording proxy
+- `scout verify` — debug-mode scenario execution with screenshots, no proxy
+- `scout diff` — compare two runs' API recordings, produce HTML diff report
+  with structural, value, and known-change classification
+- `scout runs` — list local run history
+- Pixel-anchored `Locator` API with `abs` / `rel` / `dxy` positioning
+- `diff_ignore.json` rule format for field, value-type, endpoint, and
+  status-only noise suppression
+- HTML diff report with filterable endpoint table, popup body diffs, and
+  known-change badges
+- JUnit XML report alongside HTML for CI integration
+
+[Unreleased]: https://github.com/boxprobe/scout/compare/v0.1.3...HEAD
+[0.1.3]: https://github.com/boxprobe/scout/releases/tag/v0.1.3

boxprobe_scout-0.1.3/CLAUDE.md

@@ -0,0 +1,181 @@
+# scout
+
+UI-driven API regression testing — a CLI that executes pre-recorded
+scenarios, captures API traffic via a proxy, and produces cross-version
+diff reports.
+
+**Install:**
+
+```bash
+pip install boxprobe-scout
+playwright install chromium
+```
+
+## Code structure
+
+```
+scout/
+├── cli.py                  # Click CLI entry
+│                           #   scout run    — record API traffic during execution
+│                           #   scout verify — screenshot mode for scenario debugging
+│                           #   scout diff   — compare two runs' API recordings
+│                           #   scout runs   — list run history
+├── config.py               # app.json loader + URL overrides
+├── git.py                  # git commit/branch lookup for run metadata
+├── index.py                # local run index (SQLite, .scout/index.db)
+├── run_metadata.py         # run metadata assembly
+├── runner/
+│   ├── executor.py         # Playwright orchestration, batch execution
+│   ├── scenario.py         # Scenario DSL (base_url, @setup, @test)
+│   ├── page.py             # Page wrapper (goto/click/fill/wait via Locator)
+│   └── locator.py          # Pixel-anchored Locator with abs/rel/dxy positioning
+├── collector/
+│   ├── subprocess.py       # recording proxy subprocess manager
+│   ├── proxy.py            # mitmproxy addon
+│   ├── control.py          # proxy control API (session start/stop)
+│   └── db.py               # recording DB (SQLite: scenarios + api_records)
+├── matcher/
+│   ├── align.py            # endpoint pairing (path-only + 2-stage query match)
+│   ├── compare.py          # JSON structure + value comparison
+│   ├── normalize.py        # URL path normalization (dynamic ID inference)
+│   ├── noise.py            # diff_ignore.json rules + known-change suppression
+│   ├── diff_db.py          # diff result DB
+│   └── diff_report.py      # HTML diff report generation
+├── report/
+│   ├── html.py             # per-run HTML report
+│   └── junit.py            # JUnit XML report
+├── secrets/                # credential injection (pyrage encryption — planned)
+├── bridge/                 # browser bridge over CDP — planned
+├── mcp/                    # MCP server for AI agent integration — planned
+└── server/                 # planned
+```
+
+## CLI commands
+
+```bash
+# Recording run: launches proxy, records API traffic to
+# .scout/runs/<run_id>/record.db
+scout run scenarios/auth/login-success --web-version 1.0.0
+scout run scenarios/ --web-version 1.0.0   # recurse: find any test.py
+
+# Debug verify: screenshot mode, no proxy
+scout verify scenarios/auth/login-success --headed
+
+# Diff: compare two recordings
+scout runs                                  # list run IDs
+scout diff <baseline-id> <target-id>
+scout diff <baseline-id> <target-id> --no-detail  # skip body popup data
+
+# URL override (for staging/local environments)
+scout run scenarios/ --web-base-url http://localhost:9000 \
+                     --api-base-url http://localhost:9000 \
+                     --web-version dev
+```
+
+`--web-version` is required on `scout run` — it tags the recording so
+diff reports can label each side and so "added in <ver>" known-change
+buttons in the report work correctly.
+
+## Data flow
+
+```
+scout run
+  ├── Launch recording proxy (separate process)
+  ├── Playwright browser → proxy → target app
+  ├── Notify proxy of session boundaries per scenario
+  ├── API traffic     → .scout/runs/<run_id>/record.db
+  ├── Per-scenario    → .scout/runs/<run_id>/<scenario>/result.json
+  ├── HTML+JUnit      → .scout/runs/<run_id>/report.html, junit.xml
+  └── Run index       → .scout/index.db
+
+scout diff baseline target
+  ├── Read both runs' record.db
+  ├── Pair endpoints by path; resolve query differences (2-stage)
+  ├── Compare status code + JSON structure + values
+  ├── Apply diff_ignore.json rules (field/value-type/endpoint ignores)
+  ├── Diff DB         → .scout/diffs/<baseline>_vs_<target>/diff.db
+  └── HTML report     → .scout/diffs/<baseline>_vs_<target>/report.html
+```
+
+## Scenario file format
+
+A scenario lives in a directory next to an `app.json`:
+
+```
+my-app/
+├── app.json
+├── diff_ignore.json        # optional: noise rules
+└── scenarios/
+    └── login/
+        └── test.py
+```
+
+```json
+// app.json
+{
+  "name": "my-app",
+  "web_base_url": "https://app.example.com",
+  "api_base_url": "https://api.example.com",
+  "viewport_width": 1280,
+  "viewport_height": 800
+}
+```
+
+```python
+# scenarios/login/test.py
+from scout.runner import Locator, Page, Scenario
+
+scenario = Scenario(
+    name="login",
+    base_url="https://app.example.com",
+    viewport_width=1280,
+    viewport_height=800,
+)
+
+email = Locator(name="email", tag="input", bbox=(640, 320, 280, 32))
+password = Locator(name="password", tag="input", bbox=(640, 372, 280, 32))
+submit = Locator(name="submit", tag="button", bbox=(640, 428, 280, 40))
+
+
+@scenario.test
+async def test(page: Page) -> None:
+    await page.goto("/login")
+    await page.fill(email, "user@example.com")
+    await page.fill(password, "password123")
+    await page.click(submit)
+    await page.wait(2000)
+
+
+if __name__ == "__main__":
+    scenario.run()
+```
+
+## Tech stack
+
+| Layer              | Choice                                    |
+|--------------------|-------------------------------------------|
+| CLI                | Python + Click                            |
+| Browser automation | Playwright (Python)                       |
+| HTTP client        | httpx                                     |
+| Recording proxy    | mitmproxy (separate process)              |
+| Data store         | SQLite (recordings, diffs, run index)     |
+| Reports            | HTML + JUnit XML                          |
+| Lint + format      | ruff                                      |
+| Type checking      | pyright                                   |
+| Tests              | pytest + pytest-asyncio + pytest-playwright |
+
+## Python environment
+
+- Python >= 3.11
+- Uses [uv](https://docs.astral.sh/uv/) for environment management
+- **All Python commands must use `uv run`** — never bare `python` or `pip`.
+  `uv run` guarantees the venv interpreter matches `pyproject.toml`'s
+  `requires-python`; system Python can silently drift.
+
+## Conventions
+
+- Code, comments, commit messages, issues, PRs: English
+- [Conventional Commits](https://www.conventionalcommits.org/) — `feat:`,
+  `fix:`, `test:`, `refactor:`, `docs:`, `chore:`
+- Run `uv run pytest tests/ -x --tb=short -m "not e2e"` before pushing
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for full development setup