Referencia de las extensiones de Allure Kotlin

Estas son las funciones proporcionadas por las extensiones de Allure Kotlin. Todas ellas son funciones de nivel superior en el paquete io.qameta.allure.kotlin.extensions, excepto las funciones de corrutinas en io.qameta.allure.kotlin.coroutines. Puedes importar las funciones una por una o todas a la vez:

import io.qameta.allure.kotlin.extensions.*

Las funciones agregan información a la prueba, fixture o paso que se está ejecutando actualmente, de la misma manera que la API en tiempo de ejecución de la integración de tu framework de pruebas, por ejemplo, Allure JUnit Jupiter. Las llamadas realizadas mientras no se está ejecutando ninguna prueba o fixture no tienen efecto.

Metadatos

Asigna la descripción, enlaces y otros metadatos de una prueba.

Descripción

• description(description: String)
• descriptionHtml(descriptionHtml: String)

Establece la descripción de la prueba. description() acepta Markdown, descriptionHtml() acepta HTML.

import io.qameta.allure.kotlin.extensions.description
import org.junit.jupiter.api.Test

class TestMyWebsite {

    @Test
    fun testAuthentication() {
        description("This test attempts to log into the website using a login and a password. Fails if any error happens.\n\nNote that this test does not test 2-Factor Authentication.")
        // ...
    }
}

Etiqueta

• label(name: String, value: String)

Agrega una etiqueta con el nombre y valor dados a la prueba.

import io.qameta.allure.kotlin.extensions.label
import org.junit.jupiter.api.Test

class TestMyWebsite {

    @Test
    fun testAuthentication() {
        label(name = "component", value = "authentication")
        label(name = "owner", value = "John Doe")
        // ...
    }
}

Enlace

• link(url: String)
• link(name: String, url: String)
• link(name: String, type: String, url: String)
• issue(name: String, url: String)
• tms(name: String, url: String)

Agrega un enlace relacionado con la prueba. issue() y tms() agregan enlaces de los tipos issue y tms.

import io.qameta.allure.kotlin.extensions.issue
import io.qameta.allure.kotlin.extensions.link
import io.qameta.allure.kotlin.extensions.tms
import org.junit.jupiter.api.Test

class TestMyWebsite {

    @Test
    fun testAuthentication() {
        link(name = "Website", url = "https://dev.example.com/")
        issue(name = "AUTH-123", url = "https://issues.example.com/AUTH-123")
        tms(name = "TMS-456", url = "https://tms.example.com/TMS-456")
        // ...
    }
}

Jerarquía basada en comportamiento

• epic(value: String)
• feature(value: String)
• story(value: String)

Asigna los nombres del epic, feature e historia de usuario a la prueba, como parte de la jerarquía basada en comportamiento de Allure.

import io.qameta.allure.kotlin.extensions.epic
import io.qameta.allure.kotlin.extensions.feature
import io.qameta.allure.kotlin.extensions.story
import org.junit.jupiter.api.Test

class TestMyWebsite {

    @Test
    fun testAuthentication() {
        epic("Web interface")
        feature("Essential features")
        story("Authentication")
        // ...
    }
}

Jerarquía basada en suites

• suite(value: String)

Asigna el nombre de la suite, como parte de la jerarquía basada en suites de Allure. Para establecer los otros niveles de la jerarquía, usa label() con el nombre de etiqueta parentSuite o subSuite.

import io.qameta.allure.kotlin.extensions.suite
import org.junit.jupiter.api.Test

class TestMyWebsite {

    @Test
    fun testAuthentication() {
        suite("Tests for essential features")
        // ...
    }
}

Pasos de prueba

• step(name: String = "step", body: StepScope.() -> T): T
• step(name: String, status: Status = Status.PASSED)

Define un paso de prueba.

La primera función ejecuta el código en body como un paso con el name dado y devuelve el valor que el código devuelve. Si el código lanza una excepción, el paso se marca como fallido (para errores de aserción) o roto (para otras excepciones), y la excepción se propaga. Los pasos pueden contener otros pasos.

La segunda función agrega un paso que ya ha finalizado, con el name y status dados.

Dentro de body, están disponibles las siguientes funciones:

• name(name: String) - cambia el nombre del paso, por ejemplo, para incluir un valor que se conoce durante el paso.
• parameter(name: String, value: T, excluded: Boolean? = null, mode: Parameter.Mode? = null): T - agrega un parámetro al paso. Los argumentos son los mismos que para los parámetros de prueba.

import io.qameta.allure.kotlin.extensions.step
import io.qameta.allure.model.Status
import org.junit.jupiter.api.Test

class TestOrders {

    @Test
    fun testCreateOrder() {
        val orderId = step("Create order") {
            parameter(name = "region", value = "eu-west")
            val id = createOrder()
            name("Create order $id")
            id
        }

        step("Check the order") {
            step("Order exists")
            step("Delivery date is set", Status.SKIPPED)
            verifyOrder(orderId)
        }
    }
}

Etapas

• stage(name: String)

Inicia una etapa: un grupo con nombre de pasos para una fase de la prueba, como preparar datos o verificar resultados. Una etapa se muestra como un paso. No tiene un final explícito: contiene los pasos y adjuntos que la siguen, hasta que comienza la siguiente etapa o termina el paso, prueba o fixture que la contiene. Una etapa iniciada dentro de un paso se convierte en parte de ese paso.

import io.qameta.allure.kotlin.extensions.stage
import io.qameta.allure.kotlin.extensions.step
import org.junit.jupiter.api.Test

class TestOrders {

    @Test
    fun testCreateOrder() {
        stage("Prepare data")
        step("Create a customer")
        step("Add products to the cart")

        stage("Submit the order")
        step("Open the checkout page")
        step("Confirm the order")

        stage("Verify the result")
        step("Order status is created")
    }
}

Pruebas parametrizadas

• parameter(name: String, value: T, excluded: Boolean? = null, mode: Parameter.Mode? = null): T

Agrega un parámetro con el nombre y valor dados a la prueba, y devuelve el valor. Allure Report muestra los parámetros en la página de la prueba. Diferentes valores de un parámetro producen pruebas distintas en el historial, a menos que el parámetro esté excluido.

• excluded - si es true, el parámetro no se usa para diferenciar pruebas en el historial. Úsalo para valores que cambian en cada ejecución, como las marcas de tiempo.
• mode - cómo se muestra el parámetro en el reporte: Parameter.Mode.DEFAULT muestra el parámetro y su valor, Parameter.Mode.MASKED muestra el parámetro pero oculta su valor (úsalo para contraseñas, tokens y otros valores sensibles), Parameter.Mode.HIDDEN no muestra el parámetro en absoluto. Ten en cuenta que los valores de los parámetros silenciados y ocultos se siguen almacenando en el directorio de resultados de prueba.

Los parámetros agregados de esta manera se muestran junto con los que reporta la integración de tu framework de pruebas, por ejemplo, los argumentos de una prueba parametrizada.

import io.qameta.allure.kotlin.extensions.parameter
import io.qameta.allure.model.Parameter
import org.junit.jupiter.params.ParameterizedTest
import org.junit.jupiter.params.provider.ValueSource

class TestMyWebsite {

    @ParameterizedTest
    @ValueSource(strings = ["johndoe", "janedoe"])
    fun testAuthentication(login: String) {
        val browser = parameter("browser", "firefox")
        parameter(name = "password", value = "qwerty", mode = Parameter.Mode.MASKED)
        parameter(name = "startedAt", value = System.currentTimeMillis(), excluded = true)
        // ...
    }
}

Adjuntos

• attachment(name: String, content: String, type: String = "text/plain", fileExtension: String? = null)
• attachment(name: String, content: ByteArray, type: String = "application/octet-stream", fileExtension: String? = null)
• attachment(name: String, content: InputStream, type: String = "application/octet-stream", fileExtension: String? = null)
• attachmentAsync(name: String, content: CompletionStage<out InputStream>, type: String = "application/octet-stream", fileExtension: String? = null): CompletableFuture<Void>
• addHttpExchange(name: String, exchange: HttpExchange)

Agrega un adjunto con el nombre y contenido dados. Como en otras integraciones de Allure Java, cada adjunto se muestra como un paso con el nombre del adjunto.

El type es el tipo de medio del contenido. Define cómo Allure Report muestra el adjunto. Si no se establece fileExtension, la extensión del archivo se elige en función del tipo. Pasa una cadena vacía para guardar el archivo sin extensión.

attachmentAsync() no espera el contenido. Devuelve un future que se completa cuando se escribe el adjunto. La prueba, fixture o paso al que pertenece el adjunto lo espera antes de terminar.

addHttpExchange() agrega un adjunto de intercambio HTTP que tú mismo construiste.

import io.qameta.allure.kotlin.extensions.attachment
import io.qameta.allure.kotlin.extensions.attachmentAsync
import org.junit.jupiter.api.Test
import java.util.concurrent.CompletableFuture

class TestMyWebsite {

    @Test
    fun testAuthentication() {
        attachment(name = "response", content = """{"status": "ok"}""", type = "application/json")
        attachment(name = "screenshot", content = takeScreenshot(), type = "image/png")

        attachmentAsync(
            name = "server log",
            content = CompletableFuture.supplyAsync { downloadServerLog() },
            type = "text/plain",
            fileExtension = "log",
        )
        // ...
    }
}

Errores globales

• globalError(throwable: Throwable)
• globalError(statusDetails: StatusDetails)

Reporta un error que no pertenece a una sola prueba, como un entorno que no está disponible. Consulta Errores y adjuntos globales.

import io.qameta.allure.kotlin.extensions.globalError
import io.qameta.allure.model.StatusDetails

globalError(IllegalStateException("Test database snapshot is outdated"))
globalError(StatusDetails().setMessage("Payment sandbox is not available"))

Corrutinas

Las funciones de esta sección las proporciona el módulo allure-kotlin-coroutines.

Allure recuerda la prueba y el paso en ejecución por separado para cada hilo. Las corrutinas pueden cambiar de hilo, por ejemplo, después de withContext(Dispatchers.IO), y el hilo en el que continúan puede no saber qué prueba se está ejecutando. Los pasos y adjuntos agregados allí pueden perderse, o terminar en una prueba distinta si varias pruebas se ejecutan en paralelo. Las funciones a continuación se asegurar de que terminen en la prueba y el paso correctos.

Pasos suspendidos

• step(name: String = "step", body: suspend StepScope.() -> T): T

Igual que step() de allure-kotlin-extensions, pero el código en body puede suspenderse. El paso sigue siendo el paso actual cuando el código cambia de hilo, de modo que los pasos y adjuntos agregados dentro de él se muestran en él.

Si la corrutina se cancela, el paso se marca como roto, y la excepción de cancelación se propaga.

import io.qameta.allure.kotlin.coroutines.step
import io.qameta.allure.kotlin.extensions.attachment
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withContext
import org.junit.jupiter.api.Test

class TestOrders {

    @Test
    fun testLoadOrder() {
        runBlocking {
            step("Load order") {
                val order = withContext(Dispatchers.IO) {
                    orderClient.load()
                }
                parameter("orderId", order.id)
                attachment(name = "order", content = order.toString())
            }
        }
    }
}

Esta función tiene el mismo nombre que step() de io.qameta.allure.kotlin.extensions. Si un archivo necesita ambas, importa una de ellas con un nombre diferente, por ejemplo, import io.qameta.allure.kotlin.extensions.step as syncStep.

Pasar la prueba actual a las corrutinas

• withAllureContext(lifecycle: AllureLifecycle = Allure.getLifecycle(), body: suspend CoroutineScope.() -> T): T
• allureContext(): CoroutineContext

Cuando inicies corrutinas que se ejecutan en otros hilos, como launch(Dispatchers.IO), ejecútalas dentro de withAllureContext(). Esta función recuerda la prueba, fixture o paso que se está ejecutando cuando se llama y la pasa a todas las corrutinas iniciadas dentro de ella. Los pasos iniciados en corrutinas paralelas se muestran uno junto al otro, no uno dentro del otro.

import io.qameta.allure.kotlin.coroutines.step
import io.qameta.allure.kotlin.coroutines.withAllureContext
import io.qameta.allure.kotlin.extensions.attachment
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import org.junit.jupiter.api.Test

class TestReports {

    @Test
    fun testBuildReports() {
        runBlocking {
            withAllureContext {
                coroutineScope {
                    launch(Dispatchers.IO) {
                        attachment(name = "worker output", content = loadOutput())
                    }
                    launch(Dispatchers.Default) {
                        step("Calculate summary") {
                            calculateSummary()
                        }
                    }
                }
            }
        }
    }
}

Alternativamente, agrega allureContext() al contexto de una sola corrutina:

launch(Dispatchers.IO + allureContext()) {
    // ...
}

Asegúrate de que las corrutinas terminen antes de que finalice la prueba, fixture o paso que las inició, por ejemplo, iniciándolas dentro de coroutineScope { } como se muestra arriba. No uses GlobalScope ni otras formas de iniciar corrutinas que puedan sobrevivir a la prueba.

Anotaciones y corrutinas

Las anotaciones @Step y @Attachment funcionan en código Kotlin de la misma manera que en Java, y necesitan AspectJ, como se describe en la documentación de la integración de tu framework de pruebas. Las funciones de esta página no necesitan AspectJ.

No uses @Step en funciones suspend. Dichos pasos obtienen un parámetro adicional con datos internos, y los pasos agregados después de que la función cambia de hilo pueden no aparecer en el paso. Usa en su lugar la función suspendida step().