Zum Inhalt springen

End-to-End-Tests mit Playwright: Frontend, Backend und Datenbank · Teil 12 von 14 der Serie

Teil 12: Barrierefreiheit prüfen mit axe

Lass axe bei jedem Lauf vier Zustände des Quest Boards ansehen, behebe, was es findet, und dann das, was es nicht finden konnte: ein Feld, dessen Beschriftung nie jemand sieht. Ein ARIA-Snapshot hält fest, was ein Screenreader erfährt.

Quest-Ziele

  • Wissen, was axe prüft, und verstehen, warum das ein Teil der Probleme ist und nicht alle
  • Eine Fixture schreiben, die dem Test eine Funktion gibt, damit der Test bestimmt, wann geprüft wird
  • Mehrere Zustände einer Seite prüfen statt nur den ersten, den sie zeigt
  • Einen Fund von axe lesen und beheben
  • Ein Problem erkennen, das keine Regel meldet, mit einem Hinweis aus den eigenen Locators
  • Rollen und Namen einer Seite mit einem ARIA-Snapshot festhalten

Die Suite kann sich einloggen, und alle vier Bereiche sind wieder grün. Bevor die Serie in einer Pipeline endet, ziehen noch zwei Arten von Prüfungen in den Frontend-Bereich ein. Beide brauchen einen Browser und eine Seite in einem Zustand, den der Test bestimmt, und beides gibt es dort schon. Dieser Teil fragt, ob alle das Board benutzen können. Der nächste fragt, wie es aussieht.

Ein zweites Paar Augen für das Board: Eine Maschine misst, was sich messen lässt, etwa den Kontrast, und der Rest bleibt eine Aufgabe für Menschen.
Ein zweites Paar Augen für das Board: Eine Maschine misst, was sich messen lässt, etwa den Kontrast, und der Rest bleibt eine Aufgabe für Menschen.

axe ist eine Engine mit Regeln für häufige Probleme der Barrierefreiheit: Text mit zu wenig Kontrast, Formularfelder und Buttons ohne Namen, Bilder ohne Textalternative und viele mehr. Das Paket @axe-core/playwright lässt diese Engine in der Seite laufen, die dein Test geöffnet hat, und gibt dem Test zurück, was sie gefunden hat.

Regeln können nur prüfen, was eine Maschine entscheiden kann. Ob ein Text genug Kontrast hat, ist eine Rechnung. Ob eine Beschriftung etwas Hilfreiches sagt, ob die Reihenfolge der Seite Sinn ergibt, ob man allein mit der Tastatur durch ein Formular kommt: Dafür braucht es einen Menschen. axe findet also einen Teil der Probleme, nicht alle. Es ist der Teil, nach dem zu suchen bei jedem Lauf nichts kostet, und das ist Grund genug, es einen Test tun zu lassen.

Installiere das Paket:

questboard
$ npm install --save-dev @axe-core/playwright

Eine Fixture, die eine Funktion ist

Jeder Test, der die Barrierefreiheit prüft, tut dieselben zwei Dinge: axe auf der Seite laufen lassen und ansehen, was es gefunden hat. Das gehört an eine Stelle, in die Fixtures des Frontend-Bereichs. Öffne tests/frontend/fixtures.ts und füge als erste Zeile einen Import ein:

tests/frontend/fixtures.ts
import AxeBuilder from '@axe-core/playwright';

Der Typ der Fixtures bekommt einen dritten Eintrag:

tests/frontend/fixtures.ts
type Fixtures = {
  board: QuestBoard;
  /** Whether the mocked API knows the visitor as a member. `test.use({ loggedIn: false })` turns it off. */
  loggedIn: boolean;
  /** Checks the page as it is right now, and returns one line per problem axe finds. */
  findA11yProblems: () => Promise<string[]>;
};

Und die Fixture selbst kommt in base.extend, hinter board:

tests/frontend/fixtures.ts
findA11yProblems: async ({ page }, use) => {
  await use(async () => {
    const { violations } = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
      .analyze();
    return violations.flatMap((violation) =>
      violation.nodes.map((node) => `${violation.id}: ${node.target.join(' ')}`),
    );
  });
},

Die bisherigen Fixtures haben dem Test ein Objekt gegeben: eine Seite, ein Board. Diese gibt ihm eine Funktion. Der Grund ist der Zeitpunkt. Eine Fixture wird gebaut, bevor der Test beginnt, wenn die Seite noch leer ist, und axe prüft die Seite so, wie sie in dem Moment ist, in dem es läuft. Also muss der Test sagen, wann: Er bringt die Seite in den Zustand, um den es ihm geht, und ruft dann findA11yProblems() auf.

Darin bereitet new AxeBuilder({ page }) eine Prüfung dieser Seite vor, und analyze() führt sie aus. withTags wählt die Regeln aus. Die vier Tags stehen für die Stufen A und AA der WCAG 2.0 und 2.1, der Web Content Accessibility Guidelines. Das ist der Standard, auf den sich Anforderungen an die Barrierefreiheit üblicherweise beziehen.

Zurück kommt eine Liste von violations. Jede nennt die Regel, die verletzt wurde (id), und die Elemente, die sie verletzen (nodes), jedes mit seinem Selektor (target). Die letzten Zeilen machen daraus eine Textzeile pro Element in der Form Regel: Selektor. Ein Test kann dann eine leere Liste erwarten, und ist die Liste nicht leer, dann ist die Fehlermeldung die Liste selbst: welche Regel, und wo.

Zustände prüfen, nicht nur die erste Seite

Leg tests/frontend/accessibility.spec.ts an:

tests/frontend/accessibility.spec.ts
import { DRAGON, SWORD, expect, mockApi, test } from './fixtures.ts';

test('the board of a member', async ({ page, board, findA11yProblems }) => {
  await mockApi(page, 'GET', '/quests', { json: [SWORD, DRAGON] });
  await board.open();
  await expect(board.quests).toHaveCount(2);

  expect(await findA11yProblems()).toEqual([]);
});

test('the empty board', async ({ page, board, findA11yProblems }) => {
  await mockApi(page, 'GET', '/quests', { json: [] });
  await board.open();
  await expect(page.getByText('No quests yet.')).toBeVisible();

  expect(await findA11yProblems()).toEqual([]);
});

test('the board that could not be loaded', async ({ page, board, findA11yProblems }) => {
  await mockApi(page, 'GET', '/quests', { status: 500 });
  await board.open();
  await expect(board.problem).toBeVisible();

  expect(await findA11yProblems()).toEqual([]);
});

test.describe('for a visitor', () => {
  test.use({ loggedIn: false });

  test('the board with the login form', async ({ page, board, findA11yProblems }) => {
    await mockApi(page, 'GET', '/quests', { json: [SWORD, DRAGON] });
    await board.open();
    await expect(board.loginButton).toBeVisible();

    expect(await findA11yProblems()).toEqual([]);
  });
});

Vier Tests, vier Zustände derselben Seite: das Board eines Mitglieds mit einer offenen und einer erledigten Quest, das leere Board, das Board, dessen Quests nicht geladen werden konnten, und das Board, das ein Besucher sieht, mit dem Login-Formular. Probleme sitzen gern in den Zuständen, die man selten ansieht, etwa in einer Fehlermeldung, und mit einer gemockten API ist jeder davon eine Zeile entfernt. Der Zustand des Besuchers verwendet die Option aus dem letzten Teil: test.use({ loggedIn: false }) lässt die gemockte /api/me für die Tests dieser Gruppe mit 401 antworten.

Jeder Test hat eine Zeile zwischen dem Öffnen der Seite und der Prüfung. Sie wartet auf etwas, das es nur in dem Zustand gibt, den der Test meint: zwei Quests in der Liste, den Satz des leeren Boards, die Fehlermeldung, den Login-Button. goto kommt zurück, wenn die Seite geladen ist, und das kann sein, bevor die Antwort der API auf ihr steht. Ohne die wartende Zeile könnte axe eine Seite prüfen, auf der noch „Loading quests…“ steht, daran nichts auszusetzen finden, und der Test wäre grün, ohne angesehen zu haben, was sein Name verspricht.

Führ die neue Datei aus. Das Wort am Ende des Befehls filtert die Testdateien nach ihrem Namen:

questboard
$ npx playwright test --project=frontend accessibilityRunning 4 tests using 4 workers  ✓  1 [frontend] › tests/frontend/accessibility.spec.ts:19:1 › the board that could not be loaded (546ms)  ✓  3 [frontend] › tests/frontend/accessibility.spec.ts:11:1 › the empty board (555ms)  ✓  4 [frontend] › tests/frontend/accessibility.spec.ts:30:3 › for a visitor › the board with the login form (549ms)  ✘  2 [frontend] › tests/frontend/accessibility.spec.ts:3:1 › the board of a member (673ms)  1) [frontend] › tests/frontend/accessibility.spec.ts:3:1 › the board of a member    Error: expect(received).toEqual(expected) // deep equality    - Expected  - 1    + Received  + 3    - Array []    + Array [    +   "color-contrast: .done > label",    + ]       6 |   await expect(board.quests).toHaveCount(2);       7 |    >  8 |   expect(await findA11yProblems()).toEqual([]);         |                                    ^       9 | });      10 |      11 | test('the empty board', async ({ page, board, findA11yProblems }) => {        at /home/robin/questboard/tests/frontend/accessibility.spec.ts:8:36  1 failed    [frontend] › tests/frontend/accessibility.spec.ts:3:1 › the board of a member  3 passed (2.1s)

Drei Zustände bestehen und einer nicht, und die Meldung sagt, was und wo: die Regel color-contrast, am Element .done > label. Das sind die erledigten Quests. Die Seite streicht sie durch und dunkelt sie ab, und zwar so weit, dass sich der Text nicht mehr genug vom Hintergrund abhebt. Die Stufe AA verlangt für Text dieser Größe einen Kontrast von mindestens 4,5 zu 1.

Das Board des Besuchers zeigt dieselbe abgedunkelte Quest und besteht trotzdem. Die Checkboxen eines Besuchers sind gesperrt, und die Kontrastregel von axe lässt gesperrte Bedienelemente und ihre Beschriftungen aus.

Die Korrektur ist ein Wert in web/src/style.css. Die Farbe war #5b4a78. Eine hellere ist lesbar, und die Quest sieht weiterhin erledigt aus, denn durchgestrichen bleibt sie:

web/src/style.css
li.done label {
  color: #a99bc9;
  text-decoration: line-through;
}

Führ den Befehl noch einmal aus, und alle vier Tests sind grün. Von Hand neu bauen musst du nichts: Playwright baut das Frontend für jeden Lauf neu.

Was axe nicht gefunden hat

Sieh dir das Formular des Boards an. Das Textfeld hat eine Beschriftung, „New quest“. Das Zahlenfeld daneben hat keine. Es hat einen Platzhalter, „Reward“, und ein Platzhalter ist nur zu sehen, solange ein Feld leer ist. Dieses Feld ist es nie: Es beginnt bei 10 und springt nach jeder neuen Quest auf 10 zurück. Zu sehen ist also ein Kästchen mit einer Zahl darin, und nichts sagt, wofür die Zahl steht.

axe beschwert sich nicht, und nach seinen Regeln hat es recht. Ein Feld braucht einen Namen, den assistive Technik ansagen kann, und der Platzhalter gibt ihm einen. Die Maschine ist zufrieden. Ein Mensch, der auf die Seite schaut, ist es nicht.

Der Testcode hat die ganze Zeit einen Hinweis gegeben. Das Page Object aus Teil 7 findet das Titelfeld so, wie ein Mensch es findet, über seine Beschriftung. Für dieses Feld musste es page.getByPlaceholder('Reward') schreiben. Wenn ein Test zu etwas anderem als einer Rolle oder einer Beschriftung greifen muss, um ein Element zu finden, frag nach dem Grund: Oft fehlt der Seite etwas, das auch ein Mensch bräuchte.

Gib dem Feld eine Beschriftung, die immer da ist. In web/src/App.vue wird das Formular für eine neue Quest zu:

web/src/App.vue
<form @submit.prevent="add">
  <label>
    New quest
    <input v-model.trim="title" maxlength="80" required />
  </label>
  <label class="narrow">
    Reward
    <input v-model.number="reward" type="number" min="0" max="1000" required />
  </label>
  <button>Add quest</button>
</form>

Das Zahlenfeld zieht in ein eigenes label mit dem sichtbaren Text „Reward“, und der Platzhalter verschwindet. Die Labels dieses Formulars teilen die Breite der Zeile unter sich auf. Die Klasse narrow hält das neue so breit wie sein Feld. Füge die Regel in web/src/style.css ein, unter der für form label:

web/src/style.css
form label.narrow {
  flex: none;
}

Jetzt würde jeder Test fehlschlagen, der eine Belohnung einträgt, denn nichts auf der Seite hat mehr den Platzhalter „Reward“. Hier zahlt sich das Page Object aus. Keiner dieser Tests sagt, wie das Feld gefunden wird, also ist eine Zeile in tests/support/board.ts die ganze Reparatur:

tests/support/board.ts
this.reward = page.getByLabel('Reward');

Die Seite ohne das Bild

axe prüft Regeln. Es gibt eine zweite, direktere Frage: Was bekommt jemand, der die Seite gar nicht sieht? Ein Screenreader arbeitet nicht mit Pixeln. Er arbeitet mit dem, was der Browser für ihn aus der Seite ableitet: den Elementen, auf die es ankommt, jedes mit einer Rolle (Überschrift, Textfeld, Button, Liste) und einem Namen. Playwright kann das als Text aufschreiben, als ARIA-Snapshot, und mit einer Vorlage im Test vergleichen. Füge am Ende von tests/frontend/accessibility.spec.ts einen weiteren Test an:

tests/frontend/accessibility.spec.ts
test('the board reads well without the picture', async ({ page, board }) => {
  await mockApi(page, 'GET', '/quests', { json: [SWORD, DRAGON] });
  await board.open();

  // What a screen reader gets to work with: roles and names, in the order of the page.
  await expect(page.getByRole('main')).toMatchAriaSnapshot(`
    - heading "Quest Board" [level=1]
    - textbox "New quest"
    - spinbutton "Reward"
    - button "Add quest"
    - list "Quests":
      - listitem:
        - checkbox "Find the lost sword"
        - button "Delete Find the lost sword"
      - listitem:
        - checkbox "Feed the dragon" [checked]
        - button "Delete Feed the dragon"
    - paragraph: 1 of 2 quests open
  `);
});

Die Vorlage in toMatchAriaSnapshot liest sich wie eine Gliederung der Seite: eine Überschrift der Ebene 1 namens „Quest Board“, ein Textfeld „New quest“, ein spinbutton „Reward“ (das ist die Rolle eines Zahlenfelds), der Button „Add quest“, dann eine Liste namens „Quests“ mit zwei Einträgen. Jeder Eintrag hat eine Checkbox, die nach ihrer Quest benannt ist, und einen Button „Delete …“, die zweite Checkbox ist [checked], und unter der Liste steht der Zähler. Rollen und Namen, in der Reihenfolge der Seite. Es sind dieselben Rollen und Namen, die deine Locators seit Teil 2 verwenden, und deshalb haben Tests mit getByRole und getByLabel die ganze Zeit schon etwas über die Barrierefreiheit gesagt.

Der Vergleich ist streng bei dem, was die Vorlage aufzählt, und schweigt zu dem, was sie weglässt. Die Zeile „Logged in as robin“, der Button „Log out“ und das Gold jeder Quest stehen auf der Seite und nicht in der Vorlage, und den Test stört das nicht. Eine Vorlage kann also bei dem bleiben, worauf es ankommt. Hier ist das: Die Felder des Formulars haben Namen, jede Quest lässt sich über ihren Namen abhaken und löschen, und eine erledigte Quest wird als angehakt angesagt. Entfernt jemand das aria-label von den Löschen-Buttons, heißen sie alle „✕“, und dieser Test meldet es.

Wie die anderen Assertions auf Locators versucht es auch diese so lange, bis die Seite passt, der Test braucht also keine eigene wartende Zeile. Führ die Datei noch einmal aus:

questboard
$ npx playwright test --project=frontend accessibilityRunning 5 tests using 5 workers  ✓  3 [frontend] › tests/frontend/accessibility.spec.ts:39:1 › the board reads well without the picture (217ms)  ✓  2 [frontend] › tests/frontend/accessibility.spec.ts:30:3 › for a visitor › the board with the login form (578ms)  ✓  4 [frontend] › tests/frontend/accessibility.spec.ts:11:1 › the empty board (557ms)  ✓  5 [frontend] › tests/frontend/accessibility.spec.ts:19:1 › the board that could not be loaded (564ms)  ✓  1 [frontend] › tests/frontend/accessibility.spec.ts:3:1 › the board of a member (603ms)  5 passed (2.0s)

Was du jetzt hast

Der Frontend-Bereich prüft vier Zustände des Boards gegen die Regeln, die axe kennt, und ein weiterer Test hält fest, was assistive Technik über die Seite erfährt. Unterwegs ist das Board selbst zweimal besser geworden: Erledigte Quests sind lesbar, und das Feld für die Belohnung sagt, was es ist.

All das dreht sich darum, was die Seite bedeutet. Ob sie nach einer Änderung am CSS noch richtig aussieht, kann bisher kein Test sagen. Im nächsten Teil macht die Suite Bilder vom Board und vergleicht sie.

Kommentare

Die Kommentare sind GitHub Discussions: Zum Schreiben mit GitHub anmelden.

Die Kommentare kommen über giscus von GitHub. Beim Laden gehen deine IP-Adresse an giscus.app und GitHub.