Integración con Jenkins

Con el plugin Allure Report para Jenkins, puedes añadir un paso de "Allure Report" a tu configuración de construcción, de modo que Jenkins generará automáticamente un reporte de prueba para cada compilación.

El plugin es compatible con Allure 2 (basado en Java, instalado como herramienta global de Jenkins) y Allure 3 (basado en Node.js, resuelto desde el PATH en el agente). Puedes elegir qué versión usar por trabajo.

Instalación y configuración

Para habilitar el soporte de Allure en tu instalación de Jenkins, haz lo siguiente bajo la cuenta de administrador:

1. instalar el plugin,
2. configurar la herramienta de generación de reportes.

1. Instalar el plugin

El método recomendado para instalar el plugin Allure Report es a través de la interfaz web de Jenkins. Sin embargo, si tu configuración de Jenkins no tiene acceso a internet, puedes instalar el plugin subiendo un archivo HPI manualmente a Jenkins. El método de instalación seleccionado no afecta la funcionalidad del plugin.

Para instalar el plugin directamente desde internet:

1. En la interfaz web de Jenkins, ve a Manage Jenkins → Plugins → Available plugins.

2. Usando el cuadro de búsqueda, busca el plugin "Allure". Marca la casilla junto al plugin.

3. Haz clic en Install without restart.

   En la página de Download progress, espera hasta que el estado de cada uno sea "Success".

Para instalar el plugin a través de un archivo:

1. En la página de lanzamientos del plugin Allure Report, encuentra la versión que deseas elegir (se recomienda la última versión) y haz clic en direct link. Guarda el archivo HPI en un directorio local de tu dispositivo.

2. En la interfaz web de Jenkins, ve a Manage Jenkins → Plugins → Advanced settings.

3. En la sección Deploy Plugin, haz clic en Browse y selecciona el archivo HPI desde tu dispositivo.

4. Haz clic en el botón Deploy para confirmar la instalación.

   En la página de Download progress, espera hasta que el estado de cada uno sea "Success".

Después de la instalación, el plugin aparecerá en la sección Manage Jenkins → Plugins → Installed plugins.

2. Configurar la herramienta de generación de reportes

La configuración depende de qué versión de Allure planeas usar.

Allure 3 (basado en Node.js)

Allure 3 espera que el comando allure esté disponible en el PATH de cada agente de Jenkins donde se generarán los reportes.

Para configurar Allure 3 en los agentes de Jenkins:

1. En cada agente que generará reportes de Allure 3, instala la CLI de Allure mediante npm:

   npm install -g allure

2. Verifica la instalación:

   allure --version

INFO

Una sección de instalaciones de Allure 3 (desde PATH) está disponible en Manage Jenkins → Tools. Esta sección es un artefacto del sistema de gestión de herramientas de Jenkins, no requiere configuración y no tiene ningún efecto — el plugin siempre resuelve el comando allure desde el PATH del sistema automáticamente. Puedes ignorar esta sección de forma segura.

Allure 2 (basado en Java)

Allure 2 se instala como herramienta global de Jenkins. Una vez agregada, Jenkins se encarga de descargarla en cada agente que necesite generar un reporte.

Configuración rápida (recomendada para instancias con acceso a internet):

La forma más sencilla de configurar Allure 2 es usar el botón de Configuración rápida, que aparece automáticamente en la configuración del trabajo cuando no se ha configurado ninguna instalación de Allure 2.

1. Abre la página Configure de cualquier trabajo y agrega una acción posterior a la construcción Allure Report (ver Usar Allure en un proyecto freestyle).

2. En la sección Allure Report, si no hay ninguna instalación de Allure 2 configurada, aparecerá un banner de advertencia. Haz clic en Quick Setup (Install Latest Stable Allure 2).

   INFO

   El botón de Configuración rápida solo es visible para los administradores de Jenkins.

   Jenkins descargará la última versión estable de Allure 2 desde Maven Central y la registrará como herramienta global. La herramienta se descargará en cada agente en el primer uso.

Para instalar la herramienta manualmente (con conexión a internet):

1. En la interfaz web de Jenkins, ve a Manage Jenkins → Tools.

2. En la sección Allure Commandline installations, haz clic en Add Allure Commandline.

   Asegúrate de que la casilla Install automatically esté marcada.

3. En el desplegable del instalador, selecciona From Maven Central (legacy).

4. Rellena los campos:

   • Name — un nombre para ayudarte a reconocer esta versión de la herramienta, por ejemplo, "2.39.0".
   • Version — la versión de Allure Report a instalar. Se recomienda la última versión.

5. Haz clic en Save.

Para instalar la herramienta desde una URL personalizada (entornos sin acceso a internet):

1. En el directorio allure-commandline en Maven Central, encuentra el archivo ZIP o TAR.GZ más reciente. Cópialo a un servidor web disponible para el servidor Jenkins.

2. En la interfaz web de Jenkins, ve a Manage Jenkins → Tools.

3. En la sección Allure Commandline, haz clic en Add Allure Commandline.

   Asegúrate de que la casilla Install automatically esté marcada.

4. Haz clic en X para eliminar el bloque del instalador existente.

5. Haz clic en Add installer → Extract *.zip/*.tar.gz.

6. Rellena los campos:

   • Name — un nombre para ayudarte a reconocer esta versión de la herramienta, por ejemplo, "2.39.0".
   • Download URL for binary archive — la URL desde la cual se descargará la utilidad.
   • Subdirectory of extracted archive — deja en blanco.

7. Haz clic en Save.

Actualizar la integración con Allure

TIP

Actualizar Allure en Jenkins requiere actualizar no solo el plugin de Allure en sí, que solo gestiona la integración con Jenkins, sino también la herramienta de generación de reportes, que es el software real de Allure Report.

Además, recomendamos actualizar la herramienta de vez en cuando incluso si no hay actualizaciones pendientes del plugin, ya que la herramienta suele recibir actualizaciones más frecuentes que el plugin.

1. Actualizar el plugin

Para actualizar a través de la interfaz de Jenkins:

1. En la interfaz web de Jenkins, ve a Manage Jenkins → Plugins.
2. Haz clic en la pestaña Updates.
3. Si el plugin Allure aparece en la lista, marca la casilla junto a "Allure".
4. Haz clic en Update.
5. En la siguiente página, marca Restart Jenkins when installation is complete and no jobs are running.
6. Espera a que Jenkins se reinicie automáticamente.

Para actualizar manualmente a través de un archivo HPI:

1. Visita la página de lanzamientos del plugin Allure Report.
2. Descarga el archivo .hpi más reciente.
3. En Jenkins, ve a Manage Jenkins → Plugins → Advanced settings.
4. En "Deploy Plugin", haz clic en Browse y selecciona el archivo HPI descargado.
5. Haz clic en Deploy.
6. Reinicia Jenkins cuando se te solicite.

2. Actualizar la herramienta de generación de reportes

Allure 3

Para actualizar Allure 3, ejecuta el siguiente comando en cada agente donde esté instalado:

npm update -g allure

Allure 2

Si la herramienta fue instalada directamente desde internet:

1. Ve a Manage Jenkins → Tools.
2. Encuentra tu configuración existente de Allure Commandline en la sección Allure Commandline.
3. Haz clic en el nombre de la herramienta para expandir su configuración.
4. Actualiza el campo Version a la última versión de Allure (por ejemplo, cambiar de "2.34.0" a "2.39.0").
5. Opcionalmente, actualiza el campo Name para reflejar la nueva versión.
6. Haz clic en Save.

Si la herramienta fue instalada desde una URL personalizada:

1. Ve a Manage Jenkins → Tools.
2. Encuentra tu configuración existente de Allure Commandline.
3. Actualiza el campo Download URL for binary archive para que apunte a la versión más nueva en tu espejo o en Maven Central.
4. Opcionalmente, actualiza el campo Name para reflejar la nueva versión.
5. Haz clic en Save.

Usar Allure en un proyecto freestyle

En Jenkins, un "proyecto freestyle" es una configuración de construcción en la que agregas y editas pasos a través de la interfaz web. Con el plugin Allure Report, la interfaz web ofrece una opción para agregar una acción posterior a la construcción para generar reportes de prueba.

1. En la interfaz web de Jenkins, selecciona un trabajo para el cual deseas habilitar Allure Report.

2. En el menú de la izquierda, haz clic en Configure.

   INFO

   Antes de continuar, asegúrate de que la configuración de la construcción:

   • contenga un paso que ejecute las pruebas del proyecto,
   • tenga habilitado el adaptador Allure para su framework de pruebas.

3. En la sección Post-build Actions, haz clic en Add post-build action → Allure Report.

4. En el desplegable Allure Version, selecciona la versión de Allure a usar:

   • Allure 2 (Java-based, auto-installed) — usa una herramienta global de Jenkins; requiere una instalación de Allure Commandline configurada (ver Configurar la herramienta de generación de reportes).
   • Allure 3 (Node.js-based, requires 'allure' in PATH) — usa el comando allure desde el PATH del agente; requiere que Allure 3 esté instalado en el agente mediante npm.

5. En el campo Results → Path, especifica la ruta al directorio de resultados de las pruebas (ver How it works).

   TIP

   Si tienes varios pasos de construcción generando resultados de prueba en varios directorios, usa el botón Add para especificar más rutas.

6. Si tienes más de una instalación de Allure 2 configurada y estás usando Allure 2, usa el desplegable Allure CLI Installation para seleccionar cuál usar. Si solo hay una instalación configurada, se selecciona automáticamente.

7. Haz clic en Advanced si necesitas configurar alguno de los siguientes:

   • JDK — el JDK a usar para la generación del reporte. Solo aplica a Allure 2.
   • Allure Configuration — ruta a un archivo de configuración para la generación del reporte. Solo aplica a Allure 3.

8. Haz clic en Save.

Después de la configuración, puedes hacer clic en Build Now para ejecutar la configuración de la construcción.

Usar Allure en un script de Jenkins Pipeline

Si almacenas el trabajo en un script de Jenkins Pipeline, puedes usar el comando allure para definir un paso para generar reportes de prueba. Se recomienda usar la interfaz web de Jenkins para generar el comando con los parámetros apropiados.

1. En Jenkins, selecciona un trabajo para el cual deseas habilitar la carga.

2. En el menú de la izquierda, haz clic en Pipeline Syntax.

   Se abrirá una interfaz para generar fragmentos de código para Jenkins Pipeline.

3. En la lista desplegable Sample Step, selecciona "allure: Allure Report".

4. En el desplegable Allure Version, selecciona Allure 2 o Allure 3 según sea necesario.

5. En el campo Results → Path, especifica la ruta al directorio de resultados de las pruebas (ver How it works).

   TIP

   Si tienes múltiples pasos de construcción generando resultados de prueba en varios directorios, usa el botón Add para especificar más rutas.

6. Si estás usando Allure 2 y tienes más de una instalación de Allure 2 configurada, usa el desplegable Allure CLI Installation para seleccionar cuál usar.

7. Haz clic en Generate Pipeline Script.

   En el área debajo del botón, aparecerá el comando generado. Para Allure 2, por ejemplo:

   allure includeProperties: false,
          jdk: '',
          results: [[path: 'build/allure-results']]

   Para Allure 3:

   allure allureVersion: '3',
          includeProperties: false,
          results: [[path: 'build/allure-results']]

   Copia el comando generado al portapapeles.

8. Abre el script de Groovy que usas para el proyecto. Puede ser:

   • el script en el cuadro de texto en (job) → Configure → Pipeline,
   • el Jenkinsfile bajo el sistema de control de versiones del proyecto (ver la documentación oficial).

   INFO

   Antes de continuar, asegúrate de que la configuración de la construcción:

   • contenga un paso que ejecute las pruebas del proyecto,
   • tenga habilitado el adaptador Allure para su framework de pruebas.

9. Pega el comando generado en el lugar apropiado del script.

   Para pipelines declarativas

   // Si usas la [sintaxis Declarative Pipeline](https://www.jenkins.io/doc/book/pipeline/syntax/#declarative-pipeline), encuentra el stage que ejecuta las pruebas e inserta un nuevo bloque `always` en el bloque `post` de ese stage. Esto hará que Allure Report se ejecute después del lanzamiento de las pruebas, independientemente de cuántas pruebas hayan tenido éxito.
   pipeline {
       agent any
   
       stages {
           stage('Build') {
               steps {
                   git 'https://github.com/eroshenkoam/allure-example.git'
                   sh './gradlew clean test'
               }
               post {
                   always {
                       allure includeProperties: false,
                              jdk: '',
                              results: [[path: 'build/allure-results']]
                   }
               }
           }
       }
   }

   Para pipelines con script

   // Si usas la [sintaxis Scripted Pipeline](https://www.jenkins.io/doc/book/pipeline/syntax/#scripted-pipeline), hay muchas formas de organizar el código del pipeline de manera que Allure Report se ejecute después de las pruebas, independientemente de sus resultados. Una forma de hacerlo es envolver todos los pasos existentes en una declaración `try`, colocando el comando `allure` generado en el bloque `finally`.
   node {
       stage('Build') {
           try {
               git 'https://github.com/eroshenkoam/allure-example.git'
               sh './gradlew clean test'
           }
           finally {
               allure includeProperties: false,
                      jdk: '',
                      results: [[path: 'build/allure-results']]
           }
       }
   }

10. Guarda el script. En el caso de un Jenkinsfile, asegúrate de hacer commit de los cambios en el repositorio.