Un monorepo (repositorio monolítico) es una arquitectura de gestión de código fuente donde múltiples proyectos, aplicaciones y bibliotecas compartidas coexisten en un único repositorio Git, gestionados por herramientas de orquestación como Nx, Turborepo o Lerna que optimizan los builds y las pruebas en función del grafo de dependencias.
Los monorepos han ganado. Los equipos front-end que gestionan múltiples aplicaciones — un sitio de marketing, un dashboard de administración, una app de cliente, un portal de socios — los agrupan en un solo repositorio. Es más simple para compartir código, más coherente para el design system, más eficiente para las actualizaciones transversales.
Pero para las pruebas visuales, es una pesadilla logística. No porque las pruebas visuales no funcionen en un monorepo. Funcionan perfectamente. El problema es que funcionan demasiado bien: un cambio en un paquete compartido desencadena potencialmente pruebas visuales en todos los proyectos que dependen de él. Y cuando tu monorepo contiene 15, 30 o 50 proyectos, "probar todo en cada commit" ya no es una opción.
El problema fundamental: el grafo de dependencias
En un monorepo, los proyectos no son independientes. Comparten paquetes: un design system, una biblioteca de utilidades, componentes comunes, configuraciones compartidas. Estas dependencias forman un grafo — y es este grafo el que hace compleja la prueba visual.
Tomemos un ejemplo concreto. Tienes un paquete "ui-components" que contiene tus botones, formularios y componentes de navegación. Este paquete es utilizado por 12 aplicaciones en tu monorepo. Modificas el padding de un botón en "ui-components". Visualmente, este cambio afecta potencialmente a las 12 aplicaciones. Cada página que contiene un botón podría renderizarse de manera diferente.
Si lanzas pruebas visuales en las 12 aplicaciones, capturas potencialmente cientos de screenshots. El pipeline CI/CD tarda 45 minutos. Los desarrolladores esperan. Y si una prueba falla — un falso positivo relacionado con un problema de renderizado headless — el desarrollador del paquete "ui-components" tiene que investigar un fallo en una aplicación que ni siquiera conoce.
Es insostenible. Y es exactamente lo que sucede en los monorepos que no tienen una estrategia de prueba visual.
Probar lo que cambió, no todo: el principio de afectación
La primera regla de la prueba visual en monorepo es simple en teoría, compleja en la práctica: probar solo lo que está afectado por el cambio.
Las herramientas de monorepo modernas — Nx y Turborepo a la cabeza — saben calcular el grafo de dependencias e identificar los proyectos "afectados" por un cambio. Cuando modificas un archivo en el paquete "ui-components", Nx puede decirte que las aplicaciones A, C, F y K dependen de este paquete, pero no B, D y las demás.
Es la base. Pero para la prueba visual, no es suficiente. Porque "la aplicación A depende de ui-components" no significa que todas las páginas de la aplicación A usen el componente modificado. Si cambiaste el botón, solo las páginas que contienen un botón están afectadas. Las páginas que no lo contienen son estables.
La prueba visual inteligente en monorepo opera por tanto en dos niveles de filtrado. Primer nivel: qué proyectos están afectados por el cambio, según el grafo de dependencias. Segundo nivel: qué páginas o componentes de esos proyectos utilizan realmente el elemento modificado.
El primer nivel lo resuelven las herramientas de monorepo. El segundo nivel es mucho más difícil — requiere un análisis estático del código (qué páginas importan qué componente) o un mapeo explícito mantenido por el equipo (este componente se usa en estas páginas).
La realidad de los paquetes compartidos
Los paquetes compartidos son la fuerza y la debilidad del monorepo. Permiten la coherencia: un único design system, una única fuente de verdad para los componentes visuales. Pero también crean un blast radius considerable.
Hay tres tipos de paquetes compartidos que plantean problemas específicos para las pruebas visuales.
Los paquetes de componentes UI. Es el caso más evidente. Un cambio en un botón, un formulario o un modal afecta visualmente a todas las páginas que los utilizan. El blast radius es proporcional a la popularidad del componente. Un componente de layout usado en todas partes (Header, Footer, Sidebar) tiene un blast radius máximo.
Los paquetes de estilos y tokens. Un cambio en los design tokens — colores, espaciados, tipografías — a menudo es invisible en el grafo de dependencias tradicional. Si modificas el color primario en tu archivo de tokens, el grafo de dependencias ve un cambio en el paquete "design-tokens". Pero este cambio afecta visualmente a todo: cada botón primario, cada enlace, cada elemento acentuado en todas las aplicaciones. El blast radius es total.
Los paquetes de utilidades con efectos visuales secundarios. Menos evidentes: las funciones utilitarias que formatean fechas, truncan texto o calculan layouts. Un cambio en una función de truncamiento de texto — pasar de 100 a 80 caracteres máximo — tiene un impacto visual directo en todos los componentes que la usan. Pero el grafo de dependencias no sabe que es un cambio "visual".
Las estrategias que funcionan
Tras observar a docenas de equipos gestionar las pruebas visuales en monorepos, estas son las estrategias que producen los mejores resultados.
Estrategia 1: la prueba visual por capas
Organiza tus pruebas visuales en tres capas con diferentes frecuencias de ejecución.
La capa de componente. Prueba cada componente del design system en aislamiento, mediante Storybook o equivalente. Estas pruebas se ejecutan únicamente cuando el paquete de componentes cambia. Son rápidas (unos minutos) y protegen la librería en sí. Es la primera red de seguridad, la descrita en el artículo sobre las pruebas visuales en design systems.
La capa de página afectada. Prueba las páginas de las aplicaciones afectadas por el cambio, identificadas por el grafo de dependencias. Estas pruebas se ejecutan en cada pull request, pero solo en los proyectos afectados. Son el núcleo de tu estrategia.
La capa completa. Prueba todas las páginas de todas las aplicaciones. Esta capa no se ejecuta en cada PR — es demasiado costosa. Ejecútala una vez al día (nightly), o antes de cada release. Atrapa las regresiones que el grafo de dependencias no supo predecir.
Estrategia 2: el mapeo componente-página explícito
Mantén un archivo de configuración que asocie cada componente compartido con las páginas que lo utilizan. Cuando el componente Button cambia, el archivo indica que las páginas /login, /signup, /checkout y /settings de la aplicación A usan ese componente. Solo esas páginas son probadas.
Este mapeo es tedioso de mantener manualmente. Pero puede generarse automáticamente mediante un análisis estático del código — recorriendo los imports de cada página y remontando las dependencias. Nx ofrece plugins que facilitan este tipo de análisis.
La ventaja es considerable: en lugar de probar 200 páginas de la aplicación A cuando un componente cambia, solo pruebas 12. El pipeline pasa de 30 minutos a 3 minutos.
Estrategia 3: la baseline compartida con override
En un monorepo con un design system común, las baselines visuales (los screenshots de referencia) tienen una particularidad: los componentes compartidos tienen el mismo renderizado en todas las aplicaciones (en teoría). Puedes por tanto mantener una baseline del design system a nivel del paquete, y solo recapturar las baselines a nivel de las aplicaciones cuando el contexto de integración cambia.
Concretamente: cuando modificas el componente Button, actualizas la baseline del Button en el paquete ui-components. Las aplicaciones que usan el Button heredan esta nueva baseline. Solo las aplicaciones donde el Button tiene un renderizado diferente en contexto (por CSS específico, tema u override) necesitan sus propias baselines.
Los errores clásicos a evitar
Probar todo, todo el tiempo. Es la reacción natural, y la peor. Tus pipelines se vuelven lentos, tus desarrolladores ignoran los resultados porque hay demasiado ruido, y los verdaderos bugs se ahogan en falsos positivos. La prueba visual en monorepo debe ser quirúrgica.
Ignorar el grafo de dependencias. Algunos equipos configuran sus pruebas visuales independientemente de la herramienta de monorepo. Resultado: las pruebas no saben qué proyectos están afectados y prueban todo o nada. Integra tu herramienta de prueba visual con Nx o Turborepo. Usa sus comandos "affected" para lanzar las pruebas correctas.
Poner todas las baselines en una sola carpeta. Las baselines visuales deben vivir junto a los proyectos que protegen. Si centralizas todas las baselines en una carpeta raíz, pierdes la granularidad: ya no sabes qué baseline corresponde a qué proyecto, y la limpieza de baselines obsoletas se vuelve imposible.
Descuidar el versionado de baselines durante las actualizaciones transversales. Cuando modificas un design token que afecta a todos los proyectos, todas las baselines deben actualizarse simultáneamente. Si las actualizas proyecto por proyecto en PRs separadas, creas una ventana donde algunos proyectos tienen las nuevas baselines y otros las antiguas. Las pruebas se vuelven inconsistentes.
El rol del CI/CD en la prueba visual de monorepo
La configuración CI/CD es crítica. Tu pipeline debe ser capaz de tres cosas.
Primero, calcular el conjunto de proyectos afectados por el cambio. Es el trabajo de Nx (nx affected) o Turborepo (turbo run --filter). Este paso determina el perímetro de las pruebas.
Segundo, paralelizar las pruebas visuales por proyecto. Si tres aplicaciones están afectadas, lanza las pruebas de las tres aplicaciones en paralelo, no en secuencia. Cada aplicación tiene su propio juego de baselines y su propio informe de resultados. La paralelización es la única forma de mantener tiempos de pipeline aceptables.
Tercero, agregar los resultados y bloquear la PR si es necesario. Aunque las pruebas estén paralelizadas, el veredicto final debe ser único: la PR pasa o no pasa. Si la aplicación A tiene una regresión visual y las demás no, la PR se bloquea. El desarrollador sabe exactamente qué aplicación está afectada y puede investigar.
Cuando el no-code lo simplifica todo
Las herramientas de prueba visual basadas en código — Playwright, Cypress con plugins visuales — se integran bien en un monorepo porque viven en el mismo repositorio, junto al código que prueban. Pero añaden código de prueba que mantener, configuraciones por proyecto, y scripts CI/CD específicos.
Las herramientas no-code como Delta-QA proponen un enfoque diferente. En lugar de probar desde el código fuente, prueban desde las URLs desplegadas. Configuras las URLs de cada aplicación, la herramienta captura los screenshots y los compara con las baselines. El monorepo ya no es un factor de complejidad — la herramienta solo ve URLs, no paquetes.
El inconveniente: no te beneficias del grafo de dependencias para filtrar las pruebas. La ventaja: la configuración es instantánea, no hay código de prueba que mantener, y la prueba es independiente de la arquitectura del repositorio. Para equipos que no tienen desarrolladores dedicados a las pruebas, a menudo es el compromiso adecuado.
FAQ
¿Nx o Turborepo es mejor para la prueba visual en monorepo?
Nx tiene una ventaja significativa gracias a su grafo de dependencias más detallado y sus plugins de análisis estático. El comando nx affected identifica con precisión los proyectos impactados, y los executors Nx permiten integrar tareas de prueba visual en el grafo de tareas. Turborepo es más simple pero ofrece un filtrado menos granular.
¿Cómo gestionar las baselines cuando un design token cambia y afecta a todo?
Trátalo como una actualización transversal. Crea una PR dedicada que modifique el token y actualice todas las baselines afectadas en una sola operación. Ejecuta la capa completa de pruebas visuales, aprueba los cambios esperados en lote y mergea. Nunca fragmentes una actualización de token en múltiples PRs — es la puerta abierta a las inconsistencias.
¿Cuánto tiempo debería tardar una prueba visual en un pipeline monorepo?
Apuntando solo a los proyectos afectados: menos de 10 minutos para una PR estándar que toca un solo proyecto. Menos de 20 minutos para un cambio en un paquete compartido que afecta de 3 a 5 proyectos. Si tus pruebas tardan más de 30 minutos en una PR, tu estrategia de filtrado es insuficiente. La capa completa (nightly) puede tardar más — de 30 a 60 minutos es aceptable.
¿Deberían existir baselines separadas por entorno (dev, staging, prod)?
Sí, si los entornos tienen contenidos o configuraciones diferentes. No, si el renderizado es idéntico. En la práctica, mantén una sola baseline por proyecto, capturada en un entorno de staging estable. Comparar contra producción es tentador, pero el contenido dinámico (fechas, datos de usuario, tests A/B) genera demasiados falsos positivos.
¿La prueba visual en monorepo funciona con Lerna?
Lerna es principalmente una herramienta de gestión de versiones y publicación de paquetes. Su grafo de dependencias es menos sofisticado que el de Nx o Turborepo. Puedes usarlo, pero probablemente necesitarás complementarlo con un script personalizado para identificar los proyectos afectados. Si empiezas un nuevo monorepo, prefiere Nx o Turborepo.
¿Cómo evitar que los desarrolladores ignoren los resultados de la prueba visual?
Tres reglas. Mantén la tasa de falsos positivos cerca de cero — si los desarrolladores ven falsos positivos regularmente, dejan de mirar. Bloquea las PRs en caso de fallos de prueba visual — sin merge sin aprobación. Y mantén los tiempos de pipeline cortos — si la prueba visual añade 45 minutos a la PR, los desarrolladores encontrarán formas de evitarla.
Para profundizar
- Test Visual y Contenido Dinámico: Cómo Probar Cuando Todo Cambia en Cada Carga
- Prueba Visual React Native: El Móvil, el Hijo Olvidado de la Prueba Visual
El monorepo es una excelente arquitectura para el intercambio de código y la coherencia. Pero sin una estrategia de prueba visual adaptada, transforma cada cambio en una lotería: ¿este commit rompió algo en un proyecto que ni siquiera conozco? La respuesta a esa pregunta nunca debería ser "no lo sé". Debería ser automática, rápida y fiable.