Integración con GitHub Pages

Con Allure Report y GitHub Actions, puedes generar automáticamente reportes de prueba y publicarlos en GitHub Pages.

Para configurarlo, realiza lo siguiente:

1. agregar acciones para generar y publicar reportes.
2. habilitar acceso de escritura para las ejecuciones del flujo de trabajo,
3. configurar la publicación en GitHub Pages.

1. Agregar acciones para generar y publicar reportes

Al final del flujo de trabajo de pruebas de tu repositorio, agrega los pasos que cargarán el historial de reportes de prueba, generarán el reporte de prueba y publicarán el reporte de prueba.

Los dos motores de Allure Report necesitan pasos diferentes para generar el reporte. simple-elf/allure-report-action, la acción comunitaria usada para Allure 2 a continuación, siempre genera un reporte de Allure 2 internamente (incluye su propia copia de la herramienta de línea de comandos de Allure 2), por lo que no se puede reutilizar para Allure 3. Para Allure 3, instala la CLI de allure directamente en el flujo de trabajo.

Aquí tienes un ejemplo completo de un archivo de flujo de trabajo para un proyecto en Java. El ejemplo asume que la rama utilizada para GitHub Pages se llama gh-pages.

Allure 2

name: Ejecutar pruebas y publicar reporte
on: [push]

permissions:
  contents: write

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

      - name: Configurar JDK
        uses: actions/setup-java@v6
        with:
          distribution: zulu
          java-version: 17

      - name: Ejecutar pruebas
        run: ./gradlew clean test

      - name: Cargar historial de reportes de prueba
        uses: actions/checkout@v7
        if: always()
        continue-on-error: true
        with:
          ref: gh-pages
          path: gh-pages

      - name: Generar reporte de prueba
        uses: simple-elf/[email protected]
        if: always()
        with:
          gh_pages: gh-pages
          allure_history: allure-history
          allure_results: build/allure-results

      - name: Publicar reporte de prueba
        uses: peaceiris/actions-gh-pages@v4
        if: always()
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: gh-pages
          publish_dir: allure-history

Allure 3

name: Ejecutar pruebas y publicar reporte
on: [push]

permissions:
  contents: write

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

      - name: Configurar JDK
        uses: actions/setup-java@v6
        with:
          distribution: zulu
          java-version: 17

      - name: Ejecutar pruebas
        run: ./gradlew clean test

      - name: Generar reporte de prueba
        if: always()
        run: |
          npm install -g allure
          allure generate build/allure-results -o allure-report

      - name: Publicar reporte de prueba
        uses: peaceiris/actions-gh-pages@v4
        if: always()
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: gh-pages
          publish_dir: allure-report

WARNING

Este ejemplo de Allure 3 no mantiene el historial de pruebas entre ejecuciones - cada reporte se genera desde cero, sin nada con qué compararlo. Para un historial de pruebas que funcione correctamente con Allure 3, usa el servicio de almacenamiento autoalojado - consulta las guías de Docker o Cloudflare Workers para configurarlo.

Cargar historial de reportes de prueba

Como se discute en Historial de pruebas, Allure Report puede incluir algunos datos de reportes anteriores en cada nuevo reporte. Este paso aplica solo a Allure 2 - el ejemplo de Allure 3 de arriba no mantiene el historial entre ejecuciones; consulta la advertencia anterior. Para cargar el historial en Allure 2, debes proporcionarle los archivos publicados en GitHub Pages por ejecuciones anteriores. Este paso lo realiza mediante un git checkout desde la rama utilizada para el contenido de GitHub Pages.

En el archivo del flujo de trabajo, establece los siguientes valores para este paso:

• name: cualquier nombre legible para los humanos, por ejemplo, "Cargar historial de reportes de prueba".
• uses: actions/checkout.
• if: always().
• continue-on-error: true.
• with:
  • ref: la rama utilizada para el contenido de GitHub Pages.
  • path: un nombre arbitrario para un directorio al que se guardarán los datos anteriores.

Generar reporte de prueba

Este paso genera el reporte HTML. Para Allure 2, se basa en los datos de las ejecuciones actuales y anteriores de las pruebas; para Allure 3, consulta la advertencia anterior sobre el historial. Cómo funciona depende del motor:

Allure 2 ejecuta la utilidad Allure Report mediante simple-elf/[email protected]. El nuevo reporte, junto con las copias de los reportes anteriores, se guardará en el directorio especificado en allure_history, listo para ser publicado en GitHub Pages. Establece los siguientes valores para este paso:

• name: cualquier nombre legible para los humanos, por ejemplo, "Generar reporte de prueba".
• uses: simple-elf/[email protected].
• if: always().
• with:
  • gh_pages: el nombre del directorio en el que se descargaron los datos anteriores. Debe ser el mismo que el valor de path del paso Cargar historial de reportes de prueba.
  • allure_results: ruta al directorio actual de resultados de prueba. Dependiendo del marco que uses y la configuración de la integración de Allure, una ruta apropiada puede ser allure-results, build/allure-results, o alguna ruta personalizada.
  • allure_history: un nombre arbitrario para un directorio al que se guardará el resultado.

Allure 3 no tiene una acción equivalente, así que el flujo de trabajo instala y ejecuta la CLI de allure directamente:

• npm install -g allure instala la CLI.
• allure generate build/allure-results -o allure-report genera el reporte en el directorio allure-report.

Como se señaló arriba, esto no te da historial de pruebas - para eso, configura el servicio de almacenamiento autoalojado.

Publicar reporte de prueba

El último paso del flujo de trabajo enviará el directorio generado a la rama utilizada para GitHub Pages. Se supone que esto activará una segunda ejecución del flujo de trabajo, llamada "páginas de construcción y despliegue", que, a su vez, actualizará el contenido real en el dominio de GitHub Pages. (Consulta Configurar publicación en GitHub Pages más abajo). Este paso es el mismo para ambos motores, salvo el directorio que se publica.

En el archivo del flujo de trabajo, establece los siguientes valores para este paso:

• name: cualquier nombre legible para los humanos, por ejemplo, "Publicar reporte de prueba".
• uses: peaceiris/actions-gh-pages@v4.
• if: always().
• with:
  • github_token: ${{ secrets.GITHUB_TOKEN }}. Consulta Habilitar acceso de escritura para GitHub Actions para más detalles.
  • publish_branch: la rama utilizada para el contenido de GitHub Pages.
  • publish_dir: el directorio que se publicará - el valor de allure_history del paso Generar reporte de prueba para Allure 2, o el directorio de salida de allure generate (allure-report arriba) para Allure 3.

2. Habilitar acceso de escritura para las ejecuciones del flujo de trabajo

Al enviar archivos a la rama de GitHub Pages, el flujo de trabajo utiliza un token de autenticación generado por GitHub. Sin embargo, la configuración predeterminada no permite que GitHub Actions envíe archivos al repositorio.

El bloque permissions: contents: write ya incluido en el ejemplo de flujo de trabajo anterior otorga esto solo para ese flujo de trabajo, lo cual es el enfoque preferido y de alcance mínimo - prefiérelo sobre la configuración a nivel de repositorio de abajo cuando puedas. (Es posible que veas ejemplos más antiguos usando el más amplio permissions: write-all en su lugar - eso otorga acceso de escritura a mucho más de lo que este flujo de trabajo necesita, como issues y paquetes.)

Si prefieres otorgarlo a nivel de repositorio en su lugar - o si sigues viendo errores como este en los registros de la ejecución del flujo de trabajo incluso con el bloque permissions en su lugar:

remote: Permission to ⟨USER⟩/⟨REPOSITORY⟩.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/⟨USER⟩/⟨REPOSITORY⟩.git/':
The requested URL returned error: 403

Para solucionar esto, debes otorgar permisos de escritura al token.

1. En la página del proyecto en GitHub, ve a Settings → Actions → General.

2. En la sección Workflow permissions, selecciona la opción Read and write permissions.

3. Haz clic en Save.

3. Configurar publicación en GitHub Pages

Después de ejecutar el flujo de trabajo por primera vez, enviará el reporte de prueba a la rama gh-pages. En un repositorio público, GitHub a menudo detecta esto y lo publica automáticamente, sin necesidad de ninguna acción adicional. Si eso no sucede - o prefieres configurarlo explícitamente - así es como se hace:

1. Asegúrate de que la rama con el contenido exista (gh-pages en el ejemplo anterior).

2. En la página del proyecto en GitHub, ve a Settings → Pages.

3. En la sección Build and deployment, especifica las opciones:

   • Source: "Deploy from a branch".
   • Branch: la rama utilizada para el contenido de GitHub Pages. En la siguiente lista desplegable, selecciona "/ (root)".

4. Haz clic en Save.

5. Ve a la pestaña Actions.

6. Asegúrate de que se haya creado automáticamente la ejecución del flujo de trabajo llamada "pages build and deployment".

   Una vez que la ejecución se haya completado, el reporte de prueba debería aparecer en el dominio de GitHub Pages.

Una vez que tu CI genere y publique reportes en cada ejecución, es posible que también quieras resúmenes automáticos en las pull requests - una tabla de resultados, desgloses opcionales por prueba y una verificación de Quality Gate, todo publicado como comentarios en la PR. Echa un vistazo a la Allure GitHub Action para eso; es una acción separada y complementaria que puedes agregar junto al flujo de trabajo anterior.