Pruebas unitarias de funciones con Bats-core

Bats-core (Bash Automated Testing System) es el framework de facto para realizar pruebas unitarias en Bash. Permite escribir pruebas estructuradas y repetibles para sus funciones y scripts de shell, del mismo modo que usaría JUnit para Java o pytest para Python.

• Cada prueba es un bloque @test con una descripción comprensible.
• Las pruebas tienen éxito cuando cada comando que contienen devuelve el código de salida 0.
• Las pruebas fallan ante el primer código de salida distinto de cero o cuando falla una aserción.
• La salida es compatible con TAP, por lo que los sistemas de CI (GitHub Actions, Jenkins, GitLab CI) la interpretan de forma nativa.

Instálelo mediante su gestor de paquetes o clone el repositorio:

Un archivo de pruebas de Bats tiene la extensión .bats y comienza con un shebang especial. El bloque de construcción principal es la directiva @test, seguida de una cadena de descripción y un bloque de comandos.

• El shebang #!/usr/bin/env bats indica al shell cómo ejecutar el archivo.
• Cada bloque @test es un caso de prueba independiente.
• Puede ejecutar un solo archivo con bats my_tests.bats o un directorio completo con bats test/.

A continuación se muestra la estructura mínima de un archivo de pruebas de Bats:

En proyectos reales, las funciones de Bash se encuentran en archivos de biblioteca, no dentro del propio archivo de pruebas. Bats proporciona el helper load para cargar archivos externos relativos al directorio del archivo de pruebas.

• load '../lib/math.sh' carga el archivo antes de ejecutar cada prueba.
• Después de cargarlo, todas las funciones definidas en ese archivo están disponibles en sus bloques de prueba.
• Mantenga las funciones de biblioteca en un directorio lib/ y las pruebas en un directorio test/ para mantener una separación clara.

Ejemplo de estructura del proyecto y de la prueba correspondiente:

El comando run es el núcleo de las pruebas con Bats. En lugar de ejecutar un comando directamente, envolverlo con run captura su código de salida y su salida sin hacer que la prueba falle de inmediato.

• $status — contiene el código de salida del último comando run.
• $output — contiene la salida stdout combinada del último comando run.
• $lines — es un array en el que cada elemento corresponde a una línea de salida (${lines[0]}, ${lines[1]}, etc.).

Esto permite comprobar tanto los casos de éxito como los de error:

Las aserciones integradas [ ] funcionan, pero proporcionan mensajes de error poco útiles. La biblioteca auxiliar bats-assert ofrece funciones de aserción expresivas que muestran exactamente qué salió mal.

• assert_success — comprueba que $status sea 0.
• assert_failure — comprueba que $status sea distinto de cero.
• assert_output — comprueba que $output sea igual a la cadena indicada.
• assert_output --partial — comprueba que la salida contenga la subcadena.
• refute_output --partial — comprueba que la salida NO contenga la subcadena.

Instálela clonando bats-core/bats-assert en una carpeta test/helpers/ y, después, cárguela:

Bats proporciona dos funciones especiales — setup y teardown — que se ejecutan automáticamente alrededor de cada prueba. Úselas para preparar y limpiar el estado compartido, de modo que cada prueba comience en un entorno conocido.

• setup() se ejecuta antes de cada bloque @test individual.
• teardown() se ejecuta después de cada bloque @test individual, incluso si la prueba falla.
• Usos habituales: crear directorios temporales, establecer variables de entorno y eliminar archivos temporales después de la prueba.

A veces solo necesita configurar recursos costosos una vez por archivo, no antes de cada prueba. Bats proporciona setup_file y teardown_file para este propósito.

• setup_file() se ejecuta una vez antes de todas las pruebas del archivo.
• teardown_file() se ejecuta una vez después de todas las pruebas del archivo.
• Use BATS_FILE_TMPDIR (disponible automáticamente) para compartir datos entre setup_file y sus pruebas; las variables normales no persisten entre subshells.

Un caso de uso habitual es iniciar un servidor simulado o compilar un binario una sola vez y desmontarlo al final:

Un patrón muy habitual consiste en probar funciones de Bash que leen del sistema de archivos o escriben en él. La técnica clave es usar directorios temporales (mediante mktemp -d en setup) para que las pruebas nunca toquen archivos reales ni interfieran entre sí.

• Trabaje siempre dentro de $TEST_DIR (o $BATS_TEST_TMPDIR, disponible automáticamente en las versiones recientes de Bats).
• Use la biblioteca auxiliar bats-file para realizar aserciones claras sobre archivos, como assert_file_exists y assert_file_contains.
• No codifique nunca rutas como /tmp/myfile; las ejecuciones de pruebas en paralelo entrarían en conflicto.

Las funciones suelen llamar a programas externos como curl, aws o git. En las pruebas unitarias quiere probar su lógica, no el comando externo real. La técnica de simulación más sencilla en Bats consiste en definir una función de shell con el mismo nombre que el comando dentro de setup; esta tiene prioridad sobre el binario real.

• Defina una función como curl() { echo 'mocked response'; return 0; } en setup y expórtela.
• Use export -f curl para que la función esté disponible en los subshells que inicia run.
• También puede escribir el mock en un archivo temporal incluido en PATH para escenarios más complejos.

No todas las pruebas pueden ejecutarse siempre; a veces necesita una conexión de red real, una herramienta específica o un sistema operativo determinado. Bats proporciona skip para omitir condicionalmente una prueba con un mensaje informativo, en lugar de comentarla o romper la suite.

• Llame a skip "reason" en cualquier lugar dentro de un bloque @test para omitir esa prueba.
• Las pruebas omitidas aparecen en la salida como S y no cuentan como fallos.
• Bats 1.5 y versiones posteriores admiten tags: anote las pruebas con # bats test_tags=slow,network y filtre con bats --filter-tags network test/.

Un proyecto de Bats bien organizado sigue una estructura de directorios predecible, lo que facilita la incorporación de nuevos colaboradores y la integración con los pipelines de CI.

Estructura recomendada:

• lib/ — funciones de Bash de producción (un archivo por responsabilidad: math.sh, fileutils.sh).
• test/ — un archivo .bats por cada archivo de biblioteca (math.bats, fileutils.bats).
• test/helpers/ — bats-assert, bats-file y bats-support como submódulos de git.
• Makefile — un objetivo test para que los colaboradores solo tengan que ejecutar make test.

Ejecute la suite completa con un solo comando:

Compruebe su comprensión del mecanismo principal de pruebas de Bats-core.

En esta lección ha aprendido a estructurar y escribir pruebas unitarias para funciones individuales de Bash mediante Bats-core. Estas son las ideas principales:

• Estructura del archivo de pruebas — use el shebang #!/usr/bin/env bats y bloques @test con nombres descriptivos.
• load — cargue sus archivos de biblioteca para que las funciones estén disponibles en las pruebas sin copiar y pegar código.
• run + $status + $output — el trío fundamental; use siempre run para capturar los resultados sin provocar un fallo inmediato de la prueba.
• bats-assert — prefiera assert_success, assert_failure y assert_output a [ ] sin abstracciones, para obtener mensajes de error fáciles de interpretar.
• setup / teardown — se ejecutan antes y después de cada prueba; setup_file / teardown_file se ejecutan una vez por archivo.
• Simulación — sustituya los comandos externos mediante funciones de shell con el mismo nombre, exportadas con export -f.
• skip — omita condicionalmente las pruebas que dependen de recursos no disponibles.
• Estructura del proyecto — mantenga lib/, test/ y test/helpers/ separados para facilitar el mantenimiento y la integración con CI.

Estos patrones proporcionan a sus proyectos de Bash la misma disciplina de pruebas que aplicaría a cualquier proyecto de software moderno.