Skip to content

Page audit tools

Four tools for page audits. A page audit captures one URL in a cloud browser, then analyses the capture in three steps: classify sorts the page’s elements, audit checks them against WCAG 2.2, and plan writes the clicks that reveal the rest of the page. The analysis starts on its own once the capture completes.

Page audits require organization membership and the page-audit feature flag.

See the generated operation reference for arguments. The response is GraphQL JSON. Read startPageAudit.pageAudit.id and pass that ID to get_page_audit.

See the generated operation reference for arguments. Pass the page audit ID as id. The response is { pageAudit: { report } }; a missing audit returns { pageAudit: null }. The owner assembles report with these fields:

  • captureId, url and title: the capture and the page it read. title is null until the capture completes.
  • revision: the capture revision the report reads. It is 1, the page as start_page_audit captured it. Pass it to create_page_audit_tickets and create_journey_drafts.
  • status: running while the capture or an analysis step runs, then finished.
  • steps: capture, classify, audit and plan, each with a status and the error that failed it. A step is not-started, running, completed, failed, or stale when it completed on evidence or rules that have since changed, so start a new audit before relying on it. Once nothing is running, a not-started step after a completed capture carries the reason in error.
  • summary: how many checks ended in each status, from violation to not-tested. Null until the audit completes.
  • definite: every violation the recorded evidence proves, each with its checkId, WCAG criterion, level, impact, the element, what is wrong and how to fix it. A check a reviewer answered as failing in the dashboard is here too, with review saying who answered, when and why; review is null for a violation the evidence proves on its own.
  • needsReview: totalCount, how many checks a person still has to settle.
  • resolved: totalCount, how many checks a reviewer answered as passing.
  • notTested: totalCount, how many checks the capture had no evidence for, and limitations, what the audit does not cover, such as keyboard use and screen readers.
  • coveragePlan: totalCount steps, the page’s sections (each a name and its elementIds) and followUp. Null until the plan completes.

The report holds only counts for those four groups, so it stays small enough to read in one reply. Read their items with list_page_audit_items.

Each check’s element comes from the capture’s own element data, so it is present for every rule. It carries the element’s id, tag, role, name and box, and an href reduced to the link’s origin and path. element is null only for a check on the page itself.

The result stays on the page as start_page_audit captured it, even if someone later interacts with that capture in the dashboard.

Poll until status is finished. A step still not-started at that point will not run: a failed capture has nothing to analyse, and any other step says why in its error. Start a new audit in either case.

See the generated operation reference for arguments. Pass the page audit ID as id and one group:

  • needsReview: checks marked likely-violation or needs-review, with the same fields as a definite item except the fix and the review. question is what the person has to answer. These are not defects. Don’t auto-fix them or file them as tickets without confirmation.
  • resolved: checks a reviewer answered as passing, each with its review.
  • notTested: the checks the capture had no evidence for.
  • coveragePlan: the plan’s steps in order, each with its section, elementId, action, instruction and what it reveals.

The response is { pageAuditItems: { totalCount, pageInfo, edges } }, with each item as an edge’s node. A page holds first items, 50 by default and at most 50. Pass pageInfo.endCursor as after while pageInfo.hasNextPage is true. A missing audit returns { pageAuditItems: null }.

Check items come in checkId order, and the cursor names the last item read. When a reviewer answers a needs-review item between two pages, a passing answer moves it to resolved and a failing answer moves it to definite. Either way the next page still starts after the last item you read, so nothing is skipped or read twice. A new analysis of the page refuses an older cursor with PAGE_AUDIT_CURSOR_STALE. Read the group again from its first page.

See the generated operation reference for arguments. Pass the page audit ID as pageAuditId, the project to file into as projectId, and the report’s revision as revision. The project must belong to the page audit’s organization. The dashboard files the revision it shows, which is later than 1 once someone interacts with the capture there; a finding records its revision, so the same check on two revisions is two findings on one ticket.

Only code checks with status violation become tickets: an unnamed control, an image with no text alternative, a control that hides its checked state, and an empty page title. needsReview and notTested items never do. A check a reviewer answered in the dashboard is never filed either: a definite item whose review is not null, and every resolved item, appear in neither tickets nor unfiled. The element’s DOM path identifies it, and an empty page title is identified by the page itself, so filing the same page again, from this audit or a new one, lands on the tickets it already has instead of opening new ones.

The response is { createPageAuditTickets: { newTicketCount, tickets, unfiled } }:

  • tickets: the tickets the violations landed on, each once.
  • newTicketCount: how many of them this call opened. Zero when the page was filed before.
  • unfiled: violations that could not be filed, each with its checkId, rule and reason.

It is refused until that revision’s audit step has finished, and refused with PAGE_AUDIT_STALE when that audit is out of date because its evidence or audit rules changed.

Authorization, feature-flag and read failures return the API error.

create_journey_drafts turns a revision’s coverage plan into draft journeys, one per section. See the generated operation reference for arguments. Pass the page audit ID as pageAuditId, the project as projectId, and the report’s revision as revision. The dashboard drafts the revision it shows, so drafts carry their revision, and each revision of a page audit has its own drafts. Drafting the same revision again returns its drafts. It is refused until that revision’s plan step has completed, with PAGE_AUDIT_PLAN_STALE when that plan is out of date, and with PAGE_AUDIT_PLAN_CHANGED when the revision already has drafts from an earlier plan. Read drafts with list_journey_drafts and accept one with accept_journey_draft.