Allure Report 3: XCResults Reader Allure 3
Allure Report 3 introduce soporte nativo para resultados de pruebas de Apple Xcode. Ahora puedes generar reportes Allure completamente funcionales directamente desde tus ejecuciones de XCTest y/o Swift Testing sin herramientas de conversión adicionales.
Este artículo es tanto una descripción general de las funciones como una guía básica de integración para tus proyectos Xcode.
Nota
Allure 2 requiere que uses la herramienta CLI separada xcresults para exportar los resultados de prueba de Xcode a un formato compatible. La gran mayoría de sus funciones están presentes en Allure 3, y muchas más avanzadas fueron agregadas además. Sigue leyendo para conocer los detalles.
Comenzando
Requisitos Previos
TIP
Se requiere el IDE Xcode completo para la generación adecuada de reportes. El paquete Xcode Command Line Tools no es suficiente. Además, si instalas el IDE Xcode completo encima del CLI, asegúrate de configurarlo como el entorno de desarrollo activo a través de xcode-select --switch
Proyecto de Ejemplo
Puedes explorar varios ejemplos de pruebas Xcode y ver cómo Allure muestra los resultados en sus reportes aquí:
https://github.com/allure-examples/allure3-xcresult
Generar Reporte
Allure Report puede leer los resultados de prueba de Xcode y generar reportes desde ellos - simplemente usa las funciones estándar de Swift Testing o XCTest y Allure automáticamente extraerá la estructura, resultados y metadatos de los resultados de tus pruebas.
Puedes generar un reporte Allure básico desde tu bundle .xcresult directamente, no se requieren cambios adicionales al código:
npx allure generate <ruta/al/archivo/xcresult> -o <ruta/al/directorio/del/reporte>
Y luego abrirlo como cualquier otro reporte Allure:
npx allure open <ruta/al/directorio/del/reporte>
A continuación se muestran algunos ejemplos de pruebas Xcode y cómo se mostrarán en Allure Report.
import Testing
struct MathTests {
@Test
func addition() async throws {
let result = 2 + 3
#expect(result == 5)
}
@Test
func incorrectMultiplication() async throws {
let result = 3 * 4
#expect(result == 11) // Esto fallará
}
}import XCTest
final class MathTests: XCTestCase {
func testAddition() throws {
let result = 2 + 3
XCTAssertEqual(result, 5)
}
func testIncorrectMultiplication() throws {
let result = 3 * 4
XCTAssertEqual(result, 11) // Esto fallará
}
}
Funciones Soportadas
Aunque cualquier resultado de prueba Xcode existente puede convertirse en un Allure Report, y la mayoría de metadatos se capturarán automáticamente, es posible que desees organizar y etiquetar tus pruebas de cierta manera para aprovechar al máximo Allure. Explora esta sección para aprender cómo funcionan varias funciones y cómo se reflejan en el reporte resultante.
Las insignias "Swift Testing" y "XCTest" se usarán a continuación para marcar a qué framework(s) se aplica una función particular.
1. Establecer Nombres Personalizados para Pruebas Swift Testing XCTest
A menos que se especifique lo contrario, Allure usa los nombres de las funciones de prueba como nombres. También puedes dar un nombre personalizado a tu prueba. En Swift Testing, esto se logra usando la anotación @Test, mientras que XCTest emplea una convención de nomenclatura para actividades que te permite agregar varios metadatos a las pruebas, incluyendo nombres personalizados. Discutiremos la API de convención de nomenclatura con más detalle a continuación.
@Test("Este nombre fue asignado a la prueba a través de la anotación @Test")
func renamedTest() async throws {
}final class AllureApiActivities: XCTestCase {
func testDisplayName() throws {
XCTContext.runActivity(named: "allure.name:Este nombre fue establecido por una actividad", block: { _ in })
}
}2. Trabajar con Resultados
Aserciones Fallidas Swift Testing XCTest
Cuando un resultado de prueba incluye una o más aserciones fallidas, se marca como fallido. El conteo de fallas y los detalles de las fallas se listan en la página de resultados.
Consulta este ejemplo para ver cómo Allure maneja específicamente múltiples aserciones fallidas.
Excepciones No Capturadas Swift Testing XCTest
Cuando una prueba lanza una excepción no capturada, los frameworks de prueba la marcan como fallida y Allure captura los detalles de la excepción en el reporte de falla. Tales pruebas serán etiquetadas como Roto en el reporte Allure.
Omitir Pruebas Swift Testing XCTest
Swift Testing proporciona omisión nativa de pruebas a través del trait .disabled(). Opcionalmente puedes incluir una descripción explicando por qué la prueba está deshabilitada. Estas aparecen como Omitidas en el reporte Allure con la razón mostrada. XCTest soporta la omisión a través del error XCTSkip().
@Test(.disabled("Esta descripción fue proporcionada a través del trait disabled"))
func skippedTestWithDescription() async throws {
}func testSkippedTestWithDescription() throws {
throw XCTSkip("Esta descripción fue proporcionada a través de XCTSkip")
}
Fallas Esperadas XCTest
XCTExpectFailure() de XCTest te permite marcar pruebas que contienen aserciones que se sabe que fallarán. Cuando ocurre una falla esperada, la prueba pasa. Si la prueba pasa inesperadamente o falla de una manera diferente, se marca como fallida. Allure distingue entre fallas esperadas e inesperadas en el reporte.
func testOneExpectedFailureWithMessage() throws {
XCTExpectFailure("Este mensaje fue establecido a través de XCTExpectFailure")
XCTAssertEqual("foo", "bar")
}
func testUnmetExpectedFailure() throws {
XCTExpectFailure()
XCTAssertEqual("foo", "foo") // Esto pasa, pero esperábamos que fallara
}En el ejemplo anterior testOneExpectedFailureWithMessage será marcado como aprobado en Allure, ya que esperábamos que la aserción dentro fallara, mientras que testUnmetExpectedFailure se mostrará como fallido - ya que esperábamos que la aserción fallara, pero pasó en su lugar.
XCTExpectFailure() funciona de manera OR lógica: si al menos una aserción después de esta función falla, toda la prueba pasa. De lo contrario, la prueba falla.
Ejemplo: código muestra y el reporte generado basado en él.
3. Agrupación y Etiquetado de Pruebas
Allure 3 puede configurarse para agrupar resultados de prueba en un árbol de navegación conveniente por una amplia variedad de etiquetas. Esta sección discute cómo estas etiquetas son mapeadas y procesadas por la herramienta.
3.1. Suites y Jerarquía de Suites Swift Testing XCTest
Allure tiene tres niveles de suites:
- parentSuite
- suite
- subSuite
El mapeo exacto de estos niveles depende del framework de pruebas.
Swift Testing
La jerarquía de suite se mapea al árbol de navegación de Allure, creando una organización anidada en el reporte Allure que coincide con tu estructura de código:
- El nombre del módulo siempre se convierte en el parentSuite en Allure
- El suite de Swift Testing de nivel superior se convierte en el suite en Allure
- Los suites anidados se convierten en subSuites (si hay más de dos suites anidados, se unen con > y el resultado se asigna a subSuite)
- Suites no anotados usan nombres de struct (
UnannotatedSuite→UnannotatedSubSuite) - Suites nombrados usan nombres personalizados (
Named suite→Named sub-suite) - Las etiquetas testClass y testMethod siempre contienen los nombres originales de la clase/struct y el método.
// Suite no anotado - usa nombre de struct
struct UnannotatedSuite {
struct UnannotatedSubSuite {
struct UnannotatedSubSubSuite {
@Test("testInSubSubSuite (definido en Suites.swift)")
func testInSubSubSuite(){
}
}
@Test("testInSubSuite (definido en Suites.swift)")
func testInSubSuite(){
}
}
@Test("testInTopLevelSuite (definido en Suites.swift)")
func testInTopLevelSuite(){
}
}
// Suite nombrado con anotación @Suite
@Suite("Suite nombrado") struct NamedSuites {
@Suite("Sub-suite nombrado") struct NamedSubSuite {
@Test("testInNamedSubSuite (definido en Suites.swift)")
func testInNamedSubSuite(){
}
}
@Test("testInNamedTopLevelSuite (definido en Suites.swift)")
func testInNamedTopLevelSuite(){
}
}
XCTest
Para XCTest, los suites de Allure se basan en la estructura de clase de los archivos de prueba:
- El nombre del módulo siempre se convierte en el suite padre en Allure
- Cada clase se convierte en un suite en Allure
- La etiqueta testClass muestra el nombre de la clase
- La etiqueta suite típicamente coincide con el nombre de la clase
final class Activities: XCTestCase {
func testOnePassedActivity() throws {
XCTContext.runActivity(named: "Paso 1", block: { _ in })
}
func testOneActivityWithOneFailedAssertion() throws {
XCTContext.runActivity(named: "Paso 1") { _ in
XCTAssertEqual("foo", "bar")
}
}3.2. Paquetes Swift Testing XCTest
Allure automáticamente crea etiquetas de paquete usando el formato <proyecto>.<bundle>:
Ejemplos del proyecto de muestra:
XcresultSamples.XcresultSamplesSwiftTests(pruebas Swift Testing)
Estas aparecen como etiquetas package en los reportes Allure.
3.3. Actividades y Pasos XCTest
XCTest soporta organizar pruebas en actividades dentro de una sola función de prueba, que Allure luego traduce en pasos. Cada actividad se convierte en un paso (o subpaso) en el flujo de ejecución de la prueba.
func testSixNestedSteps() throws {
XCTContext.runActivity(named: "Paso 1") { _ in
XCTContext.runActivity(named: "Paso 1.1") { _ in
}
XCTContext.runActivity(named: "Paso 1.2") { _ in
}
}
XCTContext.runActivity(named: "Paso 2") { _ in
XCTContext.runActivity(named: "Paso 2.1") { _ in
}
XCTContext.runActivity(named: "Paso 2.2") { _ in
}
}
}
TIP
Allure tiene una API que permite agregar metadatos nativos de Allure (que XCTest no soporta) a tus pruebas nombrando actividades según cierta convención, que discutimos en la sección a continuación. Allure no traduce las actividades nombradas según la convención de API en pasos.
3.4. API de Allure: Convención de Nomenclatura de Metadatos XCTest
Los nombres de actividad XCTest además sirven como un vehículo para agregar metadatos y etiquetas nativas de Allure a tus pruebas.
Los nombres de actividad con prefijo allure.* se convierten en metadatos ricos en el reporte:
allure.name:establece nombres de prueba personalizadosallure.label.*:agrega etiquetas Allureallure.parameter.*:agrega información de parámetros con opciones de enmascaramientoallure.description.:agrega una descripciónallure.link.*:agrega un enlace (hay atajos convenientes para agregar enlaces a bugs, que discutimos a continuación)allure.flakymarca una prueba como inestable.
func testDisplayName() throws {
XCTContext.runActivity(named: "allure.name:Este nombre fue establecido por una actividad", block: { _ in })
}
func testLabel() throws {
XCTContext.runActivity(named: "allure.label.owner:John Doe", block: { _ in })
}
func testParameters() throws {
XCTContext.runActivity(named: "allure.parameter.Parámetro regular:Valor 1", block: { _ in })
XCTContext.runActivity(named: "allure.parameter.Parámetro enmascarado[masked]:Valor 2", block: { _ in })
}TIP
Allure no traduce tales actividades en pasos de prueba, así que no deberías poner código de prueba real en ellas.
Asegúrate también de que las actividades usadas para insertar metadatos de Allure en las pruebas no estén anidadas, de lo contrario no serán reconocidas adecuadamente. Este es un cambio del comportamiento de la herramienta CLI xcresultstool de Allure 2, que analiza incluso actividades anidadas para metadatos.
Ejemplo: código muestra y reporte
3.5. Etiquetas Swift Testing
Allure 3 soporta etiquetas de Swift Testing. Actualmente se muestran entre las etiquetas en la página de resultados de la prueba, y en versiones futuras será posible filtrar por ellas.
extension Tag {
@Tag static var fromSuite: Self
@Tag static var fromSubSuite: Self
@Tag static var fromTest: Self
}
@Suite(.tags(.fromSuite)) struct Tags {
@Suite(.tags(.fromSubSuite)) struct SubSuite {
@Test(.tags(.fromTest)) func hasTagsFromBothSuitesAndTest() {
}
@Test func hasTagsFromSuitesOnly() {
}
}
@Test(.tags(.fromTest)) func hasTagsFromOneSuiteAndTest() {
}
}Ejemplo: código muestra y reporte.
3.6. Repeticiones de Pruebas Swift Testing XCTest
Allure soporta ejecuciones repetidas de pruebas, si el bundle fuente las contiene. Puedes encontrar los resultados de repetición en la pestaña Reintentos de una página de resultado de prueba.
TIP
'Reintentos' es el término que Allure usa para ejecuciones repetidas de pruebas. Tiene el mismo significado que 'repeticiones' en Xcode.
3.7. Destinos (Dispositivos) y Múltiples Planes de Prueba Swift Testing XCTest
Allure automáticamente etiqueta todas las pruebas Xcode con el destino (el dispositivo físico o emulado en el que se ejecutan las pruebas), así como con nombres de planes de prueba, si tales datos existen en el bundle fuente.
Si tus bundles de resultados contienen datos de resultado para múltiples destinos o planes de prueba, puedes generar un reporte Allure con todos los registros, siempre que fusiones los bundles de diferentes destinos y/o planes de prueba en un solo bundle con el comando xcresulttool merge primero y luego uses el bundle fusionado para generar tu reporte Allure.
Si el bundle fuente contiene resultados de prueba para más de un destino, Allure muestra el parámetro Detalles del Dispositivo además del parámetro Dispositivo.
De manera similar, si el bundle contiene resultados de prueba para más de un plan de prueba, Allure muestra el parámetro Plan de Prueba.
4. Pruebas Parametrizadas Swift Testing
Las pruebas parametrizadas son una función nativa de Swift Testing que permite ejecutar la misma prueba con diferentes valores de entrada. XCTest no tiene soporte incorporado para pruebas parametrizadas.
struct Parameters {
@Test(arguments: ["foo", ""], [1, 2])
func twoParametersOneFail(Text text: String, Count count: Int) async throws {
#expect(!text.isEmpty) // Falla para ("", 1) y ("", 2)
#expect(count > 0)
}
}En el reporte Allure cada combinación de parámetros se convierte en un resultado de prueba separado agrupado bajo un solo Suite. Para cada resultado de prueba, los valores de parámetros se listan en el reporte.
Ejemplo: código muestra y reporte.
5. Seguimiento de Problemas Swift Testing XCTest
El seguimiento de problemas es una función nativa de Swift Testing que permite vincular pruebas a problemas conocidos. XCTest no tiene soporte incorporado para seguimiento de problemas, pero al igual que con los nombres personalizados, la convención de nomenclatura de Actividades puede usarse para agregar enlaces a problemas.
En Allure, si se proporcionan estos metadatos, se transforman en enlaces de problemas clicables.
@Test(.bug("https://github.com/allure-framework/allure3/issues/2", id: "2", "Problema #2"))
func bugUrlNameAndId() async throws {
}func testIssueLink() throws {
XCTContext.runActivity(named: "allure.issue.Problema 2:https://github.com/allure-framework/allure3/issues/2", block: { _ in })
}
6. Adjuntos XCTest
Los adjuntos te permiten incluir datos adicionales (texto, capturas de pantalla, logs) con los resultados de tus pruebas para depuración y análisis. Swift Testing soportará adjuntos básicos en Swift 6.2, pero actualmente solo XCTest proporciona capacidades completas de adjuntos.
func testTextAttachment() throws {
XCTContext.runActivity(named: "allure.description:El adjunto es visible solo en el reporte 'Múltiples destinos'", block: { _ in })
let attachment = XCTAttachment(string: "Lorem Ipsum")
attachment.name = "Un adjunto de texto"
self.add(attachment)
}Los adjuntos de texto pueden incluir logs, información de depuración o cualquier dato de cadena. Opcionalmente puedes proporcionar un nombre para mejor organización. Los adjuntos sin nombre obtienen nombres predeterminados en los reportes Allure.
A diferencia de Allure 2, en Allure 3 los adjuntos se muestran cronológicamente, en el orden en que fueron creados.
Dependiendo del tipo, los adjuntos se manejan de manera diferente. Las imágenes, por ejemplo, se renderizarán dentro del reporte Allure mismo y pueden descargarse convenientemente.
Ejemplo: código muestra y reporte.
7. Pruebas UI XCTest
Las pruebas UI están disponibles exclusivamente a través de XCTest y proporcionan capacidades para automatizar interacciones de interfaz de usuario y capturar evidencia visual.
Allure reconoce adjuntos de imagen y video generados por las pruebas UI de XCTest y los almacena en los pasos de prueba relevantes.
Ejemplo: código muestras y reportes (capturas de pantalla y grabaciones).
8. Errores de Compilación
Allure también procesa fallas de compilación. Si el bundle fuente contiene una sola ejecución que resulta en una falla de compilación, será el único resultado en el reporte Allure. Si el bundle tiene múltiples ejecuciones, algunas con fallas de compilación y otras con resultados de prueba, las fallas de compilación se mostrarán junto con los resultados de las pruebas.
