Cómo hacer pruebas de regresión visual con Backstop.js

Last Updated: 2020-05-05

¿Qué son las pruebas de regresión visual?

Las pruebas de regresión visual consisten en pruebas que se realizan sobre la interfaz gráfica de una aplicación y se fundamentan en la comparación de elementos gráficos representados como imágenes. Es decir, estas pruebas permiten ver diferencias entre varias imágenes al realizar una comparación de todos los píxeles de cada una de ellas.

No requieren una integración con la aplicación en cuestión dado que el único insumo necesario para llevarlas a cabo es la interfaz gráfica de una aplicación e incluso, en ocasiones, únicamente las imágenes. Esto facilita que la ejecución de dichas pruebas se realice de forma paralela con el desarrollo.

¿Por qué realizar pruebas de regresión visual?

Uno de los principales objetivos de las pruebas de regresión visual consiste en realizar comparaciones de las versiones de la interfaz gráfica para hallar el impacto que pueden tener ciertos cambios en el código del proyecto. Como su nombre lo indica, se busca hacer una regresión sobre los componentes visuales de la interfaz para llevar un rastro de los avances.

Otro de los objetivos más importantes es encontrar problemas que puedan surgir en la interfaz gráfica. Estos problemas pueden corresponder a múltiples ámbitos como, por ejemplo, la similaridad entre la interfaz propuesta en la etapa de diseño de UI y la interfaz que se ha ido desarrollando, la superposición entre componentes de la vista, la posición o tamaño relativo de componentes, o la adaptación de la interfaz gráfica ante los cambios en el tamaño del viewport, la orientación o tamaño de la pantalla. Este tipo de bugs visuales puede ser detectado con rapidez por medio de estas pruebas.

No obstante, este tipo de pruebas tiene una limitación en términos de su automatización, pues requiere que algunas etapas tengan intervención de un humano para definir si los hallazgos de estas pruebas corresponden a problemas de interfaz. Los resultados de la prueba deben ser interpretados, ya que establecer criterios de aceptación de forma automática no asegura que sean adecuadamente catalogadas como correctas o incorrectas. Esto es porque las pruebas suelen ser muy precisas y el margen de aceptación, o tolerancia, sea más flexible y difícil de determinar por parte del grupo de trabajo.

¿Qué aprenderá?

Al desarrollar este tutorial aprenderá:

Cómo ejecutar pruebas de regresión visual sobre una aplicación web.
Cómo generar reportes de comparación visual sobre una interfaz gráfica con dos herramientas.
Cómo realizar capturas de pantalla sobre una aplicación web que sean comparables entre sí.

En este caso se partirá de una aplicación web como base, por lo cual los aprendizajes respectivos al desarrollo de esta no se incluyen como parte del tutorial.

¿Qué construirá?

En el tutorial se dará una serie de instrucciones que le permitirán desplegar una aplicación web de prueba y, sobre ella, realizar pruebas de regresión visual. Al final del tutorial usted deberá tener:

Una copia de una aplicación web desarrollada en HTML+CSS+JavaScript de ejemplo desplegada en GitHub Pages desde su perfil de GitHub.
Un proyecto de Backstop.js con dos escenarios listos para generar reportes.
Un reporte de las diferencias en la interfaz gráfica de la aplicación base al interactuar con ella.

¿Qué necesita?

Conocimientos básicos de JavaScript.
Una versión actualizada de Node.js instalada en su computadora.
Una versión actualizada del manejador de paquetes npm instalada en su computadora.
Un navegador web (¡Cualquier navegador funciona!).
Una cuenta de GitHub.

Comprender el funcionamiento de la aplicación

Para el caso de este tutorial se hará uso de una aplicación web sencilla que permite generar paletas de colores aleatorias que pueden usarse dentro de las reglas CSS de otra página web. Se decidió que la paleta de colores incluyera únicamente 5 colores complementarios (o equidistantes) entre ellos, cuya generación se realiza de forma aleatoria usando un esquema de generación que consiste en variar la tonalidad de los colores en la escala HSB/HSV.

En esta escala de colores, la tonalidad (hue), representada en la H puede tomar valores entre 0 y 359, que representan los grados en el círculo cromático. La saturación y el brillo, representadas en la S y la B respectivamente, toman valores entre 0 y 1 para representar un porcentaje.

Así, la aplicación selecciona una tonalidad aleatoria y calcula las otras 4 que serían equidistantes en este círculo al sumar una cantidad igual de 360/5 grados (es decir, 72) para cada uno y normalizar el valor a la escala aceptada. Estos colores se muestran en la sección superior de la página web y las reglas CSS que los contienen se muestran en un textarea de la sección inferior.

Desplegar una versión propia de la aplicación

La versión base de la aplicación web se encuentra alojada en GitHub Pages en el siguiente enlace: https://monitor177.github.io/color-palette/. Así mismo, el código fuente se encuentra alojado en el repositorio de GitHub del siguiente enlace: https://github.com/monitor177/color-palette/.

Usted usará la aplicación base como una referencia de la interfaz y comparará esta aplicación con su propio despliegue. Antes de interactuar con la aplicación original, ingrese al enlace del repositorio y revise el código del proyecto alojado en el repositorio. Podrá ver la implementación de los esquemas de generación de la paleta de color mencionados en el apartado anterior.

Una vez termine de comprender el funcionamiento de la aplicación, cree un fork del repositorio haciendo clic en el botón correspondiente de la sección superior del repositorio, el cual se muestra en la siguiente imagen:

$Encabezado del repositorio con tres botones entre los cuales se encuentra \$

Imagen 1. Sección superior del repositorio con botón "Fork"

Al hacer clic en este botón, GitHub le redirigirá a su versión del repositorio. Desde allí, ingrese a la pestaña "Settings", la cual se muestra en la siguiente imagen:

$Sección superior del repositorio con la pestaña settings seleccionada\n$

Imagen 2. Pestaña "Settings" del repositorio nuevo

En las configuraciones del repositorio, diríjase a la sección titulada "GitHub Pages". Desde allí va a configurar su repositorio para que despliegue la aplicación contenida en el código fuente como un sitio web estático alojado en GitHub Pages. Haga clic en el botón desplegable que hace referencia a la fuente en la sección "Source" y con el texto "None", el cual se muestra en la siguiente imagen:

Apartado para configurar un despliegue del proyecto a un sitio web estático de GitHub con un botón en la sección Source que muestra las ramas del repositorio

Imagen 3. Sección de GitHub Pages para elegir la fuente del código

Este botón mostrará varias opciones para alimentar el código del sitio web estático. Elija la primera, llamada "master branch" para desplegar una página web a partir del código que se encuentra en la rama principal del repositorio. Podrá ver un mensaje de confirmación como el de la imagen a continuación, el cual indica un despliegue exitoso y contiene la dirección URL donde se encuentra la aplicación.

Acceder e interactuar con la aplicación

Ingrese a la URL del sitio web de referencia en el siguiente enlace: https://monitor177.github.io/color-palette/. Explore rápidamente los elementos de la interfaz y genere varias paletas de colores con los botones de la parte inferior para ver ejemplos de colores aleatorios que pueden surgir con este esquema de generación. Las interacciones de la aplicación son limitadas y podrían resumirse en el siguiente gif:

$Interacción básica: varios clics en el botón \$

Imagen 4. Interacción de ejemplo con la aplicación web

Para familiarizarse con las pruebas de regresión visual, usted hará comparaciones entre varios aspectos visuales de la misma interfaz gráfica. La aplicación que se eligió permite tener variaciones inesperadas pero predecibles sobre la interfaz y, por ende, le permitirán comprender las particularidades de las herramientas de regresión.

Ingresar al sitio inicial

El paso inicial de la prueba debe ser el de acceder a la URL donde se aloja la página web haciendo uso de una herramienta que simule o se base en el comportamiento de un navegador. Es importante tener en cuenta el viewport o tamaño de la ventana del navegador para poder comparar con otras imágenes de la interfaz que manejen la misma escala.

Esta herramienta debe capturar una imagen que muestre el aspecto de la interfaz de la aplicación. Esta captura será tomada como el punto de referencia y comparación ante los cambios durante la prueba.

Comparar la interfaz luego de una interacción

Tal como usted probablemente lo hizo al momento de interactuar con la aplicación, el siguiente paso consiste en hacer clic en el botón de generar una paleta de colores para inducir un cambio en el aspecto visual de la interfaz. Cuando este cambio surta efecto, se debe capturar una imagen que muestre el aspecto modificado de la interfaz. Esta captura podrá compararse ahora con la imagen de referencia para detallar las diferencias gráficas y esta comparación podrá ser luego interpretada por el evaluador de la prueba (usted).

Backstop.js es una herramienta interesante para realizar comparaciones visuales y obtener información a partir de imágenes sobre una interfaz gráfica se llama Backstop.js. Ésta permite generar reportes de comparación sobre una aplicación web haciendo uso de JavaScript y HTML. Se distribuye como una herramienta de línea de comandos integrada con Node.js y permite extraer información de la interfaz y realizar comparaciones visuales. Para conocer el detalle del API, diríjase a la documentación en el siguiente enlace: https://github.com/garris/BackstopJS/blob/master/README.md

Instalar las dependencias

Para hacer uso de las herramientas de Backstop, debe descargar la CLI. Abra una terminal y ejecute el siguiente comando:

npm install -g backstopjs

Esto descargará Backstop en su máquina. Ahora, en la misma terminal, ubíquese en el directorio donde ubicará el nuevo directorio del proyecto con el comando cd <ruta>. Desde allí, ejecute el siguiente comando:

backstop init

Esto creará un nuevo directorio para su proyecto de Backstop con una estructura de archivos sobre la cual podrá configurar las interacciones de la prueba.

Comprender la estructura del proyecto

Ahora que tiene su proyecto, puede abrir la carpeta en el explorador de archivos para conocer los contenidos. En principio, podrá ver un archivo llamado backstop.json y un directorio llamado backstop_data. El archivo backstop.json contendrá la información crucial de configuración para definir cómo se ejecutará la prueba. Verá varias propiedades allí definidas, las cuales se explican en detalle en la documentación oficial y que usted modificar en breve. En cuanto a los contenidos del directorio backstop_data, podrá ver un subdirectorio llamado engine_scripts, el cual contiene el código fuente necesario para que Backstop pueda lanzar un navegador y ejecutar con el sitio web indicado en el archivo de configuración. Este directorio, luego de ejecutar pruebas, contendrá otros subdirectorios llamados bitmaps_reference, con las imágenes de referencia; bitmaps_test, con las imágenes capturadas durante la prueba, y html_report con los reportes generados para la comparación visual.

Para configurar la prueba, abra el archivo backstop.json en algún editor de texto y asegúrese de que tenga el siguiente contenido:

{
  "id": "backstop_default",
  "viewports": [
    {
      "label": "default",
      "width": 800,
      "height": 600
    }
  ],
  "onBeforeScript": "puppet/onBefore.js",
  "onReadyScript": "puppet/onReady.js",
  "scenarios": [
    {
      "label": "Inicio",
      "url": "https://monitor177.github.io/color-palette/",
      "referenceUrl": "https://monitor177.github.io/color-palette/",
      "readyEvent": "",
      "readySelector": "",
      "delay": 0,
      "hideSelectors": [],
      "removeSelectors": [],
      "hoverSelector": "",
      "clickSelector": "",
      "postInteractionWait": 0,
      "selectors": [],
      "selectorExpansion": true,
      "expect": 0,
      "misMatchThreshold" : 0.1,
      "requireSameDimensions": true
    },
    {
      "label": "Paleta de colores",
      "url": "https://monitor177.github.io/color-palette/",
      "referenceUrl": "https://monitor177.github.io/color-palette/",
      "readyEvent": "",
      "readySelector": "",
      "delay": 0,
      "hideSelectors": [],
      "removeSelectors": [],
      "hoverSelector": "",
      "clickSelector": "#generate",
      "postInteractionWait": 1,
      "selectors": [],
      "selectorExpansion": true,
      "expect": 0,
      "misMatchThreshold" : 0.1,
      "requireSameDimensions": true
    }
  ],
  "paths": {
    "bitmaps_reference": "backstop_data/bitmaps_reference",
    "bitmaps_test": "backstop_data/bitmaps_test",
    "engine_scripts": "backstop_data/engine_scripts",
    "html_report": "backstop_data/html_report",
    "ci_report": "backstop_data/ci_report"
  },
  "report": ["browser"],
  "engine": "puppeteer",
  "engineOptions": {
    "args": ["--no-sandbox"]
  },
  "asyncCaptureLimit": 5,
  "asyncCompareLimit": 50,
  "debug": false,
  "debugWindow": false
}

Como puede ver, allí se define una propiedad llamada id para identificar la prueba, un único viewport con las mismas dimensiones para la ventana que se utilizaron en la prueba de Resemble.js, unos scripts onBefore y onReady por defecto (que se encuentran en engine_scripts) y dos escenarios que, respectivamente, harán referencia a las capturas de la pantalla inicial del sitio (sin interactuar) y a las capturas de la pantalla luego de interactuar con el botón para generar una paleta de colores. Además de esto, hay otras propiedades para la configuración de la prueba que indican la ruta de cada directorio mencionado en la sección anterior, la configuración del motor de la prueba y otras características.

Definir un punto de referencia

En el archivo de configuración del apartado anterior puede notar que los escenarios tienen dos direcciones URL definidas. Una de ellas corresponde al sitio a probar y otra corresponde al sitio de referencia (que es el sitio web desplegado en el GitHub Pages del monitor). La interfaz gráfica expuesta en este sitio será el punto de referencia para la aplicación que usted desplegó a partir del mismo código fuente. Como indica la documentación de Backstop.js, sus pruebas tendrán un directorio con imágenes de referencia y un directorio con imágenes de cada ejecución de la prueba. Inicialmente, usted no contará con imágenes de referencia. Estas las debe capturar a partir de una prueba. Para esto, ejecute el siguiente comando:

backstop test

Esto ejecutará una prueba que captura imágenes y busca las imágenes de referencia para comparar y, al finalizar, lanzará en su navegador un reporte en formato HTML indicando los hallazgos de la prueba. Dado que no existen referencias en el momento, el reporte mostrará un error como el de la siguiente imagen:

$BACKSTOP ERROR: Reference file not found backstop\\backstop_data\\bitmaps_reference\\backstop_default_Inicio_0_document_0_default.png\n$

Imagen 5. Error de Backstop.js al no encontrar archivos de referencia

En la misma terminal donde ejecutó el anterior comando, ejecute el siguiente comando:

backstop approve

Esto guardará los resultados de la prueba más reciente como la referencia y creará el directorio bitmaps_reference. Desde el explorador de archivos revise sus contenidos y podrá ver un archivo de imagen para cada escenario indicado en el archivo de configuración, como se muestra en la siguiente imagen:

Dos archivos backstop_default_inicio_0_document_0_default .png y backstop_default_inicio_0_document_0_default.png

Imagen 6. Contenidos de la carpeta de referencia

Definir y ejecutar las interacciones

Ahora que ya cuenta con imágenes de referencia, va a realizar un par de modificaciones sobre el archivo de configuración para comparar las interfaces de referencia con la interfaz de su instancia de la aplicación luego de generar paletas de colores. De esta forma, las pruebas buscarán comparar entre el sitio inicial sin colores y luego de generar una paleta de colores, y también comparar entre dos paletas de colores distintas.

Para esto, abra nuevamente el archivo backstop.json y asegúrese que tanto la primera como la segunda prueba tengan el valor "#generate" para el atributo "clickSelector", el valor 1 para el atributo "postInteractionWait" y la ruta de su sitio web de GitHub Pages en el atributo "url". La sección "scenarios" de su archivo debe verse como en la siguiente imagen:

JSONArray con dos objetos que usan la url de su sitio web, la url de referencia del sitio del monitor, el mismo selector para hacer clic en el boton de generar y con las propiedades estándar.

Imagen 7. Sección de escenarios en el archivo backstop.json

Ahora ejecute nuevamente el comando backstop test para comparar las imágenes que se obtienen en esta prueba con las que obtuvo previamente.

Generar y comprender los reportes

Cada vez que ejecute el comando backstop test, se modificará el archivo index.html que contiene el reporte, ubicado en el directorio html_report para mostrar las nuevas imágenes y sus diferencias. Este reporte muestra cada uno de los escenarios configurados para la prueba como se ve en las siguientes imágenes:

Sección etiquetada como Inicio con una imagen reference sin color y una imagen test con colores y una imagen señalando los pixeles con color distinto

Imagen 8. Escenario 1 de la prueba: Estado inicial vs paleta de colores

Sección etiquetada como Paleta de colores con una imagen reference y una imagen test con colores ligeramente distintos y una imagen señalando los pixeles con color distinto

Imagen 9. Escenario 2 de la prueba: Dos paletas de colores aleatorias comparadas entre sí

Así mismo, el reporte indica que ambos escenarios de prueba fallaron a pesar de que el comportamiento de la interfaz era muy predecible y se comportó según lo esperado. Si posiciona el cursor sobre el nombre de cada escenario, junto a la palabra "filename", podrá ver información acerca de la comparación de las imágenes de referencia y las de prueba. Allí verá un porcentaje de diferencia entre las imágenes, que tendrá un valor entre 5% y 6%.

Este porcentaje es muy bajo y parece indicar diferencias menores entre las imágenes. Sin embargo, el fallo se debe a que en el archivo de configuración se definió la propiedad misMatchThreshold para cada escenario con un valor de 0.1%.

Como se mencionó en la sección introductoria del tutorial, estimar un valor óptimo para este porcentaje es complicado, ya que el porcentaje de diferencia incluye varios aspectos como posiciones (x,y), tamaños, rotaciones, colores y texturas; y en ocasiones un mismo valor de diferencia porcentual indica una diferencia que puede tener o no impacto sobre la calidad de la interfaz gráfica. Por este motivo, es necesario que la prueba de regresión visual tenga un evaluador que determine cuándo una diferencia es válida y cuándo no. Ahora que llegó hasta acá, modifiqué la propiedad misMatchThreshold por 8, dado que la diferencia entre las imagenes es menor a este valor las pruebas pasaran.

Como lo pudo notar, las pruebas de regresión visual son bastante rápidas y se basan en principios sencillos. Haciendo uso de herramientas especializadas en análisis de imágenes se puede efectuar comparaciones entre imágenes y hallar diferencias detalladas con un buen nivel de exactitud; a partir de estas comparaciones un evaluador de la prueba puede determinar si los cambios en la interfaz gráfica son significativos y representan un impacto negativo sobre la calidad de la aplicación.

El proceso para ejecutar la prueba puede variar un poco según la herramienta que se esté utilizando, pero la intención se mantiene y es hallar diferencias visuales. En los reportes generados, puede ver que la comparación entre las imágenes se basa en capturar las diferencias de los pixeles de las posiciones equivalentes y mostrarlas en una sola imagen.

En el caso de Resemble.js, la librería ofrece únicamente las funcionalidades de análisis y comparación de imágenes y cede al desarrollador la responsabilidad de integrarlas con otras herramientas para automatizar la generación de reportes.

Es importante resaltar que los porcentajes de diferencia calculados no son absolutos y pueden variar según la herramienta y los parámetros que se eligen para la función.

¡Felicidades!

Al completar este tutorial usted pudo familiarizarse mejor con las pruebas de regresión visual.

Ahora conoce y maneja una herramienta de JavaScript que le permiten comparar su interfaz gráfica en distintos momentos para rastrear cambios o detectar errores, y podrá utilizarla para realizar pruebas de regresión visual sobre otras de sus aplicaciones web.

Créditos

Versión 1.0 - Mayo 30, 2020

Juan Sebastián Espitia Acero	Autor
Norma Rocio Héndez Puerto	Revisora
Mario Linares Vásquez	Revisor