clicked-evidence 0.1.0__tar.gz

clicked_evidence-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ritish Saini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clicked_evidence-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: clicked-evidence
+Version: 0.1.0
+Summary: Prove what one browser interaction actually did -- every network request it made, and optionally what changed on a local backing store.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MaXiMo000/clicked
+Project-URL: Source, https://github.com/MaXiMo000/clicked
+Project-URL: Issues, https://github.com/MaXiMo000/clicked/issues
+Project-URL: Changelog, https://github.com/MaXiMo000/clicked/releases
+Keywords: browser,playwright,testing,evidence,provenance,e2e
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: receipt-evidence>=0.1.1
+Dynamic: license-file
+
+# clicked
+
+[![ci](https://github.com/MaXiMo000/clicked/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/clicked/actions/workflows/ci.yml)
+
+**Prove what one browser interaction actually did -- every network
+request it made, and optionally what changed on a local backing store.**
+
+[`receipt`](https://github.com/MaXiMo000/receipt) proves what a shell
+command touched. [`custody`](https://github.com/MaXiMo000/custody) proves
+what an AI agent's tool call touched. `clicked` proves what a *click*
+touched -- the same "verified execution, not just self-report" idea, one
+layer up: a browser-automation test that asserts "clicking Save sends the
+right request" is trusting the test's own assumption unless something
+independently recorded what the browser actually sent.
+
+```python
+from clicked import capture
+
+with capture(page, task="click save button") as c:
+    page.click("#save")
+    page.wait_for_timeout(200)
+
+print(c.to_dict())
+```
+
+```json
+{
+  "providence_version": 1,
+  "tool": "clicked",
+  "payload": {
+    "task": "click save button",
+    "seconds": 0.324,
+    "requests": [
+      {"url": "http://127.0.0.1:60672/api/save", "method": "POST",
+       "post_data": "{\"name\":\"ada\"}", "status": 200, "failure": null}
+    ],
+    "raised": null
+  },
+  "sha256": "ed727efcdccbc..."
+}
+```
+
+(Real output, from `tests/test_capture_live.py` -- a real headless
+Chromium, clicking a real button, against a real local HTTP server.)
+
+## Install
+
+```
+pip install clicked-evidence
+```
+
+For once, no PyPI name-squatting to work around -- both `clicked` and
+`clicked-evidence` were actually free.
+
+## Use
+
+`capture()` takes any Playwright `Page` object and a `task` description.
+Everything inside the `with` block is one interaction:
+
+```python
+from clicked import capture
+
+with capture(page, task="delete account button") as c:
+    page.click("#delete-account-button")
+    page.wait_for_load_state("networkidle")
+
+c.write("receipt.json")   # a Providence bundle -- see below
+```
+
+`c.requests` is every network request/response pair that happened during
+the block (URL, method, POST body, status, or a `failure` reason if the
+request never got a response at all). This is what was actually sent and
+actually came back -- not what the page's own JavaScript claims it sent.
+
+## Redaction
+
+`url` and `post_data` are swept through
+[`receipt.redact`](https://github.com/MaXiMo000/receipt) before being
+stored -- a real interaction routinely carries a credential in a query
+string (`?api_key=...`) or a form/JSON POST body (`{"password": "..."}`),
+and a receipt is meant to be kept and handed to someone else as evidence,
+not a second place that credential now lives. Same regex-based, best-
+effort sweep `receipt` and `custody` already use, not exhaustive -- see
+receipt's own README for what it doesn't catch.
+
+### Watching the filesystem too
+
+Pass `watch_dir` to also snapshot-diff a local directory before and after
+the interaction, reusing `receipt.snapshot`'s real `snapshot()`/`diff()`
+core directly (not reimplemented):
+
+```python
+with capture(page, task="click save button", watch_dir="./data") as c:
+    page.click("#save")
+    page.wait_for_timeout(200)
+
+print(c.result["changes"])  # {"added": ["saved.json"], "modified": [], ...}
+```
+
+This closes the loop from *client* interaction to *backend* side effect --
+proving the click didn't just send a request that returned 200, but that
+a real file actually landed on disk because of it. `watch_dir=None` (the
+default) skips this step entirely; no extra install needed either way.
+
+### Why no CLI
+
+Every other tool in this portfolio is a CLI because each one wraps a
+command, a file, or a config a human or CI job invokes directly. `clicked`
+instruments one interaction inside a caller's *own* Playwright script --
+there's nothing to invoke from a shell that isn't already that script.
+The receipt itself is a Providence bundle either way (`c.to_dict()` /
+`c.write(path)`), so it plugs into the same evidence pipeline as
+everything else in this portfolio without needing its own entry point.
+
+## Playwright is never imported here
+
+`capture()` only calls `.on()` and `.remove_listener()` on whatever object
+you pass it -- duck-typed, not a hard dependency on Playwright or any
+particular version of it. `receipt-evidence` is the one real dependency
+this package has -- a hard one, not an extra, because redaction (above)
+is part of the core network-capture path, not an opt-in feature; it's
+also itself dependency-free, so this stays a light install either way.
+
+## Tests
+
+```
+pip install -e "."
+python tests/test_capture.py         # pure logic, a fake page object, no browser needed
+```
+
+```
+pip install -e "." playwright
+python -m playwright install chromium
+python tests/test_capture_live.py    # real Chromium, real HTTP server, real network + filesystem effects
+```
+
+17 tests total (13 + 4). The live suite is the one that actually matters
+for a package whose whole point is "did this really happen" -- it skips
+cleanly, rather than failing, if Playwright or its browser binary isn't
+installed.
+
+MIT licensed.

clicked_evidence-0.1.0/README.md

@@ -0,0 +1,142 @@
+# clicked
+
+[![ci](https://github.com/MaXiMo000/clicked/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/clicked/actions/workflows/ci.yml)
+
+**Prove what one browser interaction actually did -- every network
+request it made, and optionally what changed on a local backing store.**
+
+[`receipt`](https://github.com/MaXiMo000/receipt) proves what a shell
+command touched. [`custody`](https://github.com/MaXiMo000/custody) proves
+what an AI agent's tool call touched. `clicked` proves what a *click*
+touched -- the same "verified execution, not just self-report" idea, one
+layer up: a browser-automation test that asserts "clicking Save sends the
+right request" is trusting the test's own assumption unless something
+independently recorded what the browser actually sent.
+
+```python
+from clicked import capture
+
+with capture(page, task="click save button") as c:
+    page.click("#save")
+    page.wait_for_timeout(200)
+
+print(c.to_dict())
+```
+
+```json
+{
+  "providence_version": 1,
+  "tool": "clicked",
+  "payload": {
+    "task": "click save button",
+    "seconds": 0.324,
+    "requests": [
+      {"url": "http://127.0.0.1:60672/api/save", "method": "POST",
+       "post_data": "{\"name\":\"ada\"}", "status": 200, "failure": null}
+    ],
+    "raised": null
+  },
+  "sha256": "ed727efcdccbc..."
+}
+```
+
+(Real output, from `tests/test_capture_live.py` -- a real headless
+Chromium, clicking a real button, against a real local HTTP server.)
+
+## Install
+
+```
+pip install clicked-evidence
+```
+
+For once, no PyPI name-squatting to work around -- both `clicked` and
+`clicked-evidence` were actually free.
+
+## Use
+
+`capture()` takes any Playwright `Page` object and a `task` description.
+Everything inside the `with` block is one interaction:
+
+```python
+from clicked import capture
+
+with capture(page, task="delete account button") as c:
+    page.click("#delete-account-button")
+    page.wait_for_load_state("networkidle")
+
+c.write("receipt.json")   # a Providence bundle -- see below
+```
+
+`c.requests` is every network request/response pair that happened during
+the block (URL, method, POST body, status, or a `failure` reason if the
+request never got a response at all). This is what was actually sent and
+actually came back -- not what the page's own JavaScript claims it sent.
+
+## Redaction
+
+`url` and `post_data` are swept through
+[`receipt.redact`](https://github.com/MaXiMo000/receipt) before being
+stored -- a real interaction routinely carries a credential in a query
+string (`?api_key=...`) or a form/JSON POST body (`{"password": "..."}`),
+and a receipt is meant to be kept and handed to someone else as evidence,
+not a second place that credential now lives. Same regex-based, best-
+effort sweep `receipt` and `custody` already use, not exhaustive -- see
+receipt's own README for what it doesn't catch.
+
+### Watching the filesystem too
+
+Pass `watch_dir` to also snapshot-diff a local directory before and after
+the interaction, reusing `receipt.snapshot`'s real `snapshot()`/`diff()`
+core directly (not reimplemented):
+
+```python
+with capture(page, task="click save button", watch_dir="./data") as c:
+    page.click("#save")
+    page.wait_for_timeout(200)
+
+print(c.result["changes"])  # {"added": ["saved.json"], "modified": [], ...}
+```
+
+This closes the loop from *client* interaction to *backend* side effect --
+proving the click didn't just send a request that returned 200, but that
+a real file actually landed on disk because of it. `watch_dir=None` (the
+default) skips this step entirely; no extra install needed either way.
+
+### Why no CLI
+
+Every other tool in this portfolio is a CLI because each one wraps a
+command, a file, or a config a human or CI job invokes directly. `clicked`
+instruments one interaction inside a caller's *own* Playwright script --
+there's nothing to invoke from a shell that isn't already that script.
+The receipt itself is a Providence bundle either way (`c.to_dict()` /
+`c.write(path)`), so it plugs into the same evidence pipeline as
+everything else in this portfolio without needing its own entry point.
+
+## Playwright is never imported here
+
+`capture()` only calls `.on()` and `.remove_listener()` on whatever object
+you pass it -- duck-typed, not a hard dependency on Playwright or any
+particular version of it. `receipt-evidence` is the one real dependency
+this package has -- a hard one, not an extra, because redaction (above)
+is part of the core network-capture path, not an opt-in feature; it's
+also itself dependency-free, so this stays a light install either way.
+
+## Tests
+
+```
+pip install -e "."
+python tests/test_capture.py         # pure logic, a fake page object, no browser needed
+```
+
+```
+pip install -e "." playwright
+python -m playwright install chromium
+python tests/test_capture_live.py    # real Chromium, real HTTP server, real network + filesystem effects
+```
+
+17 tests total (13 + 4). The live suite is the one that actually matters
+for a package whose whole point is "did this really happen" -- it skips
+cleanly, rather than failing, if Playwright or its browser binary isn't
+installed.
+
+MIT licensed.

clicked_evidence-0.1.0/clicked/__init__.py

@@ -0,0 +1,4 @@
+from .capture import Capture, capture
+
+__version__ = "0.1.0"
+__all__ = ["capture", "Capture"]

clicked_evidence-0.1.0/clicked/capture.py

@@ -0,0 +1,142 @@
+"""Prove what one browser interaction actually did -- not just what
+devtools show changed in the DOM, but every network request it made, and
+optionally what changed on a local filesystem/backing store. The same
+"verified execution, not just self-report" idea `receipt` proves for a
+shell command and `custody` proves for an AI agent's tool call, applied
+here to a click, a form submit, any one interaction with a real page.
+
+Works with any Playwright `Page` object. Playwright itself is never
+imported here -- everything is duck-typed against the object passed in
+(`.on()`, `.remove_listener()`), so this package has zero hard dependency
+on which version of Playwright (or, in principle, another automation
+library exposing the same two methods) the caller happens to be using.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+
+from receipt.redact import redact
+from receipt.snapshot import diff as _diff
+from receipt.snapshot import snapshot as _snapshot
+
+# receipt-evidence is a hard dependency (see pyproject.toml) precisely
+# because of redact() above: a captured URL or POST body can carry a
+# real credential (an API key in a query string, a password in a form
+# submit), and that's not something a caller should have to opt into
+# safety for by installing an extra. snapshot()/diff() ride along on the
+# same dependency for the optional watch_dir feature.
+
+
+def _safe(getter):
+    """A Playwright accessor can itself raise (a request object's fields
+    aren't always populated depending on when in its lifecycle it's read)
+    -- never let reading one piece of metadata lose the rest of the
+    record."""
+    try:
+        return getter()
+    except Exception:  # noqa: BLE001
+        return None
+
+
+class Capture:
+    """One receipt, for one browser interaction.
+
+    with capture(page, task="delete account button") as c:
+        page.click("#delete-account-button")
+        page.wait_for_load_state("networkidle")
+    print(c.to_dict())
+    """
+
+    def __init__(self, page, task: str, watch_dir: str | None = None):
+        self.page = page
+        self.task = task
+        self.watch_dir = watch_dir
+        self.requests: list[dict] = []
+        self.result: dict | None = None
+        self._started: float | None = None
+        self._before_snapshot: dict | None = None
+
+    def _on_response(self, response) -> None:
+        # url and post_data are redacted -- a real interaction can easily
+        # carry an API key in a query string or a password in a form
+        # submit, and a receipt is meant to be kept and handed to someone
+        # else as evidence, not a second place that credential now lives.
+        req = response.request
+        self.requests.append({
+            "url": redact(_safe(lambda: req.url)),
+            "method": _safe(lambda: req.method),
+            "post_data": redact(_safe(lambda: req.post_data)),
+            "resource_type": _safe(lambda: req.resource_type),
+            "status": _safe(lambda: response.status),
+            "failure": None,
+        })
+
+    def _on_request_failed(self, request) -> None:
+        # A request that never got a response at all (DNS failure, aborted,
+        # blocked) -- recorded separately from _on_response so a network
+        # error during the interaction is on the record too, not silently
+        # absent because there was never a response to hang it off of.
+        self.requests.append({
+            "url": redact(_safe(lambda: request.url)),
+            "method": _safe(lambda: request.method),
+            "post_data": redact(_safe(lambda: request.post_data)),
+            "resource_type": _safe(lambda: request.resource_type),
+            "status": None,
+            "failure": _safe(lambda: request.failure),
+        })
+
+    def __enter__(self) -> Capture:
+        self._started = time.time()
+        if self.watch_dir and _snapshot:
+            self._before_snapshot = _snapshot(self.watch_dir)
+        self.page.on("response", self._on_response)
+        self.page.on("requestfailed", self._on_request_failed)
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        self.page.remove_listener("response", self._on_response)
+        self.page.remove_listener("requestfailed", self._on_request_failed)
+
+        payload = {
+            "task": self.task,
+            "seconds": round(time.time() - self._started, 3),
+            "requests": self.requests,
+            "raised": None if exc_type is None else f"{exc_type.__name__}: {exc}",
+        }
+        if self.watch_dir and _snapshot:
+            after = _snapshot(self.watch_dir)
+            payload["changes"] = _diff(self._before_snapshot, after)
+
+        self.result = payload
+        return False  # never suppress the exception -- a receipt records a failure, it doesn't hide one
+
+    def to_dict(self) -> dict:
+        if self.result is None:
+            raise RuntimeError("capture() hasn't exited its `with` block yet")
+        return to_providence_bundle(self.result)
+
+    def write(self, path: str) -> None:
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(self.to_dict(), f, indent=2)
+
+
+def capture(page, task: str, watch_dir: str | None = None) -> Capture:
+    return Capture(page, task, watch_dir)
+
+
+def to_providence_bundle(payload: dict, tool: str = "clicked") -> dict:
+    """A single-file Providence bundle (see
+    https://github.com/MaXiMo000/providence's SPEC.md), written by hand to
+    its documented recipe -- same approach custody takes, for the same
+    reason: providence-evidence wasn't published to PyPI when this was
+    written."""
+    blob = json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str).encode()
+    return {
+        "providence_version": 1,
+        "generated_at": time.time(),
+        "tool": tool,
+        "payload": payload,
+        "sha256": hashlib.sha256(blob).hexdigest(),
+    }

clicked_evidence-0.1.0/clicked_evidence.egg-info/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: clicked-evidence
+Version: 0.1.0
+Summary: Prove what one browser interaction actually did -- every network request it made, and optionally what changed on a local backing store.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MaXiMo000/clicked
+Project-URL: Source, https://github.com/MaXiMo000/clicked
+Project-URL: Issues, https://github.com/MaXiMo000/clicked/issues
+Project-URL: Changelog, https://github.com/MaXiMo000/clicked/releases
+Keywords: browser,playwright,testing,evidence,provenance,e2e
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: receipt-evidence>=0.1.1
+Dynamic: license-file
+
+# clicked
+
+[![ci](https://github.com/MaXiMo000/clicked/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/clicked/actions/workflows/ci.yml)
+
+**Prove what one browser interaction actually did -- every network
+request it made, and optionally what changed on a local backing store.**
+
+[`receipt`](https://github.com/MaXiMo000/receipt) proves what a shell
+command touched. [`custody`](https://github.com/MaXiMo000/custody) proves
+what an AI agent's tool call touched. `clicked` proves what a *click*
+touched -- the same "verified execution, not just self-report" idea, one
+layer up: a browser-automation test that asserts "clicking Save sends the
+right request" is trusting the test's own assumption unless something
+independently recorded what the browser actually sent.
+
+```python
+from clicked import capture
+
+with capture(page, task="click save button") as c:
+    page.click("#save")
+    page.wait_for_timeout(200)
+
+print(c.to_dict())
+```
+
+```json
+{
+  "providence_version": 1,
+  "tool": "clicked",
+  "payload": {
+    "task": "click save button",
+    "seconds": 0.324,
+    "requests": [
+      {"url": "http://127.0.0.1:60672/api/save", "method": "POST",
+       "post_data": "{\"name\":\"ada\"}", "status": 200, "failure": null}
+    ],
+    "raised": null
+  },
+  "sha256": "ed727efcdccbc..."
+}
+```
+
+(Real output, from `tests/test_capture_live.py` -- a real headless
+Chromium, clicking a real button, against a real local HTTP server.)
+
+## Install
+
+```
+pip install clicked-evidence
+```
+
+For once, no PyPI name-squatting to work around -- both `clicked` and
+`clicked-evidence` were actually free.
+
+## Use
+
+`capture()` takes any Playwright `Page` object and a `task` description.
+Everything inside the `with` block is one interaction:
+
+```python
+from clicked import capture
+
+with capture(page, task="delete account button") as c:
+    page.click("#delete-account-button")
+    page.wait_for_load_state("networkidle")
+
+c.write("receipt.json")   # a Providence bundle -- see below
+```
+
+`c.requests` is every network request/response pair that happened during
+the block (URL, method, POST body, status, or a `failure` reason if the
+request never got a response at all). This is what was actually sent and
+actually came back -- not what the page's own JavaScript claims it sent.
+
+## Redaction
+
+`url` and `post_data` are swept through
+[`receipt.redact`](https://github.com/MaXiMo000/receipt) before being
+stored -- a real interaction routinely carries a credential in a query
+string (`?api_key=...`) or a form/JSON POST body (`{"password": "..."}`),
+and a receipt is meant to be kept and handed to someone else as evidence,
+not a second place that credential now lives. Same regex-based, best-
+effort sweep `receipt` and `custody` already use, not exhaustive -- see
+receipt's own README for what it doesn't catch.
+
+### Watching the filesystem too
+
+Pass `watch_dir` to also snapshot-diff a local directory before and after
+the interaction, reusing `receipt.snapshot`'s real `snapshot()`/`diff()`
+core directly (not reimplemented):
+
+```python
+with capture(page, task="click save button", watch_dir="./data") as c:
+    page.click("#save")
+    page.wait_for_timeout(200)
+
+print(c.result["changes"])  # {"added": ["saved.json"], "modified": [], ...}
+```
+
+This closes the loop from *client* interaction to *backend* side effect --
+proving the click didn't just send a request that returned 200, but that
+a real file actually landed on disk because of it. `watch_dir=None` (the
+default) skips this step entirely; no extra install needed either way.
+
+### Why no CLI
+
+Every other tool in this portfolio is a CLI because each one wraps a
+command, a file, or a config a human or CI job invokes directly. `clicked`
+instruments one interaction inside a caller's *own* Playwright script --
+there's nothing to invoke from a shell that isn't already that script.
+The receipt itself is a Providence bundle either way (`c.to_dict()` /
+`c.write(path)`), so it plugs into the same evidence pipeline as
+everything else in this portfolio without needing its own entry point.
+
+## Playwright is never imported here
+
+`capture()` only calls `.on()` and `.remove_listener()` on whatever object
+you pass it -- duck-typed, not a hard dependency on Playwright or any
+particular version of it. `receipt-evidence` is the one real dependency
+this package has -- a hard one, not an extra, because redaction (above)
+is part of the core network-capture path, not an opt-in feature; it's
+also itself dependency-free, so this stays a light install either way.
+
+## Tests
+
+```
+pip install -e "."
+python tests/test_capture.py         # pure logic, a fake page object, no browser needed
+```
+
+```
+pip install -e "." playwright
+python -m playwright install chromium
+python tests/test_capture_live.py    # real Chromium, real HTTP server, real network + filesystem effects
+```
+
+17 tests total (13 + 4). The live suite is the one that actually matters
+for a package whose whole point is "did this really happen" -- it skips
+cleanly, rather than failing, if Playwright or its browser binary isn't
+installed.
+
+MIT licensed.

clicked_evidence-0.1.0/clicked_evidence.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+clicked/__init__.py
+clicked/capture.py
+clicked_evidence.egg-info/PKG-INFO
+clicked_evidence.egg-info/SOURCES.txt
+clicked_evidence.egg-info/dependency_links.txt
+clicked_evidence.egg-info/requires.txt
+clicked_evidence.egg-info/top_level.txt
+tests/test_capture.py
+tests/test_capture_live.py

clicked_evidence-0.1.0/clicked_evidence.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

clicked_evidence-0.1.0/clicked_evidence.egg-info/requires.txt

@@ -0,0 +1 @@
+receipt-evidence>=0.1.1

clicked_evidence-0.1.0/clicked_evidence.egg-info/top_level.txt

@@ -0,0 +1 @@
+clicked

clicked_evidence-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+# "clicked" and "clicked-evidence" were both actually available on PyPI --
+# no squatting to work around here, for once. The installed package stays
+# `clicked` either way (an installed *command* isn't relevant: this is a
+# library, imported from a caller's own browser-automation script, not a
+# CLI tool -- see README's "Why no CLI").
+name = "clicked-evidence"
+version = "0.1.0"
+description = "Prove what one browser interaction actually did -- every network request it made, and optionally what changed on a local backing store."
+requires-python = ">=3.10"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["browser", "playwright", "testing", "evidence", "provenance", "e2e"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Testing",
+]
+# Playwright is duck-typed, never imported here, so whichever version (or,
+# in principle, another library with the same .on()/.remove_listener()
+# shape) the caller already depends on is used as-is. receipt-evidence is
+# the one real dependency this package has -- it's a hard one, not an
+# extra, because capture()'s core network recording redacts every URL and
+# POST body through receipt.redact before storing it (a credential in a
+# query string or form submit is a real, common shape, not an edge case),
+# and that safety shouldn't be something a caller has to opt into by
+# installing an extra. receipt-evidence is itself dependency-free, so this
+# stays a light install. snapshot()/diff() ride along on the same
+# dependency for the optional watch_dir feature.
+dependencies = ["receipt-evidence>=0.1.1"]  # 0.1.1: redact.py's quoted-key fix, needed for JSON POST bodies
+
+urls.Homepage = "https://github.com/MaXiMo000/clicked"
+urls.Source = "https://github.com/MaXiMo000/clicked"
+urls.Issues = "https://github.com/MaXiMo000/clicked/issues"
+urls.Changelog = "https://github.com/MaXiMo000/clicked/releases"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["clicked*"]

clicked_evidence-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

clicked_evidence-0.1.0/tests/test_capture.py

@@ -0,0 +1,172 @@
+"""Run: python tests/test_capture.py
+
+Pure logic, against a fake page object exposing just the two methods
+Capture actually calls (`.on()`, `.remove_listener()`) -- no real browser
+needed here. test_capture_live.py is the real-Playwright end-to-end
+counterpart.
+"""
+from __future__ import annotations
+
+import pathlib
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from clicked.capture import capture
+
+
+class FakePage:
+    """Mimics just enough of Playwright's Page event API to drive Capture
+    without a real browser: .on()/.remove_listener() register/unregister
+    handlers by event name, and _fire() simulates the browser calling them."""
+
+    def __init__(self):
+        self._handlers: dict[str, list] = {}
+
+    def on(self, event, handler):
+        self._handlers.setdefault(event, []).append(handler)
+
+    def remove_listener(self, event, handler):
+        self._handlers[event].remove(handler)
+
+    def _fire(self, event, arg):
+        for h in list(self._handlers.get(event, [])):
+            h(arg)
+
+
+class FakeRequest:
+    def __init__(self, url, method="GET", post_data=None, resource_type="fetch", failure=None):
+        self.url, self.method, self.post_data = url, method, post_data
+        self.resource_type, self.failure = resource_type, failure
+
+
+class FakeResponse:
+    def __init__(self, request, status=200):
+        self.request, self.status = request, status
+
+
+class TestCapture(unittest.TestCase):
+    def test_a_single_response_is_recorded(self):
+        page = FakePage()
+        with capture(page, task="click submit") as c:
+            page._fire("response", FakeResponse(FakeRequest("https://api.example.com/orders", "POST")))
+        self.assertEqual(len(c.requests), 1)
+        self.assertEqual(c.requests[0]["url"], "https://api.example.com/orders")
+        self.assertEqual(c.requests[0]["method"], "POST")
+        self.assertEqual(c.requests[0]["status"], 200)
+
+    def test_multiple_responses_during_one_interaction_are_all_recorded(self):
+        page = FakePage()
+        with capture(page, task="load dashboard") as c:
+            page._fire("response", FakeResponse(FakeRequest("https://a.example.com/1")))
+            page._fire("response", FakeResponse(FakeRequest("https://a.example.com/2")))
+        self.assertEqual(len(c.requests), 2)
+
+    def test_a_credential_in_the_url_is_redacted(self):
+        # Real leak shape: an API key passed as a query param, or a DSN-style
+        # credentialed URL -- the exact bug class receipt.redact exists for.
+        page = FakePage()
+        with capture(page, task="load report") as c:
+            page._fire("response", FakeResponse(FakeRequest(
+                "https://api.example.com/report?api_key=sk-supersecret12345")))
+        self.assertNotIn("sk-supersecret12345", c.requests[0]["url"])
+        self.assertIn("[REDACTED]", c.requests[0]["url"])
+
+    def test_a_credential_in_post_data_is_redacted(self):
+        page = FakePage()
+        with capture(page, task="log in") as c:
+            page._fire("response", FakeResponse(FakeRequest(
+                "https://api.example.com/login", "POST",
+                post_data='{"password": "hunter2trombone"}')))
+        self.assertNotIn("hunter2trombone", c.requests[0]["post_data"])
+
+    def test_a_failed_requests_url_and_post_data_are_also_redacted(self):
+        # _on_request_failed is a separate code path from _on_response --
+        # a fix to one alone would leave the other leaking.
+        page = FakePage()
+        with capture(page, task="submit") as c:
+            page._fire("requestfailed", FakeRequest(
+                "https://api.example.com/x?token=ghp_abcdefghijklmnopqrst1234",
+                post_data="PASSWORD=hunter2trombone",
+                failure="net::ERR_FAILED"))
+        self.assertNotIn("ghp_abcdefghijklmnopqrst1234", c.requests[0]["url"])
+        self.assertNotIn("hunter2trombone", c.requests[0]["post_data"])
+
+    def test_a_url_with_no_credential_is_left_unredacted(self):
+        page = FakePage()
+        with capture(page, task="browse") as c:
+            page._fire("response", FakeResponse(FakeRequest("https://example.com/orders/42")))
+        self.assertEqual(c.requests[0]["url"], "https://example.com/orders/42")
+
+    def test_a_failed_request_is_recorded_with_no_status(self):
+        page = FakePage()
+        with capture(page, task="submit form") as c:
+            page._fire("requestfailed", FakeRequest("https://gone.example.com/x", failure="net::ERR_NAME_NOT_RESOLVED"))
+        self.assertEqual(c.requests[0]["status"], None)
+        self.assertEqual(c.requests[0]["failure"], "net::ERR_NAME_NOT_RESOLVED")
+
+    def test_listeners_are_removed_after_the_with_block(self):
+        """A response firing after the interaction is over must not sneak
+        into a receipt that already claims to be closed."""
+        page = FakePage()
+        with capture(page, task="x") as c:
+            page._fire("response", FakeResponse(FakeRequest("https://a.example.com/during")))
+        page._fire("response", FakeResponse(FakeRequest("https://a.example.com/after")))
+        self.assertEqual(len(c.requests), 1)
+        self.assertEqual(c.requests[0]["url"], "https://a.example.com/during")
+
+    def test_an_exception_inside_the_with_block_is_recorded_not_swallowed(self):
+        page = FakePage()
+        c = capture(page, task="risky click")
+        with self.assertRaises(ValueError):
+            with c:
+                raise ValueError("the click handler itself threw")
+        self.assertIn("the click handler itself threw", c.result["raised"])
+
+    def test_filesystem_changes_before_an_exception_are_still_captured(self):
+        """A receipt records what happened, including a failure -- it
+        doesn't lose the evidence of what changed before the failure."""
+        with tempfile.TemporaryDirectory() as d:
+            watch_dir = pathlib.Path(d)
+            page = FakePage()
+            c = capture(page, task="x", watch_dir=str(watch_dir))
+            with self.assertRaises(RuntimeError):
+                with c:
+                    (watch_dir / "new.txt").write_text("hi")
+                    raise RuntimeError("boom")
+            self.assertIn("RuntimeError: boom", c.result["raised"])
+            self.assertIn("new.txt", c.result["changes"]["added"])
+
+    def test_to_dict_before_the_with_block_exits_is_an_error(self):
+        page = FakePage()
+        c = capture(page, task="x")
+        with self.assertRaises(RuntimeError):
+            c.to_dict()
+
+    def test_to_dict_is_a_conformant_providence_bundle(self):
+        page = FakePage()
+        with capture(page, task="x") as c:
+            pass
+        bundle = c.to_dict()
+        self.assertEqual(bundle["providence_version"], 1)
+        self.assertEqual(bundle["tool"], "clicked")
+        self.assertEqual(bundle["payload"]["task"], "x")
+        self.assertIn("sha256", bundle)
+
+    def test_write_produces_a_real_file_providence_check_can_validate(self):
+        page = FakePage()
+        with capture(page, task="x") as c:
+            page._fire("response", FakeResponse(FakeRequest("https://a.example.com/1")))
+
+        with tempfile.TemporaryDirectory() as d:
+            out = str(pathlib.Path(d) / "receipt.json")
+            c.write(out)
+            import json
+            doc = json.loads(pathlib.Path(out).read_text())
+            self.assertEqual(doc["providence_version"], 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

clicked_evidence-0.1.0/tests/test_capture_live.py

@@ -0,0 +1,164 @@
+"""Run: python tests/test_capture_live.py
+
+Real Playwright, a real headless Chromium, a real local HTTP server --
+not mocked. This is the actual point of the package: proving it captures
+what a real browser really did, not just that fake event objects fan out
+to the right handlers (test_capture.py already covers that).
+
+Requires `pip install playwright && playwright install chromium` --
+skipped cleanly (not failed) if either isn't available, the same "can't
+verify, don't guess" discipline as every unverified path elsewhere in
+this portfolio.
+"""
+from __future__ import annotations
+
+import http.server
+import json
+import pathlib
+import sys
+import tempfile
+import threading
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+try:
+    from playwright.sync_api import sync_playwright
+    _PLAYWRIGHT_AVAILABLE = True
+except ImportError:
+    _PLAYWRIGHT_AVAILABLE = False
+
+from clicked.capture import capture
+
+_PAGE_HTML = b"""<!doctype html><html><body>
+<button id="save" onclick="save()">Save</button>
+<button id="login" onclick="login()">Login</button>
+<script>
+async function save() {
+  await fetch('/api/save', {
+    method: 'POST',
+    headers: {'Content-Type': 'application/json'},
+    body: JSON.stringify({name: 'ada'}),
+  });
+}
+async function login() {
+  await fetch('/api/login?api_key=sk-realtestsecret12345', {
+    method: 'POST',
+    headers: {'Content-Type': 'application/json'},
+    body: JSON.stringify({user: 'ada', password: 'hunter2trombone'}),
+  });
+}
+</script>
+</body></html>"""
+
+
+def _make_handler(write_dir: pathlib.Path):
+    class Handler(http.server.BaseHTTPRequestHandler):
+        def log_message(self, *a):
+            pass  # keep test output clean
+
+        def do_GET(self):
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html")
+            self.end_headers()
+            self.wfile.write(_PAGE_HTML)
+
+        def do_POST(self):
+            length = int(self.headers.get("Content-Length", 0))
+            body = self.rfile.read(length)
+            if self.path == "/api/save":
+                # The real side effect being proven here: a click leads to
+                # a network request leads to a file actually being written.
+                (write_dir / "saved.json").write_bytes(body)
+                self.send_response(200)
+                self.send_header("Content-Type", "application/json")
+                self.end_headers()
+                self.wfile.write(b'{"ok": true}')
+            elif self.path.startswith("/api/login"):
+                self.send_response(200)
+                self.send_header("Content-Type", "application/json")
+                self.end_headers()
+                self.wfile.write(b'{"ok": true}')
+            else:
+                self.send_response(404)
+                self.end_headers()
+
+    return Handler
+
+
+@unittest.skipUnless(_PLAYWRIGHT_AVAILABLE, "playwright not installed -- skipped, not failed")
+class TestCaptureLive(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.watch_dir = pathlib.Path(self.tmp.name)
+        self.server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), _make_handler(self.watch_dir))
+        self.port = self.server.server_address[1]
+        self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
+        self.thread.start()
+
+        self.playwright = sync_playwright().start()
+        self.browser = self.playwright.chromium.launch()
+        self.page = self.browser.new_page()
+        self.page.goto(f"http://127.0.0.1:{self.port}/")
+
+    def tearDown(self):
+        self.browser.close()
+        self.playwright.stop()
+        self.server.shutdown()
+        self.thread.join()
+        self.tmp.cleanup()
+
+    def test_a_real_click_that_fires_a_real_fetch_is_captured(self):
+        with capture(self.page, task="click save button") as c:
+            self.page.click("#save")
+            self.page.wait_for_timeout(200)  # let the fetch actually complete
+
+        api_calls = [r for r in c.requests if r["url"].endswith("/api/save")]
+        self.assertEqual(len(api_calls), 1)
+        self.assertEqual(api_calls[0]["method"], "POST")
+        self.assertEqual(api_calls[0]["status"], 200)
+        # The real POST body the browser actually sent -- not asserted
+        # from the page's own JS, read back from what the browser did.
+        self.assertEqual(json.loads(api_calls[0]["post_data"]), {"name": "ada"})
+
+    def test_the_real_filesystem_side_effect_of_the_click_is_diffed(self):
+        """The click causes the *server* to write a real file -- proving
+        this isn't just DOM/network observation, it closes the loop to an
+        actual backend side effect, the same "verified execution" idea
+        receipt/custody already prove for a shell command / tool call."""
+        self.assertFalse((self.watch_dir / "saved.json").exists())
+
+        with capture(self.page, task="click save button", watch_dir=str(self.watch_dir)) as c:
+            self.page.click("#save")
+            self.page.wait_for_timeout(200)
+
+        self.assertTrue((self.watch_dir / "saved.json").exists())
+        self.assertIn("saved.json", c.result["changes"]["added"])
+
+    def test_a_real_credential_a_real_browser_actually_sent_is_redacted(self):
+        """A real Chromium, a real fetch, with a real (test) API key in the
+        URL and a real password in the JSON POST body -- the exact leak
+        shape the audit found capture() had zero redaction for. Checks
+        the captured output, not the page's own JS, since the whole
+        point of this package is not trusting self-report."""
+        with capture(self.page, task="login") as c:
+            self.page.click("#login")
+            self.page.wait_for_timeout(200)
+
+        login_calls = [r for r in c.requests if "/api/login" in r["url"]]
+        self.assertEqual(len(login_calls), 1)
+        raw = json.dumps(c.to_dict())
+        self.assertNotIn("sk-realtestsecret12345", raw)
+        self.assertNotIn("hunter2trombone", raw)
+        self.assertIn("[REDACTED]", login_calls[0]["url"])
+        self.assertIn("[REDACTED]", login_calls[0]["post_data"])
+
+    def test_no_interaction_means_no_requests_captured(self):
+        with capture(self.page, task="do nothing") as c:
+            self.page.wait_for_timeout(50)
+        api_calls = [r for r in c.requests if r["url"].endswith("/api/save")]
+        self.assertEqual(api_calls, [])
+
+
+if __name__ == "__main__":
+    unittest.main()