Cómo crear capturas de pantalla de producto automáticamente para tu documentación
Moviste un botón. Ahora 14 artículos de ayuda muestran el diseño antiguo y alguien tiene que iniciar sesión, encontrar la cuenta de demostración adecuada, cambiar el tamaño de la ventana y rehacer todas las imágenes. Nadie quiere ese trabajo, así que no se hace, y la documentación empieza a mentir sin que nadie lo note.
La solución es dejar de hacer las capturas del producto a mano. Para crear capturas de pantalla de producto automáticamente, escribe un script que inicie sesión en una cuenta de demostración con datos de ejemplo, visite cada página en un navegador sin interfaz de tamaño fijo, capture elementos concretos (no toda la pantalla) al doble de resolución, enmascare todo lo que cambia entre ejecuciones y guarde cada imagen con un nombre de archivo estable. Después, ejecuta ese script en CI cada vez que cambie la interfaz. Playwright hace todo esto en unas 60 líneas.
A continuación encontrarás el script que usaríamos de verdad, los detalles que hacen que el resultado sea coherente y las partes que aún necesitan a una persona.
Por qué las capturas de producto hechas a mano se quedan obsoletas
Las capturas hechas a mano fallan por motivos aburridos:
- Son caras de rehacer, así que la gente lo aplaza. Un rediseño que toque la barra lateral puede invalidar de golpe todas las imágenes de tu centro de ayuda.
- Son incoherentes. Una se hizo en un portátil de 13 pulgadas, otra en un monitor 4K, otra en modo oscuro, otra con el icono de una extensión del navegador en la esquina.
- Filtran datos reales. La bandeja de entrada real de alguien, el nombre de un cliente, una dirección de correo real en el menú del avatar.
- Nadie sabe cuáles están desactualizadas. No hay un vínculo entre «hemos cambiado la página de facturación» y «estas cinco imágenes muestran la página de facturación».
La automatización de capturas resuelve de lleno las tres primeras y te da una oportunidad de pelear con la cuarta. Si tu documentación se desfasa en general (no solo las imágenes), la versión más amplia de este problema se trata en cómo mantener la documentación al día cuando lanzas cada semana.
Lo que necesitas antes de escribir código
Tres cosas hacen que las capturas automáticas de documentación funcionen. Si te saltas alguna, obtendrás resultados inestables y feos.
1. Una cuenta de demostración con datos de ejemplo
Tu script necesita iniciar sesión en una cuenta que siempre tenga el mismo aspecto: el mismo nombre de empresa, los mismos 12 proyectos, los mismos compañeros ficticios con nombres verosímiles. Escribe un script de carga de datos (scripts/seed-demo.ts o lo que encaje con tu stack) que borre y vuelva a crear esta cuenta. El realismo importa. Un panel lleno de «Test Project 1» y «asdf» parece roto en un artículo de ayuda.
2. Selectores estables para lo que capturas
Vas a capturar elementos, así que necesitas una forma fiable de encontrarlos. Las clases CSS de Tailwind o de CSS-in-JS cambian constantemente. En su lugar, añade un atributo específico:
<section data-docs="billing-summary">...</section>
No cuesta nada, sobrevive a las refactorizaciones y le dice a cada ingeniero «este elemento aparece en la documentación, piénsalo antes de borrarlo».
3. Una lista de capturas
Una lista sencilla de todas las imágenes que usa tu documentación: qué página, qué elemento, qué enmascarar y el nombre del archivo de salida. Guárdala en el código, junto al script. Esta lista también es tu respuesta a «¿qué capturas muestran la página de facturación?» más adelante.
Un script de capturas con Playwright que funciona
Playwright es hoy la mejor herramienta para esto. Controla Chromium, Firefox o WebKit reales, puede capturar un solo elemento y trae opciones integradas para enmascarar y congelar animaciones.
Primero, inicia sesión una vez y guarda la sesión para que cada ejecución de capturas empiece ya autenticada:
// 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();
Después, el script de capturas propiamente dicho:
// 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();
Ejecútalo con node scripts/docs-login.mjs && node scripts/docs-screenshots.mjs contra tu app local o una copia de staging con la cuenta de demostración ya cargada. Obtendrás una carpeta de PNG nítidos con los mismos nombres que la lista de capturas.
Los ajustes que hacen coherentes las capturas
La mayor parte del valor está en un puñado de opciones. Aquí va por qué está cada una.
Viewport fijo. 1280x800 significa que el diseño se rompe en los mismos puntos cada vez. Elige un tamaño y mantenlo en todas las imágenes para que tu centro de ayuda no parezca un collage.
deviceScaleFactor: 2. Esto renderiza con densidad retina, de modo que un elemento de 600 px de ancho se convierte en una imagen de 1200 px de ancho. Se ve nítido en portátiles y móviles actuales, y puedes mostrarlo a la mitad de tamaño en el artículo. Los archivos pesan más; pásalos por un optimizador como oxipng o conviértelos a WebP si te importa.
Capturas de elementos, no de páginas completas. Una captura solo de la tarjeta de resumen de facturación le dice al lector dónde mirar. Una captura de página completa le obliga a buscar. Además, significa que un cambio en la barra lateral no toca tu imagen de facturación, así que solo vuelves a revisar lo que realmente cambió.
Enmascarar el contenido dinámico. Todo lo que difiere entre dos ejecuciones sin ningún cambio de código es ruido: marcas de tiempo relativas, contadores en vivo, «3 personas conectadas», colores de avatar aleatorios, un consejo del día rotativo. La opción mask de Playwright pinta un recuadro sólido sobre esos elementos. Es preferible arreglar los datos en origen (nombres fijos, un reloj congelado) y enmascarar solo lo que no puedes controlar.
Reloj, idioma y zona horaria congelados. page.clock.setFixedTime fija Date.now(), de modo que «Vence en 2 días» dice lo mismo para siempre. El idioma y la zona horaria evitan que un ejecutor de CI en otra región muestre 02/03/2026 en lugar de 3/2/2026.
Animaciones desactivadas, cursor oculto. Un fundido a medias o un cursor parpadeante aparecerá en una ejecución y en la siguiente no.
Volver a ejecutar las capturas en CI
Un script que tienes que acordarte de ejecutar es solo un poco mejor que hacerlo a mano. Ponlo en CI.
La versión más sencilla: en cada fusión a main (o cada noche, si tu batería de pruebas es lenta), arranca la app, carga la cuenta de demostración, ejecuta el script y abre un pull request si alguna imagen ha cambiado. Git muestra los diffs de imágenes en paralelo en GitHub, así que un revisor puede echar un vistazo a «billing-summary.png ha cambiado» y confirmar que es un cambio intencionado.
# .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
Una advertencia sincera: las fuentes se renderizan de forma ligeramente distinta en macOS y en Linux. Si algunas capturas salen de tu portátil y otras de CI, cada ejecución «cambiará» imágenes que en realidad no cambiaron. Genéralas en un solo sitio (CI, o la imagen oficial de Docker de Playwright en local) y los diffs se mantienen tranquilos.
Dónde se quedan cortas las capturas con scripts
Este enfoque es estupendo y sigue siendo trabajo. Sé realista:
- Alguien tiene que mantener la lista de capturas. Añades una función y alguien tiene que añadir sus capturas, escribir los selectores y decidir qué enmascarar. Borras una página y el script falla hasta que alguien elimina la entrada.
- No sabe dónde van las imágenes. El script actualiza
billing-summary.png. No sabe qué artículos la usan ni si los pasos que la rodean siguen siendo ciertos. - La autenticación se complica. Los inicios de sesión solo con SSO, los enlaces mágicos, la verificación en dos pasos y las conexiones OAuth con servicios de terceros necesitan soluciones alternativas (una ruta de inicio de sesión solo para pruebas es la respuesta habitual).
- Captura estados, no historias. Un flujo de varios pasos se muestra mejor en un vídeo corto. Lo tratamos en cómo crear vídeos tutoriales de producto.
Existen otras opciones. Cypress tiene cy.screenshot() y funciona bien si tu equipo ya vive en Cypress. Puppeteer es de más bajo nivel y está centrado en Chromium. shot-scraper es un práctico envoltorio de línea de comandos alrededor de Playwright si prefieres mantener un archivo YAML en lugar de un script. Para capturas de marketing puntuales, una herramienta manual como CleanShot X con un tamaño de ventana coherente está, sinceramente, bien. La vía de los scripts compensa cuando tienes más de un par de docenas de imágenes que deben mantenerse al día.
Automatizar las capturas sin escribir el script
Esta es la parte del trabajo que creamos Ellie Docs para quitarte de encima. Conectas un repositorio de GitHub y Ellie lee el código para mapear tus funciones y pantallas de cara al usuario. Después ejecuta tu app en un entorno aislado, inicia sesión como un usuario de prueba y captura pantallas reales del producto con la sesión iniciada, que coloca directamente en los artículos de ayuda que redacta.

Como cada artículo está vinculado a las funciones que describe, un PR fusionado que cambia una de esas funciones se señala en los artículos correspondientes, y revisas la actualización sugerida antes de que se publique nada. No mantienes una lista de capturas ni un archivo de selectores.

Si te gusta ser dueño del script de Playwright, quédatelo. Es una buena configuración. Si prefieres que se encarguen por ti de las capturas, de los artículos que las rodean y del mantenimiento, eso es lo que hace Ellie. Escribir las palabras que rodean esas imágenes también es un oficio aparte; consulta cómo escribir artículos de centro de ayuda que la gente realmente use.
Preguntas habituales
¿Qué resolución deben tener las capturas de pantalla de la documentación?
Captura al doble (deviceScaleFactor: 2) desde un viewport fijo de unos 1280 píxeles de ancho y muéstralas a la mitad de tamaño. Así obtienes imágenes nítidas en pantallas retina sin diseños enormes.
¿Debo capturar la página entera o solo una parte? Normalmente solo una parte. Recorta al elemento del que trata el paso, con un poco de contexto alrededor para que el lector pueda encontrarlo. Usa las capturas de página completa con moderación, para momentos del tipo «este es el diseño general».
¿Cómo evito que aparezcan datos reales de clientes en las capturas?
No captures nunca desde cuentas de producción. Usa una cuenta de demostración con datos de ejemplo, con nombres ficticios y correos de example.com, y enmascara lo que no puedas cargar de antemano, como los widgets de terceros.
¿Con qué frecuencia deben ejecutarse las capturas automáticas? En cada fusión a main si la ejecución es rápida, cada noche si no lo es. La idea es que nadie tenga que acordarse.
Si quieres que te lo den hecho, prueba Ellie Docs gratis. Conecta un repositorio y tendrás un centro de ayuda con capturas reales de tu app, sin necesidad de tarjeta.