Créer automatiquement des captures d'écran de produit pour votre documentation
Vous avez déplacé un bouton. Maintenant, 14 articles d’aide montrent l’ancienne disposition, et quelqu’un doit se connecter, retrouver le bon compte de démonstration, redimensionner la fenêtre et refaire chaque image. Personne ne veut de cette corvée, alors elle ne se fait pas, et la documentation se met discrètement à mentir.
La solution est d’arrêter de prendre les captures d’écran du produit à la main. Pour créer automatiquement des captures d’écran de produit, écrivez un script qui se connecte à un compte de démonstration pré-rempli, visite chaque page dans un navigateur sans interface de taille fixe, capture des éléments précis (pas l’écran entier) en résolution 2x, masque tout ce qui change d’une exécution à l’autre et enregistre chaque image sous un nom de fichier stable. Puis lancez ce script en intégration continue chaque fois que l’interface change. Playwright fait tout cela en une soixantaine de lignes.
Vous trouverez ci-dessous le script que nous utiliserions vraiment, les détails qui rendent le résultat cohérent, et ce qui demande encore un humain.
Pourquoi les captures d’écran faites à la main deviennent obsolètes
Les captures faites à la main échouent pour des raisons banales :
- Elles coûtent cher à refaire, donc on repousse. Une refonte qui touche la barre latérale peut invalider d’un coup chaque image de votre centre d’aide.
- Elles sont incohérentes. L’une a été prise sur un portable de 13 pouces, une autre sur un moniteur 4K, une en mode sombre, une avec l’icône d’une extension de navigateur dans un coin.
- Elles laissent fuiter de vraies données. La vraie boîte de réception de quelqu’un, le nom d’un client, une vraie adresse e-mail dans le menu de l’avatar.
- Personne ne sait lesquelles sont périmées. Rien ne relie « nous avons changé la page de facturation » à « ces cinq images montrent la page de facturation ».
L’automatisation des captures règle les trois premiers problèmes d’emblée et vous donne une chance de traiter le quatrième. Si votre documentation dérive de façon générale (pas seulement les images), la version plus large de ce problème est abordée dans comment garder la documentation à jour quand on livre chaque semaine.
Ce qu’il vous faut avant d’écrire du code
Trois éléments font fonctionner les captures d’écran de documentation automatisées. Sautez l’un d’eux et le résultat sera instable et laid.
1. Un compte de démonstration pré-rempli
Votre script doit se connecter à un compte qui a toujours le même aspect : même nom d’entreprise, mêmes 12 projets, mêmes faux collègues aux noms plausibles. Écrivez un script d’amorçage (scripts/seed-demo.ts ou ce qui convient à votre pile technique) qui efface et recrée ce compte. Le réalisme compte. Un tableau de bord rempli de « Test Project 1 » et de « asdf » a l’air cassé dans un article d’aide.
2. Des sélecteurs stables pour ce que vous capturez
Vous allez capturer des éléments, il vous faut donc un moyen fiable de les trouver. Les classes CSS de Tailwind ou du CSS-in-JS changent constamment. Ajoutez plutôt un attribut dédié :
<section data-docs="billing-summary">...</section>
Cela ne coûte rien, survit aux refactorisations et dit à chaque ingénieur « cet élément apparaît dans la documentation, réfléchissez avant de le supprimer ».
3. Une liste de captures
Une simple liste de chaque image utilisée par votre documentation : quelle page, quel élément, quoi masquer et le nom du fichier de sortie. Gardez-la dans le code, à côté du script. Cette liste est aussi votre réponse à la question « quelles captures montrent la page de facturation ? » plus tard.
Un script de capture Playwright qui fonctionne
Playwright est aujourd’hui le meilleur outil pour cela. Il pilote un vrai Chromium, Firefox ou WebKit, peut capturer un seul élément et propose des options intégrées pour masquer du contenu et figer les animations.
D’abord, connectez-vous une fois et enregistrez la session pour que chaque exécution de capture démarre authentifiée :
// scripts/docs-login.mjs
import { chromium } from 'playwright';
const BASE_URL = process.env.BASE_URL ?? 'http://localhost:3000';
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto(`${BASE_URL}/login`);
await page.getByLabel('Email').fill(process.env.DEMO_EMAIL);
await page.getByLabel('Password').fill(process.env.DEMO_PASSWORD);
await page.getByRole('button', { name: 'Sign in' }).click();
await page.waitForURL('**/dashboard');
await page.context().storageState({ path: '.auth/demo.json' });
await browser.close();
Puis le script de capture lui-même :
// scripts/docs-screenshots.mjs
import { chromium } from 'playwright';
import { mkdir } from 'node:fs/promises';
const BASE_URL = process.env.BASE_URL ?? 'http://localhost:3000';
const OUT_DIR = 'docs/images';
const shots = [
{
name: 'dashboard-overview',
path: '/dashboard',
element: '[data-docs="overview-panel"]',
mask: ['[data-docs="last-synced"]', '[data-docs="avatar"]'],
},
{
name: 'billing-summary',
path: '/settings/billing',
element: '[data-docs="billing-summary"]',
},
{
name: 'invite-teammate-dialog',
path: '/settings/team',
element: '[role="dialog"]',
before: (page) => page.getByRole('button', { name: 'Invite teammate' }).click(),
},
];
const browser = await chromium.launch();
const context = await browser.newContext({
storageState: '.auth/demo.json',
viewport: { width: 1280, height: 800 },
deviceScaleFactor: 2,
colorScheme: 'light',
locale: 'en-US',
timezoneId: 'America/New_York',
reducedMotion: 'reduce',
});
const page = await context.newPage();
// Every "Updated 3 minutes ago" and date picker now shows the same moment.
await page.clock.setFixedTime(new Date('2026-03-02T10:00:00'));
await mkdir(OUT_DIR, { recursive: true });
for (const shot of shots) {
await page.goto(BASE_URL + shot.path);
if (shot.before) await shot.before(page);
const target = page.locator(shot.element);
await target.waitFor({ state: 'visible' });
await target.screenshot({
path: `${OUT_DIR}/${shot.name}.png`,
animations: 'disabled',
caret: 'hide',
mask: (shot.mask ?? []).map((selector) => page.locator(selector)),
maskColor: '#e3d4ff',
// Hide things that should never appear in docs.
style: '#chat-widget, .cookie-banner, .dev-toolbar { display: none !important; }',
});
console.log(`saved ${shot.name}.png`);
}
await browser.close();
Lancez-le avec node scripts/docs-login.mjs && node scripts/docs-screenshots.mjs sur votre application locale ou sur une copie de préproduction où le compte de démonstration est pré-rempli. Vous obtiendrez un dossier de PNG nets, nommés exactement comme la liste de captures.
Les réglages qui rendent les captures cohérentes
L’essentiel de la valeur tient à une poignée d’options. Voici pourquoi chacune est là.
Une fenêtre d’affichage fixe. 1280x800 signifie que la mise en page se casse aux mêmes points à chaque fois. Choisissez une taille et gardez-la pour toutes les images, pour que votre centre d’aide ne ressemble pas à un collage.
deviceScaleFactor: 2. Cela produit un rendu en densité rétina : un élément de 600 px de large devient une image de 1200 px de large. Elle est nette sur les portables et téléphones récents, et vous pouvez l’afficher à moitié taille dans l’article. Les fichiers sont plus lourds ; passez-les dans un optimiseur comme oxipng ou convertissez-les en WebP si cela compte pour vous.
Des captures d’élément, pas de page entière. La capture de la seule carte de résumé de facturation indique au lecteur où regarder. Une capture de page entière l’oblige à chercher. Cela signifie aussi qu’une modification de la barre latérale ne touche pas votre image de facturation, si bien que vous ne relisez que ce qui a vraiment changé.
Masquer le contenu dynamique. Tout ce qui diffère entre deux exécutions sans modification de code est du bruit : horodatages relatifs, compteurs en direct, « 3 personnes en ligne », couleurs d’avatar aléatoires, astuce du jour tournante. L’option mask de Playwright peint un cadre uni sur ces éléments. Privilégiez la correction des données à la source (noms pré-remplis, horloge figée) et ne masquez que ce que vous ne maîtrisez pas.
Horloge, langue et fuseau horaire figés. page.clock.setFixedTime fixe Date.now(), si bien que « Échéance dans 2 jours » dit la même chose pour toujours. La langue et le fuseau horaire évitent qu’un exécuteur d’intégration continue situé dans une autre région affiche 02/03/2026 au lieu de 3/2/2026.
Animations désactivées, curseur masqué. Un fondu à moitié terminé ou un curseur clignotant apparaîtra dans une exécution et pas dans la suivante.
Relancer les captures en intégration continue
Un script dont il faut se souvenir pour le lancer n’est guère mieux que de tout faire à la main. Mettez-le en intégration continue.
La version la plus simple : à chaque fusion sur main (ou chaque nuit, si votre suite de tests est lente), démarrez l’application, pré-remplissez le compte de démonstration, lancez le script et ouvrez une pull request si une image a changé. Git affiche les différences d’images côte à côte sur GitHub, si bien qu’un relecteur peut jeter un œil à « billing-summary.png a changé » et confirmer que c’est voulu.
# .github/workflows/docs-screenshots.yml
name: Docs screenshots
on:
push:
branches: [main]
workflow_dispatch:
jobs:
capture:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npx playwright install --with-deps chromium
- run: npm run seed:demo
- run: npm run start &
- run: npx wait-on http://localhost:3000
- run: node scripts/docs-login.mjs && node scripts/docs-screenshots.mjs
env:
DEMO_EMAIL: ${{ secrets.DOCS_DEMO_EMAIL }}
DEMO_PASSWORD: ${{ secrets.DOCS_DEMO_PASSWORD }}
- uses: peter-evans/create-pull-request@v6
with:
branch: docs/screenshots
title: "Update docs screenshots"
add-paths: docs/images
Un avertissement honnête : les polices s’affichent légèrement différemment sur macOS et sur Linux. Si certaines captures viennent de votre portable et d’autres de l’intégration continue, chaque exécution « modifiera » des images qui n’ont pas vraiment changé. Générez-les à un seul endroit (l’intégration continue, ou l’image Docker officielle de Playwright en local) et les différences resteront silencieuses.
Là où les captures scriptées restent insuffisantes
Cette approche est excellente, et elle reste un travail. Soyez réaliste :
- Quelqu’un doit entretenir la liste de captures. Ajoutez une fonctionnalité, et quelqu’un doit ajouter ses captures, écrire les sélecteurs et décider quoi masquer. Supprimez une page, et le script échoue tant que personne ne retire l’entrée.
- Il ne sait pas où vont les images. Le script met à jour
billing-summary.png. Il ne sait pas quels articles l’utilisent, ni si les étapes autour sont encore vraies. - L’authentification devient délicate. Les connexions uniquement par SSO, les liens magiques, l’authentification à deux facteurs et les connexions OAuth à des services tiers exigent tous des contournements (une route de connexion réservée aux tests est la réponse habituelle).
- Il capture des états, pas des histoires. Un parcours en plusieurs étapes se montre mieux avec une courte vidéo. Nous en parlons dans comment créer des vidéos de présentation de produit.
D’autres options existent. Cypress propose cy.screenshot() et convient très bien si votre équipe vit déjà dans Cypress. Puppeteer est plus bas niveau et centré sur Chromium. shot-scraper est une pratique enveloppe en ligne de commande autour de Playwright si vous préférez entretenir un fichier YAML plutôt qu’un script. Pour des captures marketing ponctuelles, un outil manuel comme CleanShot X avec une taille de fenêtre constante suffit honnêtement. La voie scriptée devient rentable quand vous avez plus de quelques dizaines d’images à maintenir à jour.
Automatiser les captures sans écrire le script
C’est la partie du travail qu’Ellie Docs a été conçu pour vous enlever. Vous connectez un dépôt GitHub, et Ellie lit le code pour cartographier vos fonctionnalités et vos écrans visibles par les utilisateurs. Il exécute ensuite votre application dans un bac à sable, se connecte comme utilisateur de test et capture de vraies captures d’écran du produit connecté, placées directement dans les articles d’aide qu’il rédige.

Comme chaque article est lié aux fonctionnalités qu’il décrit, une pull request fusionnée qui modifie l’une d’elles est signalée sur les bons articles, et vous relisez la mise à jour suggérée avant toute mise en ligne. Vous n’entretenez ni liste de captures ni fichier de sélecteurs.

Si vous aimez garder la main sur le script Playwright, gardez-le. C’est une bonne configuration. Si vous préférez que les captures, les articles qui les entourent et leur entretien soient pris en charge pour vous, c’est ce que fait Ellie. Écrire les mots autour de ces images est aussi un métier à part entière ; voir comment rédiger des articles de centre d’aide que les gens utilisent vraiment.
Questions fréquentes
Quelle résolution pour les captures d’écran de documentation ?
Capturez en 2x (deviceScaleFactor: 2) depuis une fenêtre d’affichage fixe d’environ 1280 pixels de large, puis affichez à moitié taille. Vous obtenez des images nettes sur les écrans rétina sans mises en page démesurées.
Dois-je capturer la page entière ou une seule partie ? En général une seule partie. Recadrez sur l’élément dont parle l’étape, avec un peu de contexte autour pour que le lecteur le retrouve. Utilisez les captures de page entière avec parcimonie, pour les moments « voici la mise en page d’ensemble ».
Comment éviter que de vraies données clients apparaissent dans les captures ?
Ne capturez jamais depuis des comptes de production. Utilisez un compte de démonstration pré-rempli, avec de faux noms et des e-mails en example.com, et masquez ce que vous ne pouvez pas pré-remplir, comme les widgets tiers.
À quelle fréquence lancer les captures automatisées ? À chaque fusion sur main si l’exécution est rapide, chaque nuit sinon. L’essentiel est que personne n’ait à y penser.
Si vous voulez que tout cela soit fait pour vous, essayez Ellie Docs gratuitement. Connectez un dépôt et vous aurez un centre d’aide avec de vraies captures d’écran de votre application, sans carte bancaire.