Gestión de especificaciones de prueba con Git: Creación de Excel desde Markdown


¿Estás escribiendo una especificación de prueba?

Hay varias formas de redactar especificaciones de prueba, como hacerlas como especificaciones de prueba o como código de prueba, dependiendo de la empresa. Creo que es común que las empresas grandes y históricas creen especificaciones de prueba en archivos de Excel. Al editar entre varias personas, creo que también es común, al menos en Japón, utilizar sufijos como _latest, _latest_20230103, _latest_5 para gestionar las versiones.

Me gustaría conocer las mejores prácticas para manejar archivos de Excel, pero no tengo una buena idea en este momento, así que decidí utilizar un programa para hacer que las diferencias sean visibles en un repositorio Git y gestionarlas.

Sin embargo, si colocas el archivo de Excel directamente en Git, las líneas de diferencia no se mostrarán claramente. TortoiseGit y otras herramientas también te mostrarán la diferencia, pero ¿puedes hacer pull requests y comentarios allí? Normalmente ves la diferencia en la página web del repositorio de todos modos. Y CSV también es un poco insatisfactorio. Hay herramientas que pueden editar CSV en formato de tabla como hoja de cálculo, pero la visualización de diferencias en el repositorio debería ser un texto delimitado por caracteres simple, que no es fácil de leer.

Entonces, pensé en gestionar casos de prueba en Markdown. Si puedes gestionarlo en texto, también puedes usar comandos *nix. Puedes escribir casos de prueba incluso si no tienes Excel, y si puedes convertirlo a Excel, nadie tendrá problemas. (La herramienta que utilicé también puede convertir a CSV, TSV.)

Resumen hasta ahora

  • Si lo gestionas con Git, no tendrás que preguntarte cuál es la última versión.
  • Si lo gestionas con Markdown, puedes ver la diferencia en la pull request. También puedes comentar allí.
    • CSV también puede romper la visualización
  • Si lo gestionas con Markdown, puedes usar comandos *nix.
  • Si lo gestionas con Markdown, puedes crear y editarlo incluso si no tienes Microsoft Excel.
  • Si puedes convertir de Markdown a Excel, no tendrás problemas cuando quieras usar el formato de tabla.

Entorno probado

  • macOS Monterey Versión 12.6
  • Python 3.10
  • meal 0.0.3.32

Cómo convertir Markdown a Excel

Preparación

Instala una herramienta de Python llamada mael.

Crea un directorio para almacenar las especificaciones de prueba.

Inicializa la carpeta. Se te preguntará qué plantilla deseas utilizar. Para pruebas, 1: Caso de prueba es útil.

Luego, se generan los siguientes archivos.

Hay varios archivos de configuración en config, pero puedes cambiarlos más tarde, así que continuemos con la creación principal de casos de prueba.

Descripción del caso de prueba

Scenario 1.md, Scenario 2.md tienen casos de prueba de muestra escritos en ellos. Actualicémoslos.

Edita con vim test/Scenario\ 1.md o algo así.

Generar archivo Excel

Ejecuta el siguiente comando.

Se genera test/output/test.xlsx.

El markdown se convierte en un archivo Excel.

La configuración en el directorio config agrega las columnas Result, Timestamp, Comment. Puedes usarlas como campos para ingresar la hora de ejecución y comentarios al realizar la prueba.

Para ajustar el ancho de columna de «Item», «Description» y «Expected Value», cambia columns.yml.

(Ya hay configuraciones de columna para Categorías, Descripción, Esperado en column_conditions, pero puedes eliminarlas si no las utilizas.)

Y ejecuta el comando nuevamente. Luego, el ancho de columna cambia y se muestra como sigue.

Los anchos de columna son adecuados.

Último paso

Guardemos los archivos Markdown en Git. Como aún no lo hemos inicializado, comenzaremos con git init.

Ahora, puedes gestionar casos de prueba en archivos Markdown.

mael puede generar tablas de Excel si coincides con el formato Markdown, así que es útil para gestionar varios datos en Markdown, no solo especificaciones de prueba.

Consejos

Usar variables

Creemos variables que se pueden usar repetidamente, como nombres de usuario y URL que aparecen muchas veces. Si fuera Excel, usaría referencias de celdas o definiría nombres.

Con mael, puedes definir variables en config/variables.ini. Bueno, son constantes.

Para usar las variables definidas, encierra el nombre de la variable con {{ }}.

Las variables están incrustadas en Excel por Mael.

Cambiar el valor de la variable para cada entorno

A veces quieres cambiar el valor de la variable para cada entorno, como cuando la URL del sitio web o el nombre de usuario a utilizar es diferente entre el entorno de producción y el entorno de desarrollo. En ese caso, creas una definición de variable en la forma de variables.{nombre del entorno}.ini.

Por ejemplo, crea variables.dev.ini de la siguiente manera.

Y utiliza el parámetro de opción -e para ejecutar el comando.

Esto creará test/output/test_dev.xlsx. variables.ini se utiliza, pero si hay la misma definición de variable en variables.dev.ini, la definición en variables.dev.ini tiene prioridad.

Reducir el número de líneas en Markdown

Dado que todos los elementos en la tabla están dispuestos verticalmente, el número de líneas en el archivo Markdown será largo. Hay dos formas de reducir el número de líneas en Markdown.

No uses ---

Anteriormente, expliqué que se usa --- para pasar a la siguiente línea. Esto es para la presentación visual en Markdown y no es necesariamente necesario. Si el mismo valor de columna continúa, el segundo se trata como un nuevo valor de línea.

Column
A
B

También es posible configurarlo para sobrescribir la línea existente en lugar de agregar una nueva línea.

Copiar cuando esté en blanco

En las tablas de Excel, incluidas las especificaciones de prueba, hay casos en los que las primera y segunda filas son iguales para una columna específica. En la siguiente tabla, las categorías grande y mediana se repiten.

Large category Medium category Small category Remarks
Tokyo Chuo-ku Ginza TEXT1
Tokyo Chuo-ku Tsukiji
Osaka Kita-ku Umeda TEXT2

En este caso, puedes escribir la parte repetida una vez configurando config/columns.yml. En el siguiente ejemplo, solo escribí la categoría grande «Tokyo» y la categoría mediana «Chuo-ku» una vez.

Hay varias formas de configurar config/columns.yml.

Un método para configurar todo para copiar la línea anterior cuando está en blanco y no copiar las observaciones,

Un método para configurar solo las categorías grande y mediana para copiar la línea anterior cuando está en blanco,

La última configuración es configurar solo todo y escribir solo el título de «Observaciones» para «Tokyo», «Chuo-ku» y «Tsukiji». La última configuración requiere un pequeño cambio en el archivo Markdown.

Salida en CSV/TSV

Es posible que termines pensando en CSV de todos modos, pero CSV es un formato difícil de descartar para verificar en la CLI. Puedes generar la salida en CSV/TSV usando la opción -f al ejecutar mael build. El valor predeterminado es -f excel.

Convertir procedimiento existente de Excel a Markdown

Para usar mael, necesitas tener las especificaciones en Markdown. Sin embargo, es bastante difícil escribir las especificaciones existentes en Markdown a mano. Entonces, uso pandas para convertirlo a Markdown.

Puedes leer Excel con read_excel y generarlo como Markdown.

Código de muestra

Usé jupyter notebook y pandas para procesarlo.

Primero, lee los datos.

Genera la salida de datos a la salida estándar y compruébalo.

Finalmente, genera la salida a un archivo.

Quiero poner un archivo README.md que no se puede poner en Excel.

Crea config/ignore.txt y escribe README.md en él.

Se leen todos los archivos Markdown como escenarios de prueba, así que si tienes algo que quieres mantener separado, ponlo en ignore.txt.

Resumen: Cómo crear especificaciones de prueba en Excel con Markdown

  1. Inicializa con mael init test_dir.
  2. Edita el archivo Markdown y crea casos de prueba
    • Escribe un Resumen y una Lista.
    • Las líneas son fáciles de leer como Markdown cuando están separadas por ---. Si deseas reducir el número de líneas, puedes omitirlas.
    • Si usas variables, utiliza test_dir/config/variables.ini y test_dir/config/variables.{nombre del entorno}.ini.
    • Si deseas ajustar el ancho de la columna, utiliza config/columns.yml.
  3. Crea Excel con mael build test_dir y mael build test_dir -e {nombre del entorno}.
    • También puedes convertir a CSV/TSV con -f csv y -f tsv.

Posdata

Pensé que Gauge podría ser bueno, pero me preguntaba si sería difícil de entender para los no ingenieros. También pensé que Pandoc podría ser una opción, pero no estoy seguro de si Pandoc es adecuado para especificaciones de prueba. mael no tiene la función de insertar figuras, así que creo que Pandoc también es bueno, pero creo que no es un problema porque de todos modos deberías escribirlo con palabras. Creo que mael es mejor porque Pandoc no tiene la función de copiar el valor de la línea anterior a la parte en blanco.

Now you can see all the content in English page.