Cómo automatizamos 60 capturas de pantalla con Playwright

Cada vez que cambiábamos un botón, un diálogo o un panel en Ofusca, había que repetir el mismo ritual: abrir la app, navegar al estado correcto, hacer captura, recortar, exportar, reemplazar el archivo. Multiplicado por más de 60 capturas de pantalla repartidas en 46 secciones de ayuda, el proceso consumía horas que deberían haberse dedicado a escribir código. Para una comparativa más detallada, en regresión visual con pixelmatch analizamos las diferencias. Hablamos de esto con más detalle en variables de entorno en scripts E2E.

Decidimos que un navegador automatizado lo hiciera por nosotros. Este artículo explica cómo usamos Playwright para generar todas las capturas de la página de Ayuda de Ofusca de forma reproducible, consistente y en dos formatos optimizados.

Qué es Ofusca y por qué necesita tantas capturas

Ofusca es una herramienta web de censura de documentos que funciona 100 % en el navegador, ningún archivo sale del dispositivo del usuario. Permite aplicar efectos de censura (sólido, blur, píxel, trama, trazo, sello), detectar caras automáticamente, buscar texto con OCR, procesar lotes de imágenes, firmar documentos con esteganografía y mucho más.

La página de Ayuda integrada tiene 7 categorías y 46 secciones con documentación visual completa. Cada sección muestra la interfaz en un estado específico: un diálogo abierto, un panel desplegado, un resultado de detección. Mantener esas imágenes actualizadas manualmente era insostenible.

Por qué Playwright y no otra herramienta

Evaluamos varias opciones antes de decidirnos:

• Capturas manuales, lo que queríamos eliminar. Lentas, inconsistentes y propensas a errores humanos (resolución incorrecta, estado incompleto).
• Puppeteer. Solo Chromium. Playwright soporta Chromium, Firefox y WebKit desde la misma API.
• Cypress. Orientado a testing, no a generación de assets. Configuración más pesada para este caso de uso.
• Playwright. API nativa de capturas, selectores potentes, control total del viewport y soporte para interacciones complejas (arrastrar, hacer clic en coordenadas, esperar animaciones).

Playwright ofrece exactamente lo que necesitábamos: lanzar un navegador, llevar la interfaz a un estado preciso y fotografiarla. Sin más.

La configuración base

El punto de partida es un playwright.config.ts mínimo. No necesitamos reporters, ni paralelismo agresivo, ni reintentos: el script corre en local contra el servidor de desarrollo.

import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./screenshots",
  timeout: 60_000,
  use: {
    baseURL: "http://localhost:5173",
    screenshot: "off", // las tomamos manualmente
    viewport: { width: 1440, height: 900 },
  },
  projects: [
    {
      name: "desktop",
      use: { ...devices["Desktop Chrome"] },
    },
  ],
});

Fijamos el viewport a 1440 × 900 para todas las capturas de escritorio. Esto garantiza que cada imagen tenga las mismas dimensiones y que los elementos de la interfaz aparezcan siempre en la misma posición relativa.

El script de captura, paso a paso

El núcleo es una función auxiliar que encapsula la lógica de captura y conversión:

import { type Page } from "@playwright/test";
import sharp from "sharp";
import path from "node:path";

const HELP_DIR = path.resolve("public/help");

async function capture(page: Page, name: string) {
  const pngPath = path.join(HELP_DIR, `${name}.png`);
  const webpPath = path.join(HELP_DIR, `${name}.webp`);

  // Captura PNG a resolución completa
  await page.screenshot({ path: pngPath, fullPage: false });

  // Convierte a WebP con calidad 80 (buen equilibrio tamaño/calidad)
  await sharp(pngPath).webp({ quality: 80 }).toFile(webpPath);

  console.log(`✓ ${name} → PNG + WebP`);
}

Cada llamada a capture() produce dos archivos: el PNG original (fallback para navegadores antiguos) y una versión WebP optimizada. Así, el componente de la ayuda puede servir el formato más eficiente según el soporte del navegador.

Preparar el estado de la interfaz

Antes de fotografiar, hay que llevar la aplicación al estado exacto que queremos documentar. Aquí es donde Playwright brilla: podemos cargar un documento de ejemplo, abrir diálogos, seleccionar herramientas y esperar a que las animaciones terminen.

import { test } from "@playwright/test";

test("capture help screenshots", async ({ page }) => {
  await page.goto("/");

  // Cargar documento de demostración
  await page.click('button:has-text("Probar con documento de ejemplo")');
  await page.waitForSelector("canvas", { state: "visible" });

  // ─── Panel de efectos ───
  await capture(page, "effects-panel");

  // ─── Detección de caras ───
  await page.click('button:has-text("Detección de caras")');
  await page.waitForSelector('[role="dialog"]', { state: "visible" });
  await capture(page, "det-caras");
  await page.click('button:has-text("Cancelar")');

  // ─── Procesamiento por lotes ───
  await page.click('button:has-text("Lotes")');
  await page.waitForSelector('[role="dialog"]', { state: "visible" });
  await capture(page, "batch-mode");
  await page.click('button:has-text("Cancelar")');

  // ─── Censura automática ───
  await page.click('button:has-text("Auto-censurar")');
  await page.waitForTimeout(1500); // esperar resultado de detección
  await capture(page, "auto-censurar");
});

Cada bloque sigue el mismo patrón, navegar → esperar → capturar → cerrar. Al encadenar todas las capturas en un solo test, aprovechamos que la aplicación ya está cargada y evitamos reiniciar el navegador 60 veces.

Capturando estados complejos de la interfaz

No todas las capturas son tan simples como hacer clic en un botón. Algunos estados requieren interacciones elaboradas:

Diálogos modales

Ofusca muestra diálogos para detección de caras, verificación de censura, procesamiento por lotes y más. Cada uno se abre con una acción específica y necesita tiempo para cargar datos.

El diálogo de detección de caras, por ejemplo, necesita que el modelo de IA local termine de procesar antes de que podamos capturar el resultado con las tres caras identificadas y sus porcentajes de confianza.

Panel de efectos y herramientas

El panel lateral muestra los siete efectos de censura disponibles. Para capturarlo en su estado completo, necesitamos que un documento esté cargado y el panel visible:

Procesamiento por lotes

El modo de lotes permite aplicar un perfil de censura a múltiples imágenes. El diálogo necesita estar limpio, sin archivos cargados, para la captura de documentación:

Resultados de censura automática

La censura automática combina detección de caras y OCR para identificar datos sensibles. La captura muestra el resumen de elementos censurados:

De PNG a WebP: optimización automática

Cada captura se genera en dos formatos. El PNG sirve como fallback universal; el WebP reduce el peso drásticamente sin pérdida perceptible de calidad.

La conversión usa sharp, la librería de procesamiento de imágenes más rápida del ecosistema Node.js:

import sharp from "sharp";
import { readdir } from "node:fs/promises";
import path from "node:path";

async function convertAllToWebP(dir: string) {
  const files = await readdir(dir);
  const pngs = files.filter((f) => f.endsWith(".png"));

  for (const file of pngs) {
    const input = path.join(dir, file);
    const output = input.replace(/\.png$/, ".webp");

    const { size: pngSize } = await sharp(input).metadata();
    await sharp(input).webp({ quality: 80 }).toFile(output);
    const { size: webpSize } = await sharp(output).metadata();

    const reduction = ((1 - (webpSize ?? 0) / (pngSize ?? 1)) * 100).toFixed(1);
    console.log(`${file}: ${reduction}% más pequeño en WebP`);
  }
}

Los resultados de compresión son notables. Algunos ejemplos reales de nuestras capturas:

• effects-panel.png, de 48 KB a 5 KB en WebP (90 % de reducción)
• det-caras.png, de 689 KB a 17 KB en WebP (97 % de reducción)
• auto-censurar.png, de 688 KB a 17 KB en WebP (97 % de reducción)
• batch-mode.png, de 21 KB a 2 KB en WebP (90 % de reducción)
• editor.png, de 316 KB a 22 KB en WebP (93 % de reducción)

De media, las versiones WebP pesan entre un 90 % y un 97 % menos que los PNG originales. Para una página de ayuda que carga docenas de imágenes bajo demanda, la diferencia es enorme.

Integración en la página de ayuda

En el lado del frontend, un componente Img se encarga de servir el formato adecuado usando la etiqueta <picture> de HTML5:

export function Img({ src, alt, className = "" }: {
  src: string;
  alt: string;
  className?: string;
}) {
  const webpSrc = src.replace(/\.(png|jpe?g)$/i, ".webp");

  return (
    <picture>
      <source srcSet={webpSrc} type="image/webp" />
      <img
        src={src}
        alt={alt}
        className={className}
        loading="lazy"
      />
    </picture>
  );
}

El navegador elige automáticamente WebP si lo soporta; en caso contrario, carga el PNG. La propiedad loading="lazy" asegura que solo se descarguen las imágenes visibles en el viewport, lo cual es crítico cuando la página contiene más de 60.

Y así es como se ve la página de Ayuda completa, con todas las capturas generadas por Playwright:

La experiencia es idéntica en escritorio y en móvil: las imágenes se adaptan al ancho disponible y la navegación cambia de barra lateral a acordeón.

Los números que importan

Después de implementar la automatización, estos son los datos concretos:

• 62 pares de imágenes (PNG + WebP) generados de forma automática.
• 46 secciones de ayuda cubiertas con capturas actualizadas.
• 7 categorías documentadas visualmente: inicio, censura, PDF, detección inteligente, seguridad, colaboración y productividad.
• ~93 % de reducción de peso medio al convertir de PNG a WebP.
• Un comando para regenerar todas las capturas tras un cambio en la interfaz.

Lo que antes llevaba una mañana entera ahora toma menos de dos minutos: el tiempo que Playwright necesita para recorrer todos los estados de la interfaz, capturar y convertir.

Lecciones para tu propio proyecto

Si mantienes documentación visual de cualquier tipo, estas son las ideas clave que nos llevamos:

1. Fija el viewport. Todas las capturas deben compartir las mismas dimensiones. Esto elimina inconsistencias visuales y hace que la documentación se sienta profesional.
2. Un test, muchas capturas. Encadena las capturas en un solo flujo para aprovechar el estado cargado de la aplicación. Reiniciar el navegador por cada imagen es innecesariamente lento.
3. Espera explícitamente. Usa waitForSelector o waitForTimeout antes de capturar. Las animaciones y las cargas asíncronas producen capturas incompletas si no se espera lo suficiente.
4. Genera dos formatos. PNG como fallback, WebP para navegadores modernos. La reducción de peso justifica el paso extra con creces.
5. Usa <picture> en el frontend. Es la forma estándar de servir formatos condicionales sin JavaScript adicional.
6. Lazy loading siempre. Con loading="lazy" nativo, las imágenes fuera del viewport no se descargan hasta que el usuario hace scroll. Imprescindible cuando tu página tiene docenas de capturas.

La mejor documentación es la que se actualiza sola. Si cada cambio en la interfaz requiere trabajo manual para mantener las capturas al día, tarde o temprano dejarás de hacerlo. Automatízalo desde el principio.

El código de Ofusca y su página de ayuda están en producción. Si quieres ver el resultado final de este flujo de trabajo, visita ofusca.josemanuelortega.dev y pulsa el botón de ayuda (?).

Otra entrega de la serie Playwright en profundidad. El siguiente post es Playwright como motor de testing de JMO Labs.