Probablemente cada dolor conoce este dolor: documentación irrelevante. No importa cuánto lo intente el equipo, en proyectos modernos lanzaremos tan a menudo que es casi imposible describir todos los cambios. Nuestro equipo de prueba, junto con analistas de sistemas, decidió intentar revitalizar nuestra documentación de proyecto.
Los proyectos web de Alfa-Bank utilizan el marco de automatización de pruebas de
Akita , que se utiliza para los scripts de BDD. Hasta la fecha, el marco ha ganado gran popularidad debido a su bajo umbral de entrada, usabilidad y la capacidad de probar el diseño. Pero decidimos ir más allá, sobre la base de los escenarios de prueba descritos, para generar documentación, lo que reduce en gran medida el tiempo que los analistas dedican al eterno problema de actualizar la documentación.
De hecho, junto con Akita, ya se utilizó un complemento de generación de documentación, que siguió los pasos de los scripts y los subió al formato html, pero para que este documento sea popular, tuvimos que agregar:
- Capturas de pantalla
- valores de variables (archivo de configuración, cuentas de usuario, etc.);
- estados y parámetros de consulta.
Analizamos nuestro complemento existente, que era, de hecho, un analizador estático y la documentación generada basada en los scripts descritos en los archivos .feature. Decidimos agregar altavoces, y para que el complemento no parezca un complemento, decidimos escribir el nuestro.
Primero, decidimos descubrir cómo podemos recopilar capturas de pantalla y valores de variables utilizadas en los scripts de prueba a partir de archivos de características. Todo resultó ser bastante simple. Cucumber, cuando ejecuta pruebas para cada archivo de características, crea un cucumber.json separado.
Dentro de este archivo contiene los siguientes objetos:
Nombre del caso de prueba y palabra clave:
Arreglos de elementos: los scripts y los pasos mismos:
El campo de salida contiene información adicional, por ejemplo, variables: direcciones, enlaces, cuentas de usuario, etc.
Las incrustaciones contienen capturas de pantalla que el selenio toma durante las pruebas:
Por lo tanto, solo tenemos que revisar los archivos cucumber.json, recopilar los nombres de las suites de prueba, los scripts de prueba, extraer los pasos, recopilar información adicional y capturas de pantalla.
Para que la documentación muestre las solicitudes que se producen en segundo plano o para una acción específica, tuvimos que pedir ayuda a nuestros desarrolladores frontales. Con la ayuda del proxy, pudimos capturar traceId, que genera solicitudes de servicio front-end. Por el mismo traceId, los registros se escriben en elástico, desde donde extraemos todos los parámetros de consulta necesarios en el informe de prueba y la documentación.
Como resultado, obtuvimos un archivo en formato Asciidoc, un formato de archivo conveniente, un poco más complicado que el análogo de reducción, pero tiene muchas más opciones de formato (puede insertar una imagen o una tabla, que no se puede hacer en reducción).
Para convertir el Asciidoc resultante a otros formatos, utilizamos Ascii doctorj, que es la versión oficial de la herramienta AsciiDoctor Java. Como resultado, obtenemos documentación preparada en formato html, que se puede descargar en confluencia, enviar a un colega o poner en el repositorio.
¿Cómo conectarse?
Ahora, para generar documentación de front-end para su proyecto, solo necesita conectar el complemento de documentación y después de ejecutar todas las pruebas, ejecute el comando
adoc .
¿Qué queremos mejorar?
- Agregue pasos técnicos configurables.
En la versión actual del complemento hay pasos "Y se tomó una captura de pantalla ...". Dichos pasos no llevan una carga semántica para la documentación, y queremos ocultarlos. Ahora los hemos cosido dentro del complemento, y se omiten, pero hay un inconveniente: cada adición de este paso lleva al hecho de que necesitamos construir una nueva versión del complemento. Para evitar esto, planeamos transferir dichos pasos al archivo de configuración y anotar aquellos pasos que no queremos ver en los scripts. - Crea un plugin de sourse abierto.
¿Qué equipos son adecuados para nuestra implementación?
- usar pepino (o un marco similar);
- desea tener documentación actualizada para el frente y la base de conocimiento;
- Quieren involucrar a los analistas en las pruebas.
Resultado:
La prueba piloto en varios equipos demostró que, con la ayuda del complemento que logramos mantener actualizada la documentación, los analistas ya no necesitan dedicar su tiempo a mantenerla. Además, la implementación de esta característica nos hizo pensar en continuar implementando BDD en todos los equipos. Hoy estamos llevando a cabo un experimento: los analistas formulan una ruta positiva para el cliente, indican restricciones comerciales utilizando pasos de Akita BDD, probadores, a su vez, escriben pasos personalizados y verificaciones adicionales para estos escenarios.
Por cierto, sobre holivar, ya sea que se necesite o no BDD, el lunes celebraremos una
reunión especial .