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.
start_page_audit
Section titled “start_page_audit”See the generated operation reference for arguments. The response is
GraphQL JSON. Read startPageAudit.pageAudit.id and pass that ID to get_page_audit.
get_page_audit
Section titled “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,urlandtitle: the capture and the page it read.titleis null until the capture completes.revision: the capture revision the report reads. It is 1, the page asstart_page_auditcaptured it. Pass it tocreate_page_audit_ticketsandcreate_journey_drafts.status:runningwhile the capture or an analysis step runs, thenfinished.steps:capture,classify,auditandplan, each with astatusand theerrorthat failed it. A step isnot-started,running,completed,failed, orstalewhen it completed on evidence or rules that have since changed, so start a new audit before relying on it. Once nothing is running, anot-startedstep after a completed capture carries the reason inerror.summary: how many checks ended in each status, fromviolationtonot-tested. Null until the audit completes.definite: every violation the recorded evidence proves, each with itscheckId, 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, withreviewsaying who answered, when and why;reviewis 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, andlimitations, what the audit does not cover, such as keyboard use and screen readers.coveragePlan:totalCountsteps, the page’ssections(each anameand itselementIds) andfollowUp. 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.
list_page_audit_items
Section titled “list_page_audit_items”See the generated operation reference for arguments. Pass the
page audit ID as id and one group:
needsReview: checks markedlikely-violationorneeds-review, with the same fields as adefiniteitem except the fix and the review.questionis 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 itsreview.notTested: the checks the capture had no evidence for.coveragePlan: the plan’s steps in order, each with itssection,elementId,action,instructionand what itreveals.
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.
create_page_audit_tickets
Section titled “create_page_audit_tickets”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 itscheckId,ruleandreason.
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.
Drafting journeys from the plan
Section titled “Drafting journeys from the plan”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.