Installer et lancer son premier audit

Ce guide part de zéro. Il ne demande pas de savoir programmer : chaque commande se copie et se colle. Comptez une vingtaine de minutes la première fois, téléchargements compris.

1. Ce qu’il vous faut

• Un ordinateur sous Windows 10 ou 11, ou sous macOS. Linux convient aussi.
• Une connexion à Internet, pour les téléchargements de la première fois.
• Node.js, version 22.18 ou plus récente. C’est gratuit ; la partie 2 explique comment l’installer.
• Quelque chose à auditer : un dossier qui contient les fichiers de votre site (pages HTML, composants…), ou l’adresse d’un site en ligne.

2. Installer Node.js

Si Node.js est peut-être déjà installé sur votre ordinateur, passez d’abord à la partie 4 pour le vérifier.

3. Ouvrir un terminal

4. Vérifier l’installation

1. Copiez cette commande, collez-la dans le terminal, puis appuyez sur Entrée :

   node --version

   Vous devez voir une ligne qui commence par la lettre v, suivie du numéro de version. Ce numéro doit être au moins 22.18. S’il est plus petit, réinstallez Node.js (étape 2).

2. Faites de même avec cette commande :

   npx ultra11y --version

   La première fois, npx demande la permission de télécharger ultra11y : Need to install the following packages… Ok to proceed? (y). Tapez y puis Entrée. Vous devez voir le numéro de version d’ultra11y. Tout est prêt.

5. Premier audit : un dossier

Ici, vous auditez des fichiers présents sur votre ordinateur : le dossier d’un site, ou le code d’une application.

1. Placez le terminal dans ce dossier. Tapez cd suivi d’une espace, sans appuyer sur Entrée :

   cd 

   Puis faites glisser le dossier depuis l’Explorateur de fichiers (Windows) ou le Finder (macOS) jusque dans la fenêtre du terminal : son emplacement s’écrit tout seul. Appuyez alors sur Entrée.

2. Lancez l’audit :

   npx ultra11y audit . --standard rgaa --out audits

   Le point . désigne le dossier courant, --standard rgaa demande un audit selon le RGAA, et --out audits range les résultats dans un nouveau sous-dossier audits.

   Vous devez voir un titre, un tableau d’une ligne par thématique du RGAA (images, cadres, couleurs…), puis la liste des non-conformités trouvées. Par exemple :

   Audit RGAA 4.1.2 (moteur statique ultra11y) — …
   Thématique        C  NC  NA  ⏳
   1. Images         …
   …
   Non-conformités détectées :
     🔴 [6.2] index.html:2  Lien sans intitulé — aucun nom accessible.

   Les colonnes comptent les critères : C conformes, NC non conformes, NA non applicables, ⏳ à évaluer. Chaque non-conformité donne son critère RGAA entre crochets, le fichier et la ligne.

3. Fabriquez le rapport, en Markdown et en HTML :

   npx ultra11y report --in audits/audit-latest.json --standard rgaa --html --out audits

   Vous devez voir la liste des fichiers écrits, dont audits/index.html. Passez à la partie 7 pour l’ouvrir.

6. Premier audit : un site en ligne

Pour un site en ligne, ultra11y ouvre la page dans un vrai navigateur, invisible, et en garde une copie qu’il audite ensuite. Ce navigateur s’installe une fois pour toutes.

1. Créez un dossier pour ranger les résultats :

   mkdir audit-mon-site

2. Placez le terminal dans ce dossier :

   cd audit-mon-site

3. Installez le navigateur d’audit. C’est un téléchargement d’une centaine de mégaoctets, à faire une seule fois :

   npx playwright install chromium

   Comme à la partie 4, tapez y puis Entrée si npx demande la permission. Un grand encadré WARNING peut s’afficher, qui conseille npm install : il vise les projets de développeurs, ignorez-le. Le téléchargement se termine sans message d’erreur.

4. Ouvrez la page à auditer. Collez la commande, remplacez l’adresse par celle de votre site, puis appuyez sur Entrée :

   npx ultra11y scan https://adresse-de-votre-site.fr

   Vous devez voir une ligne qui se termine par written to .ultra11y/pages/ : la copie de la page est enregistrée. Un audit RGAA porte sur plusieurs pages représentatives (accueil, contact, mentions légales, un formulaire…) : refaites cette étape pour chacune.

5. Auditez les pages enregistrées :

   npx ultra11y audit --standard rgaa --out audits

   Vous devez voir instantanés de page ingérés depuis .ultra11y/pages, puis le même tableau qu’à la partie 5.

6. Fabriquez le rapport :

   npx ultra11y report --in audits/audit-latest.json --standard rgaa --html --out audits

7. Ouvrir le rapport

Le rapport HTML est une page web, rangée dans le dossier audits. Pour l’ouvrir dans votre navigateur, tapez la commande de votre système :

start audits\index.html

open audits/index.html

Vous pouvez aussi ouvrir le dossier audits et faire un double-clic sur index.html. Le même rapport existe en Markdown (le fichier rgaa- suivi de la date), pratique à joindre à un ticket.

Le rapport s’ouvre sur le résumé : le niveau atteint et ce qu’il faut corriger. Vient ensuite un sommaire, qui mène à chaque partie : synthèse par thématique, non-conformités par priorité, grille page par page, critères conformes et critères à évaluer. Beaucoup de critères restent « à évaluer » : c’est normal. Un outil automatique ne tranche qu’une petite partie du RGAA, et ultra11y ne déclare jamais conforme ce qu’il n’a pas vérifié. La page Principes explique pourquoi ; la suite du travail se fait avec un agent IA.

8. Aller plus loin : la skill dans Claude Code ou Codex

Un agent de code comme Claude Code ou Codex peut mener l’audit complet : il juge les critères que la machine ne tranche pas, et ses verdicts sont contre-vérifiés (voir Audit). Installé comme extension, ultra11y relit aussi chaque changement avant un commit. Ces étapes supposent que l’agent est déjà installé et ouvert dans le dossier de votre projet.

Les autres agents (OpenCode, Cursor…) sont décrits sur la page Intégration.

Ça ne marche pas ?

« node » ou « npx » n’est pas reconnu, ou command not found

Node.js n’est pas installé, ou le terminal a été ouvert avant son installation. Fermez le terminal, ouvrez-en un nouveau et retapez node --version. Toujours rien ? Refaites la partie 2.

Windows : « l’exécution de scripts est désactivée sur ce système »

PowerShell bloque le petit script qui lance npx. Tapez npx.cmd à la place de npx dans chaque commande, par exemple :

npx.cmd ultra11y audit . --standard rgaa --out audits

Node.js est trop ancien

ultra11y demande Node.js 22.18 ou plus récent. Avec une version plus ancienne, npx affiche un avertissement EBADENGINE (Unsupported engine) ou une erreur. Vérifiez avec node --version, puis installez la version LTS depuis nodejs.org : elle remplace l’ancienne.

« 0 fichiers analysés »

Le terminal n’est pas dans le bon dossier, ou ce dossier ne contient aucun fichier de page (HTML, JSX, Vue, Svelte, Astro…). Refaites la partie 5 depuis le début. Pour voir ce que contient le dossier courant, tapez dir sur Windows, ls sur macOS.

scan ne trouve pas de navigateur

Le message parle de no browser binary, d’Executable doesn’t exist ou de playwright install : le navigateur d’audit n’est pas installé. Lancez npx playwright install chromium, puis recommencez. Sur un réseau d’entreprise, le téléchargement peut être bloqué : demandez à votre service informatique.

Le rapport ne s’ouvre pas

Ouvrez le dossier audits dans l’Explorateur de fichiers ou le Finder, et faites un double-clic sur index.html.

Le rapport est plein de « à évaluer »

C’est attendu : le moteur seul ne peut trancher qu’une partie des tests du RGAA. Le reste demande un jugement, celui d’un agent IA contre-vérifié (partie 8) ou d’une personne compétente.

Un autre problème ? Décrivez-le, avec la commande tapée et le message affiché, dans une demande sur GitHub.