Skip to content
UxerProof

Documentation

Everything you need to compose and read a Circuit

Written against the current product. Anything that depends on the execution service is marked.

Execution service not connected. Circuit runs shown here are fictional demo data. The isolated browser workers, queues and AI provider integration are added in the next engineering phase. Nothing on this screen was produced by executing a real website.

Terminology

Circuit
A complete test.
AI User
A simulated participant that performs the journey.
Persona
The behaviour definition an AI User follows.
Project
A website or application under test.
Environment
A target deployment of a Project.
Run
An individual execution of a Circuit.
Finding
A discovered problem.
Possibility
An evidence-backed description of what the tested experience could become.
Baseline
An approved comparison state.
Evidence
A supporting artefact captured during a Run.
Proof Score
The overall, fully decomposed result of a Run.

Circuit modes

  • Public Circuit — Unauthenticated journeys across pages anyone can reach.
  • Authenticated Circuit (planned) — Journeys behind sign-in using short-lived, scoped credentials.
  • Role Circuit (planned) — Multi-role journeys that hand off between requester, reviewer and approver.
  • Mobile Circuit (planned) — The same journey replayed at mobile viewports and input modes.
  • Accessibility Circuit (planned) — Keyboard-only, focus order, contrast and semantics checks along the journey.
  • Regression Circuit (planned) — A Circuit replayed against an approved Baseline to detect drift.

Domain verification

Every Environment must prove control of its domain before it can be executed against. DNS TXT is the only verification method accepted in this release:

  1. DNS TXT record

    Add a TXT record at _uxerproof.yourdomain.com containing the token shown in the Environment. Recommended for production.

    _uxerproof.shop.example.com. IN TXT "uxp-verify=8f2c…"

  2. Meta tag

    Add the exact issued tag to the document head of the Environment's root URL. UxerProof does not follow redirects during verification.

    <meta name="uxerproof-verification" content="uxp-verify=8f2c…" />

  3. Well-known file

    Serve the exact issued token as plain text at /.well-known/uxerproof-verification.txt. Useful for preview deployments.

Scheduled daily re-verification, mismatch suspension and a 48-hour execution freshness gate are implemented. The authenticated scheduler still has to be activated in production before external customer execution is enabled.

Composing a Circuit

A Circuit is an ordered list of steps against one Environment, performed by one or more AI Users. Each step declares a kind, an intent and an expectation. Write expectations as outcomes a person could verify, not as selectors.

  • navigate — arrive somewhere.
  • input — provide information.
  • decision — choose between paths.
  • action — commit to something.
  • verify — check what the system says.
  • handoff — pass the journey to another role.

Reading a report

A report contains the Circuit Canvas, the Evidence Timeline, the Findings and the Proof Score. The score decomposes into five dimensions:

  • Completion — Did the AI User reach the intended outcome of the journey?
  • Friction — How much hesitation, backtracking and repeated effort occurred?
  • Clarity — Were labels, states and system responses understandable in context?
  • Accessibility — Keyboard reachability, focus order, naming and contrast along the path.
  • Consistency — Did patterns behave the same way across steps and roles?

See the sample report for a worked example.

Retention

  • Standard retention

    Structured reports, findings and baselines are kept for your plan's retention window. Raw execution artefacts are deleted within 24 hours of report generation.

  • Ephemeral Mode

    Raw screenshots, traces and execution artefacts are deleted immediately after report synthesis. Structured reports and baselines are retained only when you explicitly choose to retain them.

  • No report retention

    You export the report and all run data is scheduled for deletion. Nothing is kept beyond the usage ledger and audit record.

Credits

1 Circuit credit = one normal Circuit run of up to five minutes of execution time. This is a configurable commercial assumption and will be recalibrated once real infrastructure costs are measured. Runs that fail because of platform infrastructure are restored automatically once billing is implemented; a restoration appears in the usage ledger with its own entry type.

API and CI

Workspace owners and admins can create a revocable API key in Settings. A key is shown once, expires after 30, 90 or 365 days, and authorises only the scopes printed beside it. Store it as a masked CI secret—never in source control or workflow logs.

POST /api/v1/circuits/run
Authorization: Bearer $UXERPROOF_API_KEY
Idempotency-Key: build-${GITHUB_RUN_ID}
Content-Type: application/json

{"circuitId":"00000000-0000-4000-8000-000000000000"}

GET /api/v1/runs/{run_id}
Authorization: Bearer $UXERPROOF_API_KEY

Run requests accept only ready Public Circuits with a current DNS proof, an approved Test Contract, available capacity and a positive credit balance. Reusing an idempotency key returns the same Run. Status responses expose only bounded release fields: status, outcome, Proof Score, finding count and timestamps.

Release-gate outcomes

pending
Continue polling with a bounded interval.
pass
The Circuit passed.
warn
The Circuit passed with friction; choose whether CI should block.
fail
The Circuit failed or was blocked; fail the release job.

The full request, response and GitHub Actions contract is maintained in the repository documentation. The API queues authorised work, but external execution remains unavailable until the production runner is enabled.