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 :
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.
| Besoin | Option recommandée | Raison |
|---|---|---|
| Analyser une vraie application web | Playwright | Pilote 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 statique | CLI | Aucune 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 WebdriverIO | Le binding correspondant | S’intègre directement à l’environnement de test que vous avez déjà. |
| Tests unitaires ou de composants | test-matchers | Intégration directe avec Jest/Vitest sur jsdom. |
| Votre propre intégration, ou un accès direct au moteur | @surea11y/core | Contrô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.htmlengine: @surea11y/core 1.14.1pass: 14 fail: 3 cantTell: 2 notApplicable: 126occurrences by tier: fail: 3 cantTell: 2needs review: likely fail: 0 likely pass: 0 needs a person: 2FAIL (3 rule(s)):contrast-enhanced (serious, 1 fail occurrence(s))- html > body > main > pElement 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 thecontrast ratio reaches at least 7:1.contrast-minimum (serious, 1 fail occurrence(s))- html > body > main > pElement 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 thecontrast ratio reaches at least 4.5:1.page-title-present (serious, 1 fail occurrence(s))- head > titleThis 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-reviewcriteria (WCAG 2.2):fail 1.4.3 Contrast: minimum; 1.4.6 Contrast: enhanced; 2.4.2 PagetitledcantTell 1.1.1 Non-text content: text alternatives; 1.2.1 Audio-onlyand video-only (prerecorded): transcript; 1.2.2 Captions(Prerecorded); 1.3.1 Info and Relationships; 1.3.4Orientation; 1.3.5 Identify Input Purpose; 1.4.1 Use ofColor; 1.4.2 Audio Control; 1.4.4 Resize Text; 1.4.5 Imagesof 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 Focusorder; 2.4.4 Link Purpose (In Context); 2.4.6 Headings andLabels; 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.2Language of Parts; 3.2.5 Change on Request; 3.3.1 ErrorIdentification; 3.3.2 Labels or Instructions; 3.3.8Accessible Authentication (Minimum); 4.1.2 Name, role, value:accessible name; 4.1.2 Name, role, value: ARIA validity;4.1.3 Status MessagesnotApplicable: 2A criterion that passes here means the checks that ran found nothing init, 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/coreou 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.