Integrando ApprovalsJS con WebStorm

Contexto.

En nuestro curso Cambiando Legacy exploramos diferentes maneras de caracterizar código legado. Una de las que explicamos es approval testing.

Approval testing facilita la aplicación de la técnica de Golden Master, aportando una herramienta que nos ayuda con algunos de los pasos más complicados y/o engorrosos de la técnica de Golden Master:

• la comparación entre el resultado real y el aprobado (golden master),
• la visualización de las diferencias entre ellos (si las hay), y
• el proceso de aprobación de un nuevo resultado válido (actualización del golden master).

En una edición reciente del curso que tuvo Typescript como lenguaje conductor, utilizamos la librería Approvals JS para demostrar cómo aplicar approval testing.

Approvals JS es la versión para Node de la herramienta Approvals que está disponible en varios lenguajes, siendo probablemente la de Java la más popular y mantenida.

El problema o, más bien, nuestras necesidades.

Aunque también se puede usar Visual Studio Code en el curso, el IDE que utilizamos para nuestras demos es WebStorm porque es el que nosotros solemos usar para desarrollar.

Cuando existe una diferencia entre el resultado real y el resultado aprobado, Approvals JS lanza una diff tool para facilitarnos la detección de las diferencias entre ambos resultados, y así ayudarnos a determinar el origen de dichas diferencias.

Approvals define una abstracción para esta responsabilidad de facilitar la detección de diferencias entre los resultados real y aprobado: el Report^[1]. Dicha abstracción se implementa con adaptadores concretos que utilizan diferentes herramientas de diff.

Approvals JS viene configurado con una lista de Reports que usa de manera priorizada, es decir, empieza por intentar ejecutar el primer Report de la lista, si lo encuentra y todo va bien usa ese, y si no pasa a intentar ejecutar el siguiente de la lista, y así sucesivamente.

En nuestro caso, no nos interesaba utilizar (ni siquiera las teníamos instaladas) ninguna de las herramientas de diff configuradas por defecto, (BeyondCompare, Diffmerge, P4merge, Tortoisemerge, etc.), sino que queríamos usar la propia herramienta de diff de WebStorm para no tener que cambiar de contexto y tener una experiencia de desarrollo más fluida^[2].

El problema es que no existía un Report por defecto para trabajar con Webstorm.

La solución: escribir un Report para WebStorm.

Para cubrir nuestras necesidad de usar la propia herramienta de diff de WebStorm y tener una experiencia de desarrollo más fluida no nos quedó otra que escribir un adaptador de la abstracción Report que use la herramienta de diff de WebStorm.

Este es el código de nuestro WebStormReporter:

Approvals JS actualmente puede integrarse con 2 runners, Jest y Mocha. Nosotros nos limitamos a hacer funcionar nuestro WebStormReporter con Jest porque es el runner que utilizamos en el curso. Si necesitas utilizar WebStorm con Mocha mira la documentación para ver cómo modificarlo.

Para usar WebStormReporter, basta con llamar en los tests a la función verifyAsJson^[3] que exportamos en vez de la función que proporciona Jest.

Conclusión.

Hemos mostrado cómo, gracias a la abstracción Report de Approvals, se puede conseguir integrar de manera sencilla Approvals JS con Webstorm.

En un futuro post, hablaremos de qué tuvimos que hacer para poder combinar approval testing y mutation testing de forma integrada dentro Webstorm.

Agradecimientos.

Nos gustaría agradecer a las tres empresas que hasta ahora han confiado en nosotros para ayudar a sus equipos a mejorar cómo trabajan con su código legacy. Ya hemos dado cuatro ediciones del curso Cambiando Legacy que han tenido muy buen feedback y nos han permitido refinar su contenido.

Por último, también nos gustaría darle las gracias a Markus Spiske por la foto del post.

Notas.

[1] Approvals define toda una serie de abstracciones fundamentales (Writer, Reporter, Namer..) que permiten extender su comportamiento y adaptarla en caso de que sea necesario.

[2] Además estamos acostumbrados a ella porque la usamos regularmente para resolver conflictos en merges o visualizar cambios en la Local History.

[3] JestApprovals tiene otros métodos como verify y verifyAll. Nosotros utilizamos verifyAsJson porque necesitábamos comparar objetos y nos resultaba más cómodo hacerlo usando el formato JSON. Es por esto que sólo nos hemos preocupado de proporcionar una versión de verifyAsJson que use nuestro WebStormReporter.