Referencia de Allure JUnit 4

Estas son las funciones que puedes usar para integrar tus pruebas de JUnit 4 con Allure.

Allure JUnit 4 proporciona más de una forma de usar algunas características. En la mayoría de los casos, una forma implica usar una anotación en el método de prueba, mientras que la otra implica una llamada a un método dentro del cuerpo del método de prueba. Este último estilo se denomina “dinámico” y permite construir valores de manera dinámica.

Metadatos

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

Title

• @DisplayName(String value)
• Allure.getLifecycle().updateTestCase(Consumer<TestResult> update)

Establece el título de la prueba.

Si necesitas construir dinámicamente el título de una prueba, escribe una función lambda que lo haga y pásala al método updateTestCase() del objeto AllureLifecycle, como se muestra en el ejemplo a continuación.

Annotations API

import io.qameta.allure.junit4.DisplayName;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    @DisplayName("Test Authentication")
    public void testAuthentication() {
        // ...
    }
}

Runtime API

import io.qameta.allure.Allure;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    public void testAuthentication() {
        Allure.getLifecycle().updateTestCase(result -> {
            result.setName("Test Authentication");
        });
        // ...
    }
}

Description

• @Description(String value="")
• Allure.description(String description)

Establece la descripción de la prueba.

Usa la anotación @Description() para establecer una descripción de forma estática o usa el método description() para configurarla dinámicamente en tiempo de ejecución.

Annotations API

import io.qameta.allure.Description;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    @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.")
    public void testAuthentication() {
        // ...
    }
}

Runtime API

import io.qameta.allure.Allure;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    public void testAuthentication() {
        Allure.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.");
        // ...
    }
}

Alternativamente, puedes permitir que Allure JUnit 4 analice la descripción del comentario JavaDoc del método de prueba. Para hacerlo, primero agrega un procesador de anotaciones especial a la configuración de Maven o Gradle de tu proyecto.

// In the project's `build.gradle.kts`:
val allureVersion = "2.24.0"

dependencies {
    // ...
    testAnnotationProcessor("io.qameta.allure:allure-descriptions-javadoc:$allureVersion")
}

Luego, utiliza la API de Anotaciones sin argumentos para analizar la descripción desde JavaDoc. Ten en cuenta que, en un proyecto grande, procesar las anotaciones puede aumentar significativamente tanto el tiempo de compilación como el tamaño de los archivos ejecutables de prueba.

Se permite el formato Markdown. Cualquier formato HTML, si está presente, será eliminado por motivos de seguridad.

import io.qameta.allure.Description;
import org.junit.Test;

public class TestMyWebsite {

    /**
     * This test attempts to log into the website using a login and a password. Fails if any error happens.
     * <p>
     * Note that this test does not test 2-Factor Authentication.
     */
    @Test
    @Description
    public void testAuthentication() {
        // ...
    }
}

Owner

• @Owner(String value="")

Establece el propietario de la prueba.

Annotations API

import io.qameta.allure.Owner;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    @Owner("John Doe")
    public void testAuthentication() {
        // ...
    }
}

Runtime API

import io.qameta.allure.Allure;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    public void testAuthentication() {
        Allure.label("owner", "John Doe");
        // ...
    }
}

Tag

• @Tag(String value)
• @Tags(Tag[] value)

Establece los tags de la prueba.

Annotations API

import io.qameta.allure.junit4.Tag;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    @Tag("NewUI")
    @Tag("Essentials")
    @Tag("Authentication")
    public void testAuthentication() {
        // ...
    }
}

Runtime API

import io.qameta.allure.Allure;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    public void testAuthentication() {
        Allure.label("tag", "NewUI");
        Allure.label("tag", "Essentials");
        Allure.label("tag", "Authentication");
        // ...
    }
}

Severity

• @Severity(SeverityLevel value)

Establece la gravedad de la prueba.

Los valores permitidos son: “trivial”, “minor”, “normal”, “critical”, y “blocker”.

Annotations API

import io.qameta.allure.Severity;
import org.junit.Test;

import static io.qameta.allure.SeverityLevel.*;

public class TestMyWebsite {

    @Test
    @Severity(CRITICAL)
    public void testAuthentication() {
        // ...
    }
}

Runtime API

import io.qameta.allure.Allure;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    public void testAuthentication() {
        Allure.label("severity", "critical");
        // ...
    }
}

Label

• @LabelAnnotation(String name, String value=DEFAULT_VALUE)
• Allure.label(String name, String value)

Asigna una etiqueta arbitraria para la prueba. Esta es la implementación subyacente para muchas de las otras funciones de Allure.

Para establecer una etiqueta de manera dinámica, simplemente llama a la función label() con un nombre y un valor para la etiqueta. Puedes llamarla varias veces para crear un arreglo de valores bajo ese nombre.

Otra forma de asignar una etiqueta es crear una clase personalizada usando @LabelAnnotation (en un archivo separado) y anotar las pruebas con la nueva anotación. Consulta el ejemplo a continuación. Por favor, asegúrate de copiar @Retention, @Target y las otras anotaciones necesarias como se muestra en el ejemplo, de lo contrario, tu anotación personalizada podría no funcionar correctamente.

Annotations API

import io.qameta.allure.LabelAnnotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
@LabelAnnotation(name = "CustomLabelName")
@interface MyLabel {
    String value();
}

java

import org.junit.Test;

public class TestMyWebsite {

    @Test
    @MyLabel("custom label value")
    public void testAuthentication() {
        // ...
    }
}

Runtime API

import io.qameta.allure.Allure;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    public void testAuthentication() {
        Allure.label("language", "java");
        Allure.label("framework", "junit4");
        Allure.label("CustomLabelName", "custom label value");
        // ...
    }
}

Allure ID (Allure TestOps)

• @AllureId(String value)

Establece el ID de la prueba.

import io.qameta.allure.AllureId;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    @AllureId("123")
    public void testAuthentication() {
        // ...
    }
}

Link

• @Link(String value="", name="", String url="", String type=CUSTOM_LINK_TYPE)
• @Links(Link[] value)
• @Issue(String value="")
• @Issues(Issue[] value)
• @TmsLink(String value="")
• @TmsLinks(TmsLink[] value)
• Allure.link(String url)
• Allure.link(String name, String url)
• Allure.link(String name, String type, String url)
• Allure.issue(String name, String url)
• Allure.tms(String name, String url)

Agrega un enlace relacionado con la prueba.

Según el type (que puede ser cualquier cadena), Allure intentará cargar un patrón de enlace correspondiente para procesar la URL, según lo definido por la opción de configuración allure.link.*.pattern. Si no se encuentra un patrón para el tipo dado, la URL se dejará sin modificar.

El name se utilizará como texto del enlace. Si se omite, se usará la URL sin procesar.

Para mayor comodidad, Allure proporciona dos funciones abreviadas con tipos de enlace preseleccionados: issue() y tms().

Annotations API

import io.qameta.allure.Issue;
import io.qameta.allure.Link;
import io.qameta.allure.TmsLink;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    @Link(name = "Website", url = "https://dev.example.com/")
    @Issue("AUTH-123")
    @TmsLink("TMS-456")
    public void testAuthentication() {
        // ...
    }
}

Runtime API

import io.qameta.allure.Allure;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    public void testAuthentication() {
        Allure.link("Website", "https://dev.example.com/");
        Allure.issue("AUTH-123", "https://jira.example.org/browse/AUTH-123");
        Allure.tms("TMS-456", "https://tms.example.org/TMS-456");
        // ...
    }
}

Jerarquía basada en el comportamiento

• @Epic(String value="")
• @Epics(Epic[] value)
• @Feature(String value="")
• @Features(Feature[] value)
• @Story(String value="")
• @Stories(Story[] value)
• Allure.epic(String value)
• Allure.feature(String value)
• Allure.story(String value)

Asigna nombres de epics, features o user stories para una prueba, como parte de la jerarquía basada en comportamiento de Allure.

Annotations API

import io.qameta.allure.Epic;
import io.qameta.allure.Feature;
import io.qameta.allure.Story;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    @Epic("Web interface")
    @Feature("Essential features")
    @Story("Authentication")
    public void testAuthentication() {
        // ...
    }
}

Runtime API

import io.qameta.allure.Allure;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    public void testAuthentication() {
        Allure.epic("Web interface");
        Allure.feature("Essential features");
        Allure.story("Authentication");
        // ...
    }
}

Jerarquía basada en la suite

• Allure.suite(String value)

Asigna el nombre de suite, como parte de la jerarquía basada en suites de Allure.

Runtime API

import io.qameta.allure.Allure;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    public void testAuthentication() {
        Allure.label("parentSuite" "Tests for web interface");
        Allure.suite("Tests for essential features");
        Allure.label("subSuite", "Tests for authentication");
        // ...
    }
}

Pasos de prueba

• @Step(String value="")
• @Param(String value="", String name="", Parameter.Mode mode=DEFAULT, boolean excluded=false)
• Allure.step(String name)
• Allure.step(String name, Status status)
• Allure.step(String name, ThrowableRunnableVoid runnable)
• Allure.step(String name, ThrowableRunnable<T> runnable)
• Allure.step(ThrowableContextRunnableVoid<StepContext> runnable)
• Allure.step(String name, ThrowableContextRunnableVoid<StepContext> runnable)
• Allure.step(String name, ThrowableContextRunnable<T, StepContext> runnable)
• Allure.step(ThrowableContextRunnable<T, StepContext> runnable)

Define un paso de prueba con el name proporcionado.

Hay tres maneras de definir un paso.

• “Un paso anotado”: define un método que contenga un paso de prueba y decóralo con @Step().
• “Un paso lambda”: escribe un paso de prueba en una función lambda y pásalo a Allure.step().
• “Un paso no-op”: simplemente pasa un name y un status opcional a Allure.step() para agregar inmediatamente una entrada correspondiente a los resultados como un sub-paso del paso actual.

Cuando implementes un paso anotado que tome argumentos, puedes especificar nombres legibles para humanos mediante la anotación @Param. Los argumentos se mostrarán como parámetros a nivel de paso bajo los nombres proporcionados. Para los argumentos sin la anotación @Param, Allure JUnit 4 usará nombres que indiquen el orden de los argumentos (“arg1”, “arg2”, etc.) o los nombres de los argumentos del código Java. Esto último requiere el argumento del compilador -parameters, consulta Cómo empezar.

Cuando implementes una función para un paso lambda, puede aceptar o bien ningún argumento o un único argumento de la clase StepContext. Este objeto proporciona los siguientes métodos:

• name() — sobrescribe el nombre del paso durante su ejecución.
• parameter() — indica parámetros arbitrarios utilizados para el paso.

Tanto la anotación @Param como el método parameter() del contexto de pasos permiten los mismos argumentos adicionales que la implementación a nivel de prueba de las pruebas parametrizadas.

Annotated steps

import io.qameta.allure.Param;
import io.qameta.allure.Step;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    public void testAuthentication() {
        testAuthenticationWith("https://1.example.com/", "alice", "qwerty");
        testAuthenticationWith("https://2.example.com/", "bob", "asdfgh");
        testAuthenticationWith("https://3.example.com/", "charlie", "zxcvbn");
    }

    @Step("Authenticate on {url}")
    void testAuthenticationWith(String url, String login, String password) {
        openWebPage(url);
        enterCredentials(login, password);
        checkIfLoggedInAs(login);
    }

    @Step("Visit {url}")
    void openWebPage(@Param("URL") String url) {
        // ...
    }

    @Step("Enter credentials")
    void enterCredentials(
            @Param("Login") String login,
            @Param("Password") String password
    ) {
        // ...
    }

    @Step("Check if I am logged in")
    void checkIfLoggedInAs(
            @Param("Login") String login
    ) {
        // ...
    }
}

Lambda steps

import io.qameta.allure.Allure;
import org.junit.Test;

public class TestMyWebsite {

    private static final String[][] authenticationData = new String[][]{
            {"https://1.example.com/", "alice", "qwerty"},
            {"https://2.example.com/", "bob", "asdfgh"},
            {"https://3.example.com/", "charlie", "zxcvbn"},
    };

    @Test
    public void testAuthentication() {

        for (String[] data : authenticationData) {
            String url = data[0];
            String login = data[1];
            String password = data[2];

            Allure.step("Authenticate on %s".formatted(url), () -> {

                Allure.step("Visit %s".formatted(url), stepContext -> {
                    stepContext.parameter("URL", url);
                    // ...
                });

                Allure.step("Enter credentials", stepContext -> {
                    stepContext.parameter("Login", login);
                    stepContext.parameter("Password", password);
                    // ...
                });

                Allure.step("Check if I am logged in", stepContext -> {
                    stepContext.parameter("Login", login);
                    // ...
                });
            });
        }
    }
}

No-op steps

import io.qameta.allure.Allure;
import io.qameta.allure.model.Status;
import org.junit.Test;

public class TestMyWebsite {

    private static final String[][] authenticationData = new String[][]{
            {"https://1.example.com/", "alice", "qwerty"},
            {"https://2.example.com/", "bob", "asdfgh"},
            {"https://3.example.com/", "charlie", "zxcvbn"},
    };

    @Test
    public void testAuthentication() {

        for (String[] data : authenticationData) {
            String url = data[0];
            String login = data[1];
            String password = data[2];

            Allure.step("Begin testing %s...".formatted(url));
            try {
                // ...
                Allure.step("Visited %s.".formatted(url));

                // ...
                Allure.step("Entered credentials.");

                // ...
                Allure.step("I am logged in!");

            } catch (Exception e) {
                Allure.step("Failed!", Status.FAILED);
            }
        }
    }
}

Pruebas parametrizadas

• Allure.parameter(String name, T value)
• Allure.parameter(String name, T value, Boolean excluded)
• Allure.parameter(String name, T value, Parameter.Mode mode)
• Allure.parameter(String name, T value, Boolean excluded, Parameter.Mode mode)

Especifica un name y un value de un parámetro que se usó durante esta prueba. Consulta Pruebas parametrizadas para más detalles.

WARNING

Allure JUnit 4 identifica las pruebas solo en función de sus nombres. Si tienes varias pruebas que solo difieren en los parámetros, serán tratadas como una sola prueba para los fines de Historial y reintentos.

Si el argumento excluded está configurado como verdadero, Allure no usará el parámetro al comparar el resultado actual de la prueba con el anterior en el historial. Este argumento solo lo usa Allure TestOps.

El argumento mode afecta cómo se mostrará el parámetro en el informe. Las opciones disponibles están definidas en la enumeración Parameter.Mode:

• Parameter.Mode.DEFAULT (igual que no especificar ningún modo) — el parámetro y su valor se mostrarán en una tabla junto con otros parámetros.
• Parameter.Mode.MASKED — el parámetro se mostrará en la tabla, pero su valor será ocultado. Usa este modo para contraseñas, tokens y otros parámetros sensibles.
• Parameter.Mode.HIDDEN — el parámetro y su valor no se mostrarán en el informe de la prueba. Sin embargo, ten en cuenta que aún es posible extraer el valor del directorio allure_results si lo publicas.

import io.qameta.allure.Allure;
import org.junit.Test;

public class TestMyWebsite {

    @Test
    public void testAuthenticationWithUsername() {
        Allure.parameter("login", "johndoe");
        // ...
    }

    @Test
    public void testAuthenticationWithEmail() {
        Allure.parameter("login", "[email protected]");
        // ...
    }
}

Archivos adjuntos

• @Attachment(String value="", String type="", String fileExtension="")
• Allure.addAttachment(String name, String content)
• Allure.addAttachment(String name, String type, String content)
• Allure.addAttachment(String name, String type, String content, String fileExtension)
• Allure.addAttachment(String name, InputStream content)
• Allure.addAttachment(String name, String type, InputStream content, String fileExtension)
• Allure.attachment(String name, String content)
• Allure.attachment(String name, InputStream content)

Agrega content como un adjunto al resultado de la prueba bajo el name dado (por defecto se usa una cadena pseudo-aleatoria única).

TIP

Puedes usar datos producidos por cualquier función, no necesariamente leídos desde un archivo real.

Para crear un adjunto usando la API de Anotaciones, define un método que retorne algunos datos y anótalo con @Attachment. Llama al método en cualquier momento durante tu prueba.

Para crear un adjunto usando la API en Tiempo de Ejecución, simplemente llama a addAttachment() o attachment() en cualquier momento durante tu prueba. Pasa los datos como el argumento content.

Los datos serán procesados de la siguiente manera:

• Si el tipo de dato es byte[], Allure lo usará sin modificaciones.
• Si el tipo de dato es String, Allure lo convertirá a byte[].
• Si el dato es de cualquier otro tipo, Allure llamará al método toString() y luego convertirá la cadena a byte[].

Para asegurar que el navegador web del lector muestre los adjuntos correctamente, se recomienda especificar el tipo de cada adjunto. Para hacerlo, pasa el tipo de medio del contenido como type y, opcionalmente, una extensión de archivo como fileExtension. El tipo de medio afecta cómo se mostrará el dato en el informe de la prueba, mientras que la extensión de archivo se agrega al nombre del archivo cuando el usuario quiere guardarlo.

Annotations API

import io.qameta.allure.Attachment;
import org.junit.Test;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;

public class TestMyWebsite {

    @Test
    public void testAuthentication() throws IOException {
        // ...
        attachDataTXT();
        attachScreenshotPNG();
    }

    @Attachment(value = "data", type = "text/plain", fileExtension = ".txt")
    public String attachDataTXT() {
        return "This is the file content.";
    }

    @Attachment(value = "screenshot", type = "image/png", fileExtension = ".png")
    public byte[] attachScreenshotPNG() throws IOException {
        return Files.readAllBytes(Paths.get("/path/to/image.png"));
    }
}

Runtime API

import io.qameta.allure.Allure;
import org.junit.Test;

import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Paths;

public class TestMyWebsite {

    @Test
    public void testAuthentication() throws IOException {
        // ...
        Allure.attachment("data.txt", "This is the file content.");
        try (InputStream is = Files.newInputStream(Paths.get("/path/img.png"))) {
            Allure.attachment("image.png", is);
        }
    }
}

INFO

Además, Allure ofrece una forma de generar hilos que agregarán adjuntos a los resultados de las pruebas de manera asincrónica sin bloquear el corredor de pruebas. Aunque no se recomienda para la mayoría de los casos, este enfoque puede mejorar las pruebas que, de otro modo, tendrían que esperar a procesar archivos muy grandes, como videos de más de 1 GB. Consulta el código fuente de Allure.addByteAttachmentAsync() y Allure.addStreamAttachmentAsync() para obtener más información.

Historial de resultados

Inestable

• @Flaky

Indica que se sabe que la prueba es inestable y puede no tener éxito cada vez. Consulta Pruebas inestables.