Premiers pas

Installation

Il n’y a pas de commande d’installation unique : surea11y est un moteur central accompagné d’une famille de bindings publiés séparément, donc le ou les paquets à installer dépendent de la façon dont vous exécutez déjà vos tests ou vos scripts. Choisissez votre stack :

Vous ne savez pas par où commencer ?

Utilisez Playwright pour analyser une vraie application web, ou la CLI pour vérifier du HTML statique depuis un terminal ou un pipeline de CI.

BesoinOption recommandéeRaison
Analyser une vraie application webPlaywrightPilote un vrai navigateur via une intégration que les suites de tests modernes utilisent déjà, donc les résultats reflètent la mise en page et le rendu réels.
Analyser du HTML statiqueCLIAucune intégration à écrire : une seule commande sur des fichiers, des URL, un sitemap ou une étape de CI ; avec --browser, elle analyse aussi les pages rendues par leur JavaScript.
Vous utilisez déjà Cypress, Selenium, Puppeteer ou WebdriverIOLe binding correspondantS’intègre directement à l’environnement de test que vous avez déjà.
Tests unitaires ou de composantstest-matchersIntégration directe avec Jest/Vitest sur jsdom.
Votre propre intégration, ou un accès direct au moteur@surea11y/coreContrôle maximal sur l’exécution et les résultats.

Un exemple en 5 minutes

La CLI est le moyen le plus rapide de voir un vrai résultat : pas de navigateur à configurer, pas de framework de test. Analysez une page minimale :

<html lang="en">
<body>
<main>
<h1>Welcome</h1>
<p style="color: #999999; background-color: #ffffff;">This text has low contrast.</p>
<a href="/details">Click here</a>
</main>
</body>
</html>
$ npm install -g @surea11y/cli
$ surea11y scan ./index.html
surea11y scan: file:///path/to/index.html
engine: @surea11y/core 1.14.1
pass: 14 fail: 3 cantTell: 2 notApplicable: 126
occurrences by tier: fail: 3 cantTell: 2
needs review: likely fail: 0 likely pass: 0 needs a person: 2
FAIL (3 rule(s)):
contrast-enhanced (serious, 1 fail occurrence(s))
- html > body > main > p
Element has insufficient color contrast (AAA) of 2.85:1 (foreground:
#999999, background: #ffffff, font size: 16px, font weight: normal).
Expected contrast ratio of 7:1 (normal text).
hint: Change the text color, the background color, or both, so the
contrast ratio reaches at least 7:1.
contrast-minimum (serious, 1 fail occurrence(s))
- html > body > main > p
Element has insufficient color contrast of 2.85:1 (foreground:
#999999, background: #ffffff, font size: 16px, font weight: normal).
Expected contrast ratio of 4.5:1 (normal text).
hint: Change the text color, the background color, or both, so the
contrast ratio reaches at least 4.5:1.
page-title-present (serious, 1 fail occurrence(s))
- head > title
This page has no <title> element.
hint: Add a <title> that says what the page is about or what it is for.
cantTell — needs human review (2 rule(s)): link-name-quality,
manual-review
criteria (WCAG 2.2):
fail 1.4.3 Contrast: minimum; 1.4.6 Contrast: enhanced; 2.4.2 Page
titled
cantTell 1.1.1 Non-text content: text alternatives; 1.2.1 Audio-only
and video-only (prerecorded): transcript; 1.2.2 Captions
(Prerecorded); 1.3.1 Info and Relationships; 1.3.4
Orientation; 1.3.5 Identify Input Purpose; 1.4.1 Use of
Color; 1.4.2 Audio Control; 1.4.4 Resize Text; 1.4.5 Images
of Text; 1.4.12 Text Spacing; 2.1.1 Keyboard; 2.1.3 Keyboard
(No Exception); 2.2.1 Timing Adjustable; 2.2.2 Pause, Stop,
Hide; 2.2.4 Interruptions; 2.4.1 Bypass Blocks; 2.4.3 Focus
order; 2.4.4 Link Purpose (In Context); 2.4.6 Headings and
Labels; 2.4.7 Focus visible; 2.4.9 Link Purpose (Link Only);
2.5.8 Target size: minimum; 3.1.1 Language of page; 3.1.2
Language of Parts; 3.2.5 Change on Request; 3.3.1 Error
Identification; 3.3.2 Labels or Instructions; 3.3.8
Accessible Authentication (Minimum); 4.1.2 Name, role, value:
accessible name; 4.1.2 Name, role, value: ARIA validity;
4.1.3 Status Messages
notApplicable: 2
A criterion that passes here means the checks that ran found nothing in
it, not that the page conforms.

Deux problèmes dont le moteur est certain, qui donnent donc fail : le texte à faible contraste, en échec aux seuils AA et AAA, et l’absence de <title>. Puis une liste cantTell à examiner par une personne (« Click here » est-il un bon nom de lien, y a-t-il ici quelque chose qui demande un examen manuel) ; la ligne needs review indique qu’aucune des deux questions ne penche d’un côté, si bien que toutes deux demandent une personne. Parmi les 126 résultats notApplicable figure target-size-minimum : cette règle ne peut pas s’exécuter sans une vraie mise en page CSS, dont une analyse de HTML statique ne dispose pas (--browser la lui donne).

Le dernier bloc présente le même résultat par critère WCAG 2.2 : 1.4.3, 1.4.6 et 2.4.2 donnent fail ; tous les autres critères vérifiés par l’analyse sont cantTell, laissés à une personne ; et les 2 sans rien à juger sont seulement comptés. Aucun n’apparaît en pass : depuis @surea11y/core 1.14, un critère ne réussit que si ses règles vérifient tout ce qu’il demande, et aucun ne le fait encore, si bien que, lorsqu’elles réussissent toutes, le reste revient à une personne. Voir Résultats et rapports pour la signification de chaque champ d’un résultat complet.

  • Tests de bout en bout, qui pilotent un navigateur réel ou headless : Cypress, Playwright, Puppeteer, Selenium ou WebdriverIO.
  • Tests unitaires et de composants, sur jsdom : test-matchers, pour Jest ou Vitest.
  • Des pages depuis un terminal ou un pipeline de CI, en HTML statique ou dans un navigateur : la CLI.
  • Sans framework de test ni étape de build : autonome, en installant directement @surea11y/core ou en intégrant le bundle navigateur.

Utilisation

Quelle que soit la façon dont vous lancez une analyse (jsdom, un vrai navigateur, n’importe quel binding, la CLI), elle renvoie la même structure de résultat native : checksResults (une entrée par règle, y compris chaque pass/notApplicable, et non une liste « violations uniquement ») et rulesResults (les agrégations par critère de succès WCAG). Ce n’est pas la structure violations/passes/incomplete/inapplicable utilisée par d’autres outils de test d’accessibilité répandus : les noms de méthodes de chaque binding reprennent les conventions courantes du domaine pour faciliter la migration, mais le schéma de résultat, plus riche, est conservé tel quel. Voir Résultats et rapports pour le schéma complet.