Configuración de JUnit 5 con GitHub Actions

Cuando escribimos nuestras pruebas, el principio básico es hacerlas lo más enfocadas posible para minimizar las fuentes de error en cada prueba. Idealmente, cuando una prueba falla, solo deberías buscar la causa en un único lugar. El entorno de prueba causa muchas fallas, por lo que se ha convertido en una práctica estándar ejecutar pruebas en un servidor CI. Esto nos permite mantener el entorno constante y evitar la temida frase: "Oye, en mi máquina funciona."

Un servidor CI con pruebas también permite que cada miembro del equipo ejecute pruebas fácilmente sin configurar todo el entorno en cada computadora. Las pruebas se convierten en una herramienta para todo el equipo, no solo para los especialistas de QA.

En esta guía, demostraremos los beneficios de ejecutar pruebas en un CI y mostraremos cómo configurar Allure Report con GitHub Actions y JUnit.

1. Preparación

Requisitos

Asegúrate de cumplir con los siguientes requisitos:

• Un repositorio de GitHub está creado y GitHub Actions está habilitado.
• Un servidor Selenoid está configurado y en funcionamiento (para ejecutar pruebas de interfaz de usuario).
• Docker está instalado (para Selenoid).

Lista de dependencias

Esta guía utiliza los siguientes paquetes:

• org.aspectj:aspectjweaver: 1.9.22
• org.junit:junit-bom: 5.11.3
• org.junit.jupiter:junit-jupiter-api
• org.junit.jupiter:junit-jupiter-engine
• com.codeborne:selenide: 7.5.1
• io.qameta.allure:allure-bom: 2.29.0
• io.qameta.allure:allure-junit5
• io.qameta.allure:allure-selenide

Ejemplo de código

El código fuente completo utilizado en esta guía está disponible en https://github.com/allure-examples/guide-junit5-github-actions.

Configuración

Necesitarás crear un repositorio Git con tu proyecto y subirlo a GitHub. Puedes descargar un proyecto predeterminado con JUnit, Gradle y Allure desde Allure Start. El repositorio de GitHub debe tener habilitadas las GitHub Actions (están habilitadas por defecto; si no es así, sigue las instrucciones de aquí).

Si deseas ejecutar pruebas de interfaz de usuario (UI), también necesitarás configurar una granja de navegadores Selenoid (o tener acceso a una). Si la configuras tú mismo, tu computadora necesitará tener Docker instalado.

2. Configuración de GitHub Actions

Para empezar, necesitarás crear un flujo de trabajo de Actions. En tu repositorio, crea una carpeta llamada .github/workflows. GitHub reconoce cualquier archivo con la extensión .yml o .yaml en esa carpeta como un flujo de trabajo. Así que, vamos a crear uno con el siguiente contenido:

name: Run tests
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK
        uses: actions/setup-java@v4
        with:
          distribution: zulu
          java-version: 17

      - name: Run tests
        run: ./gradlew clean test

Vamos a analizar qué significa esto. El name se mostrará en la pestaña de Actions cuando ejecutes esto. on: [push] es el disparador que ejecuta el flujo de trabajo; en este caso, es cuando hacemos un push al repositorio. Puedes agregar otros disparadores, por ejemplo, on: [push, workflow_dispatch]; ahora, el flujo de trabajo se ejecutará tanto en un push como cuando lo actives manualmente. El resto del archivo describe las acciones que ocurren cuando se activa el flujo de trabajo: configurar el JDK y ejecutar nuestras pruebas.

Ahora, vamos a confirmar nuestro nuevo flujo de trabajo y subirlo a GitHub. Esto creará una nueva acción y la ejecutará inmediatamente:

Dentro de la ejecución del flujo de trabajo, encontrarás un registro de las pruebas que se han ejecutado:

Sin embargo, aún no hemos terminado. Como regla general, las personas no ejecutan interfaces gráficas de navegadores (GUIs) en servidores CI/CD: consumen muchos recursos, son difíciles de escalar y generan muchos problemas con la gestión de versiones. Por eso, tu máquina virtual de GitHub no tiene un navegador, por lo que todas tus pruebas de GUI generarán errores.

Una solución es usar un navegador remoto en Selenoid, que está específicamente diseñado para ejecutar muchos navegadores de manera eficiente. La forma de conectarte a él depende de tu herramienta de control de navegadores. Estamos usando Selenide, y solo necesita la dirección de nuestro servidor Selenoid:

@BeforeAll
static void setupSelenoid() {
    Configuration.remote = "https://your.selenoid.address/wd/hub";
}

Sin embargo, se considera una mala práctica incrustar URLs como esta directamente en el código fuente. En su lugar, pasémosla a través de una variable de entorno:

@BeforeAll
static void setupSelenoid() {
    String selenideUrl = System.getenv("SELENIDE_URL");
    if (selenideUrl != null && !selenideUrl.isEmpty()) {
        Configuration.remote = selenideUrl;
    }
}

Y propagaremos una variable de GitHub a esta variable de entorno en la definición del flujo de trabajo:

name: Run tests
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK
        uses: actions/setup-java@v4
        with:
          distribution: zulu
          java-version: 17

      - name: Run tests
        run: SELENIDE_URL="${{ vars.SELENIDE_URL }}" ./gradlew clean test

Ahora, mientras tengas la variable de GitHub SELENIDE_URL definida en el repositorio, y esta apunte a un servidor Selenoid existente, tus pruebas de UI también deberían ejecutarse en GitHub Actions.

¡Excelente! Ahora todos pueden usar las pruebas: se ejecutarán cada vez que alguien haga un commit. Sin embargo, la salida no nos dice mucho sobre los resultados de las pruebas. Ya sea que desees depurar o simplemente obtener una comprensión general del estado del sistema, un informe de Allure sería mucho más fácil de leer.

3. Integración con Allure Report

Ejecutar Allure Report en un servidor CI es la mejor forma de aprovechar todas sus funciones. En particular, tendrás acceso automáticamente al historial de ejecuciones de pruebas. Con este historial, puedes identificar pruebas inestables, encontrar pruebas que cambiaron su estado desde el último informe, y visualizar cambios en las métricas.

Para que GitHub Actions funcione con Allure Report, necesitaremos realizar algunos pasos adicionales.

a. Crear una rama

Necesitaremos una nueva rama para GitHub Pages (asumiremos que se llama gh-pages). Ten en cuenta que esta no es donde deben ubicarse los archivos del flujo de trabajo. Aquí es donde se empujarán los archivos de nuestro informe. Por lo tanto, puedes crear una rama vacía que no esté relacionada con ninguna otra rama en el repositorio:

git switch --orphan gh-pages
git commit --allow-empty -m "crear una rama para GitHub Pages"
git push -u origin gh-pages
git switch a-previous-branch

b. Modificar el flujo de trabajo

A continuación, debemos actualizar el archivo del flujo de trabajo: agregar los pasos para cargar el historial del informe, construir el informe y publicarlo en GitHub Pages. El archivo debería verse así:

name: Run tests and publish the report
on: [push]

permissions: write-all

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK
        uses: actions/setup-java@v4
        with:
          distribution: zulu
          java-version: 17

      - name: Run tests
        run: SELENIDE_URL="${{ vars.SELENIDE_URL }}" ./gradlew clean test

      - name: Load test report history
        uses: actions/checkout@v4
        if: always()
        continue-on-error: true
        with:
          ref: gh-pages
          path: gh-pages

      - name: Build test report
        uses: simple-elf/[email protected]
        if: always()
        with:
          gh_pages: gh-pages
          allure_history: allure-history
          allure_results: build/allure-results

      - name: Publish test report
        uses: peaceiris/actions-gh-pages@v4
        if: always()
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: gh-pages
          publish_dir: allure-history

Un par de cosas a tener en cuenta aquí:

• permissions: write-all: esta línea permite que el flujo de trabajo haga commits en la rama de GitHub Pages.
• if: always(): estas líneas aseguran que el informe se construya y publique incluso si hay pruebas fallidas.

c. Habilitar el despliegue

Si has ejecutado el flujo de trabajo anterior, el informe se ha empujado a la rama gh-pages, pero aún no se ha publicado. Esto será gestionado por un segundo flujo de trabajo que GitHub debe generar automáticamente. Para ello:

• Ve a Settings > Pages.
• En Build and deployment, establece la opción Source en Deploy from a branch.
• La opción Branch debe configurarse como gh-pages (o cualquier rama que estés utilizando para Pages).
• Haz clic en Save.
• Asegúrate de que el nuevo flujo de trabajo (pages-build-deployment) se haya creado en Actions:

Con esto, tus informes deberían aparecer en el dominio que GitHub Pages ha creado para ti (puedes encontrar el enlace en Settings > Pages):

Los informes generados por este flujo de trabajo tendrán el historial habilitado. En la página principal del informe, el gráfico de Tendencia es interactivo, y al hacer clic en él te llevará a ejecuciones de pruebas anteriores:

Y con eso, estás listo para realizar pruebas en un entorno estandarizado y estable.

4. Conclusión

Al trabajar en equipo, la mejor manera de ejecutar pruebas es en un servidor CI; esto permite que todos tengan acceso rápido a las pruebas y asegura que los resultados de las pruebas sean reproducibles. GitHub Actions te permite ejecutar pruebas en un entorno centralizado, y Allure Report hace que los resultados de las pruebas sean rápidamente accesibles para todo el equipo.