Migración a Allure Java 3

Allure Java 3.0 es una versión principal de las integraciones de Allure para frameworks de pruebas de JVM (JUnit, TestNG, Cucumber-JVM, Spock, ScalaTest, Karate y otros). Aumenta la versión mínima de Java, elimina varios módulos heredados y métodos de la API de Runtime, y cambia la forma de registrar las solicitudes HTTP y de identificar las pruebas en el historial del reporte.

Esta guía enumera todo lo que puedes necesitar cambiar al actualizar desde Allure Java 2.x.

TIP

No necesitas cambiar tu versión de Allure Report. Los resultados producidos por Allure Java 3 pueden verse tanto en Allure Report 3 como en Allure Report 2.

1. Comprueba los requisitos

Allure Java 3 requiere Java 17 o una versión posterior. Los módulos allure-karate y allure-jooq requieren Java 21 o una versión posterior.

Algunas integraciones con frameworks también requieren versiones más recientes de estos:

• TestNG: 7.10 o una versión posterior.
• Karate: Karate 2 (io.karatelabs:karate-core). Allure Java 3 ya no es compatible con Karate 1.

Si tus pruebas se ejecutan en una versión anterior de Java o del framework, sigue usando Allure Java 2.x hasta que puedas actualizar.

2. Actualiza la versión de la dependencia

Si usas allure-bom, actualiza su versión. Todos los módulos de Allure se actualizarán juntos.

Maven

<properties>
    <allure.version>3.0.0</allure.version>
</properties>

Gradle (Kotlin)

val allureVersion = "3.0.0"
// ...
dependencies {
    testImplementation(platform("io.qameta.allure:allure-bom:$allureVersion"))
}

Gradle (Groovy)

def allureVersion = "3.0.0"
// ...
dependencies {
    testImplementation platform("io.qameta.allure:allure-bom:$allureVersion")
}

Si usas el plugin de Allure para Gradle para agregar los adaptadores, este sigue usando Allure Java 2.x de forma predeterminada. Usa la versión 4.3.0 o una versión posterior del plugin y habilita Allure Java 3 explícitamente; consulta Uso de Allure Java 3:

allure {
    adapter {
        allureJavaVersion.set("3.0.0")
    }
}

3. Reemplaza los módulos eliminados

Los siguientes módulos ya no se publican en Allure Java 3. Si tu proyecto depende de alguno de ellos, reemplázalo como se muestra a continuación.

Módulo eliminado	Reemplazo
allure-junit5	allure-jupiter; consulta JUnit Jupiter
allure-junit5-assert	allure-jupiter-assert
allure-cucumber4-jvm allure-cucumber5-jvm allure-cucumber6-jvm	Actualiza a Cucumber-JVM 7 y usa allure-cucumber7-jvm; consulta Cucumber-JVM
allure-jbehave (JBehave 4)	Actualiza a JBehave 5 y usa allure-jbehave5; consulta JBehave
allure-spock (Spock 1)	Actualiza a Spock 2 y usa allure-spock2; consulta Spock
allure-okhttp (OkHttp 2)	Actualiza a OkHttp 3 o una versión posterior y usa allure-okhttp3
allure-attachments	No se necesita reemplazo. Las integraciones HTTP ahora generan adjuntos de intercambio HTTP sin este módulo
allure-test-filter	No se necesita reemplazo. La compatibilidad con planes de pruebas ahora forma parte de allure-java-commons, del que ya depende cada adaptador. Elimina la dependencia
allure-reader	Sin reemplazo

4. Reemplaza los métodos eliminados de la API de Runtime

Se eliminaron varios métodos de la clase Allure y de su ciclo de vida. Reemplázalos como se muestra a continuación.

Método eliminado	Reemplazo
Allure.addAttachment(name, content)	Allure.attachment(name, content)
Allure.addAttachment(name, type, content)	Allure.attachment(name, type, content)
Allure.addAttachment(name, type, content, fileExtension)	Allure.attachment(name, type, content, AttachmentOptions.withFileExtension(fileExtension))
Allure.addByteAttachmentAsync() Allure.addStreamAttachmentAsync()	Allure.attachmentAsync(name, type, body), donde body es un CompletionStage de un InputStream
Allure.addDescription(description)	Allure.description(description)
Allure.addDescriptionHtml(descriptionHtml)	Allure.descriptionHtml(descriptionHtml)
Allure.addLabels(labels...)	Allure.label(name, value) para cada etiqueta
Allure.addLinks(links...)	Allure.link(name, type, url) para cada enlace
Allure.getLifecycle().updateTestCase(update)	Allure.getLifecycle().updateTest(update)

Los métodos de nivel inferior de AllureLifecycle que reciben UUID, como startStep(uuid, result), stopStep(uuid) o getCurrentTestCase(), se reemplazaron por métodos que reciben un AllureExternalKey. Se usan principalmente en integraciones personalizadas; consulta Para autores de integraciones.

5. Revisa los cambios de comportamiento

Las solicitudes HTTP se registran como intercambios HTTP

Todas las integraciones de clientes HTTP (REST Assured, OkHttp, Apache HttpClient, Spring Web, JAX-RS y otras) ahora registran cada solicitud y su respuesta como un único adjunto de intercambio HTTP. Allure Report lo muestra como un visor interactivo de solicitudes y respuestas.

En Allure Java 2.x, estas integraciones generaban dos adjuntos HTML independientes renderizados mediante plantillas de FreeMarker. Se eliminaron las plantillas y los métodos para personalizarlas, como setRequestTemplate() y setResponseTemplate() de Allure REST Assured. Para controlar los datos confidenciales y el tamaño de los cuerpos, usa configureHttpExchange().

Los adjuntos se agrupan en pasos

Los adjuntos agregados mediante la API de Runtime, como Allure.attachment(), ahora aparecen en el reporte como un paso con el nombre del adjunto, en el orden en que se crearon respecto a los demás pasos.

Historial de pruebas

Allure Java 3 calcula los identificadores de pruebas de forma diferente, lo que afecta al historial y los reintentos de dos maneras:

• El historial puede comenzar de nuevo después de la actualización. Las pruebas ejecutadas con JUnit 4, TestNG y JBehave reciben nuevos identificadores, por lo que el primer reporte generado después de la actualización las muestra como pruebas nuevas, sin su historial anterior. Las pruebas ejecutadas con JUnit Jupiter, Cucumber-JVM y Spock conservan su historial. Esto sucede tanto en Allure Report 3 como en Allure Report 2.

• Los parámetros de Runtime ahora afectan a la identidad de la prueba. Los parámetros agregados mediante Allure.parameter() ahora se tienen en cuenta junto con los parámetros proporcionados por el framework de pruebas. Si el valor de un parámetro cambia entre ejecuciones, como una marca de tiempo o un ID aleatorio, la prueba se considera una prueba nueva en cada ejecución. Marca dichos parámetros como excluidos:

  Allure.parameter("startedAt", startedAt, true);

Variable de entorno del plan de pruebas

La variable de entorno heredada AS_TESTPLAN_PATH ya no es compatible. Usa ALLURE_TESTPLAN_PATH para indicar a Allure la ubicación de un archivo de plan de pruebas.

Limpieza del directorio de resultados

Se eliminaron las propiedades de configuración allure.results.clean.before.run y allure.results.clean.only.once. Allure Java ya no elimina los archivos existentes del directorio de resultados. Usa tu herramienta de compilación para limpiarlo, por ejemplo, mvn clean o gradle clean.

APIs de Jakarta

allure-servlet-api y allure-jax-rs ahora usan las APIs jakarta.* en lugar de javax.*. Si tu proyecto todavía usa javax.servlet o javax.ws.rs, migra a Jakarta EE antes de actualizar.

Para autores de integraciones

Si desarrollas tu propia integración de Allure sobre allure-java-commons, ten en cuenta que se rediseñó la API de AllureLifecycle. Se eliminaron los métodos que identificaban pruebas, pasos, fixtures y contenedores mediante cadenas UUID. Se reemplazaron por métodos que reciben un AllureExternalKey, y los contenedores de pruebas se reemplazaron por ámbitos (registerScope(), addTestToScope() y writeScope()). El formato de los archivos de resultados escritos en el disco no cambió.

6. Explora las novedades

Allure Java 3 también incorpora nuevas funciones, entre ellas:

• Errores y adjuntos globales: los fallos en fixtures y hooks del ciclo de vida se registran para toda la ejecución de prueba en lugar de crear resultados de prueba artificiales, y puedes registrar los tuyos mediante Allure.globalError().
• Adjuntos de intercambio HTTP con ocultación de cabeceras, cookies y parámetros de consulta y formulario.
• Compatibilidad con JUnit 6.
• Las anotaciones @Flaky y @Muted ahora funcionan con JUnit 4.