UX Evidence Auditor — Website UX & Regression API

Audit public web pages on desktop and mobile with reproducible, non-AI checks. Every finding includes a stable issue ID, affected selector, measured evidence, severity, methodology, and recommendation.

Use this Actor for release checks, scheduled UX monitoring, agency QA, technical SEO workflows, and machine-readable evidence for agents or CI.

What it checks

The Actor combines two deterministic layers:

• WCAG 2.x A/AA checks from axe-core, including accessible names, labels, language, document title, alternative text, ARIA validity, contrast, and other rules that can be decided automatically.
• Browser-rendered UX checks for horizontal overflow, mobile viewport metadata, undersized and crowded touch targets, very small leaf text, broken images, heading hierarchy, main landmarks, and HTTP errors.

The touch-target check follows the WCAG 2.2 minimum of 24 × 24 CSS pixels plus spacing geometry. Exceptions that require context are named in the finding instead of being silently treated as certain failures.

To keep results usable, the Dataset contains at most 10 element examples per rule and viewport. Repeated instances do not multiply the score penalty.

Try it

{
  "startUrls": [{ "url": "https://example.com" }],
  "auditDesktop": true,
  "auditMobile": true
}

One Dataset item is produced for each page × viewport audit. A failed page is isolated as a status: "failed" item so other URLs can still finish.

Useful options:

• saveScreenshots stores one JPEG of the visible viewport per audit. Screenshots provide visual evidence and do not affect findings or scoring.
• waitAfterLoadMs gives client-rendered interfaces time to settle.
• maxPages and maxConcurrency control run size. Effective concurrency is capped at roughly one browser page per 1 GB of Actor memory.
• monitorKey compares stable issue IDs with a previous run.
• updateBaseline saves the current IDs as the next regression baseline.

Only public HTTP(S) pages are accepted. URLs with credentials, local/private/reserved targets, and hostnames resolving to private networks are blocked. Login sessions, cookies, CAPTCHA bypass, and private-network auditing are intentionally unsupported.

Output

{
  "status": "ok",
  "url": "https://example.com/checkout",
  "finalUrl": "https://example.com/checkout",
  "httpStatus": 200,
  "viewport": "mobile",
  "score": 76,
  "issueCount": 4,
  "issues": [
    {
      "issueId": "touch_target_size-ef452bb1e13d8d2a",
      "ruleId": "TOUCH_TARGET_SIZE",
      "severity": "minor",
      "selector": "main > form > button:nth-of-type(1)",
      "bbox": { "x": 24, "y": 612, "width": 18, "height": 18 },
      "metrics": { "widthPx": 18, "heightPx": 18, "minimumPx": 24 },
      "methodology": "Automated geometry check for WCAG 2.2 SC 2.5.8; exceptions may require review"
    }
  ],
  "coverage": {
    "customRulesEvaluated": 8,
    "axeViolationRules": 1,
    "axePassedRules": 22,
    "axeIncompleteRules": 2,
    "axeInapplicableRules": 31
  },
  "regression": {
    "baselineFound": true,
    "newIssueIds": ["touch_target_size-ef452bb1e13d8d2a"],
    "resolvedIssueIds": [],
    "persistentIssueIds": []
  },
  "screenshotUrl": "https://api.apify.com/v2/key-value-stores/.../records/...",
  "screenshotFullPage": false,
  "engineVersion": "0.2.0"
}

Viewport screenshots and a compact SUMMARY record are stored in the default Key-value store. Set saveScreenshots to false for machine-only runs that do not need visual evidence.

Regression monitoring

1. Choose a hard-to-guess monitorKey for one site or deployment pipeline.
2. Run with updateBaseline: true to establish the baseline.
3. Reuse the same key and URL set on later runs.
4. Read newIssueIds, resolvedIssueIds, and persistentIssueIds.

Stable IDs use normalized final URL, viewport, rule ID, and DOM selector. A major template refactor can therefore resolve an old selector and introduce a new one.

Scoring

The score is a prioritization aid, not a universal UX grade. Custom rule families have fixed weights; all axe WCAG violations contribute through one accessibility score family so a long page is not punished merely for having more DOM nodes. Critical findings cap the score at 60, and three or more major rule families cap it at 75.

Use issue evidence, axe incomplete counts, and regression diffs for decisions. Do not use the score alone as a compliance claim.

What automation cannot prove

A clean report means that no implemented deterministic rule found a violation. It does not certify WCAG compliance and does not replace:

• moderated usability research or task-completion testing;
• judgment about business goals, persuasion, clarity, or user intent;
• keyboard workflows and interactive states that were not opened during this URL-level run;
• legal accessibility review.

axe-core itself reports cases that need human review. Their count is exposed as coverage.axeIncompleteRules rather than converted into fabricated failures.

Privacy and operational limits

• No screenshot or page content is sent to an AI provider.
• Screenshots remain in the run's Apify storage and are optional.
• The Actor requests only supplied public pages and their public subresources.
• Up to 50 input pages and two viewports are supported per run.
• Each page failure is isolated; the run summary records requested, completed, and failed audits.

Automation examples

• Run after a deployment and alert on new critical issue IDs.
• Schedule weekly desktop/mobile audits in Apify Console.
• Send Dataset items to Make, Zapier, n8n, Google Sheets, Slack, or a webhook.
• Compare a fixed set of landing pages for an agency after each release.

Local development

npm install
npm test
npm run benchmark -- https://example.com/
apify run --purge

The test suite includes unit tests plus a real headless-Chrome fixture for custom and axe-core rules.

Support

Report reproducible bugs and feature requests in the public UX Evidence Auditor support tracker. Include the public URL, viewport, rule ID, and run ID; never post credentials or private page content.