Diagnostic receipts

Diagnostic receipts are an optional, structured artifact for focused investigations. They are separate from pumpo5.log and are disabled by default.

Add this setting to src/test/resources/config.conf when you need receipts:

pn5.diagnostics.enabled=true

When enabled, Pumpo collects receipts in memory and writes one target/reports/{test-name}/diagnostics.jsonl file at the end of a test, whether the test passed or failed. Each line is one JSON object with a schemaVersion, type, operationId, status, timestamp, and fields. No file is created if no producer emits a receipt. The normal log only reports the artifact path.

The recorder limits each test to 256 receipts, each receipt to 16 scalar fields, and each field value to 256 characters. If more receipts arrive, the file ends with a recorder receipt marked truncated. This initial foundation does not yet emit click receipts; a producer must be added for each diagnostic type.

Framework producers can use dev.pumpo5.logging.Diagnostics.record(...). The payload supplier runs only when diagnostics are enabled. Producers must sanitize every field before recording it: do not include raw URLs, query strings, selectors, page content, or secrets. Use stable action identifiers and explicitly redacted route values where needed. Use a shared operationId to correlate receipts from one operation.

As with per-test logging, work on another thread must carry the test's LogContext and finish before the test ends.

Web click receipts

Each @Click dispatch emits one web.click receipt when diagnostics are on. The receipt includes the number of attempts, branch history, the final branch, the located element's stable data-testid and sanitized link path, the observed trusted click target's data-testid, its closest action's data-testid and sanitized link path, and the sanitized route after the click. A failed dispatch also records the exception class. The browser event listener captures the event target; Pumpo does not derive it from the locator or a visual class.

The listener stores a short, operation-specific observation before navigation, which lets Pumpo retrieve it after a same-origin page load. If it cannot observe or retrieve the event, the receipt says no-event or unknown and leaves target fields as unknown. Cross-origin navigation or blocked browser storage can make the event target unknown. Paths omit origins, query strings and fragments; path segments that do not match a short, simple identifier are shown as :redacted. Review application route names before sharing receipts outside the test team.