blob: b5e4fe627cf546870e52f325a25ed4867a23da3a [file] [view] [edit]
# Accessibility snapshot corpus
The cross-binding contract for the accessibility snapshot of
[ADR 18205](../../../../docs/decisions/18205-accessibility-tree-snapshot.md).
Every binding runs every page here in each browser it tests and compares its
snapshot to the recorded expectation. The atom's own suite
(`//javascript/atoms:closure-test`, page `accessibility_corpus_typescript_test.html`)
is the first consumer and the thing that records the expectations.
## Layout
```
NNN-name.html the page
NNN-name.expected.json the snapshot of the whole page, as JSON
NNN-name.expected.txt the same snapshot in the text form of ADR §1
NNN-name.expected.full.json the unpruned snapshot (interestingOnly false)
NNN-name.expected.full.txt and its text form
NNN-name.expected[.full].<engine>.json / .txt
only where a divergence is recorded below;
<engine> is chromium, firefox or webkit
index.json the list of page names, in order
```
Each `.html` is a plain page with no test harness. The snapshot is taken of
the whole document, so the root is the `html` element as role `document`
named from the title. Every page is recorded twice: pruned, the default
(ADR §2), and unpruned, with `interestingOnly` false, where every rendered
element produces a node and `generic`, `none` and `presentation` are kept.
## Conventions
- Every rendered element carries an `id`, since every one appears in the
unpruned form. `expected.json` stores `"element": "<id>"`; a binding maps
each reference it gets back to its id with one `getAttribute("id")` call.
Text leaves have no `element` key. The root `html` element has `id="root"`
and the body `id="body"`.
- Links use absolute `https://example.com/...` hrefs, so the `url` a link
node records does not depend on where the corpus is served from.
- Empty `description` and `states` are still written (`""` and `{}`), so the
JSON matches `javascript/atoms/typescript/accessibility-node.schema.json`
literally. `//javascript/atoms:accessibility-corpus-consistent` checks
every expectation against that schema and checks that each `.txt` is the
renderer's output over its `.json`.
- `expected.txt` is produced by the reference renderer
(`javascript/atoms/typescript/testing/accessibility-text.ts`), never by
hand. The bindings' `toText` ports are held to these files.
- Pages must be deterministic across engines: no focus, no user-agent text,
no timing. Images use `../map.png` from this directory's parent.
## Adding or re-recording a page
1. Add `NNN-name.html` and its name to `index.json`.
2. Run the atom's debug server and open the corpus runner in record mode:
```sh
bazel run //javascript/atoms:closure-test_debug_server
# http://localhost:2310/filez/_main/javascript/atoms/test/accessibility_corpus_typescript_test.html?record=1
```
The page shows the JSON and text it computed for every corpus page, in
both forms; copy them into the `.expected.json`, `.expected.txt`,
`.expected.full.json` and `.expected.full.txt` files.
3. Run the corpus page in every browser:
```sh
bazel test //javascript/atoms:closure-test{,-chrome,-edge,-safari} --test_filter=accessibility_corpus_typescript_test
```
## Known divergences
Where an engine computes something different from the recorded expectation
and the difference is the engine's rather than a bug in the atom, record an
engine-specific expectation file and list it here with the reason.
_None recorded yet._