Empezando con Allure xUnit.net
Genera hermosos informes en HTML utilizando Allure Report y tus pruebas de xUnit.net.
INFO
Consulta el proyecto de ejemplo en github.com/allure-examples/allure-xunit para ver Allure xUnit.net en acción.
Configuración
1. Verificar los prerrequisitos
Asegúrate de que la herramienta de línea de comandos de Allure Report esté instalada. Si no lo está, consulta las instrucciones de instalación.
Verifica el SDK de .NET con el que se compila tu proyecto de pruebas. Allure xUnit.net es compatible con los siguientes SDKs:
- .NET Core 3.1
- .NET 5.0 y versiones posteriores
Visita la documentación oficial para más información sobre cómo instalar o actualizar el SDK de .NET.
Asegúrate de que tu proyecto de pruebas haga referencia a una versión compatible de xUnit.net. Actualmente, se admite xUnit.net v2 a partir de la versión 2.4.1.
El soporte para xUnit.net v3 se añadirá en el futuro (puedes hacer seguimiento de esta tarea en este issue).
INFO
Allure xUnit.net no puede funcionar con la versión 3 de
xunit.runner.visualstudiodebido a cambios en cómo el ejecutor detecta los reporteros personalizados. Debes hacer un downgrade a la versión 2.8.2 o anterior para seguir utilizándolo con Allure xUnit.net.
2. Prepara tu proyecto
Añade
Allure.Xunita las dependencias de tu proyecto usando tu IDE o la línea de comandos.Por ejemplo, así se puede añadir la dependencia a un proyecto con el CLI
dotnet:plaindotnet add ⟨PATH TO PROJECT⟩ package Allure.XunitSelecciona explícitamente
allurecomo el reportero del ejecutor xUnit.net.Este paso solo es necesario si tienes dos o más reporteros "habilitados ambientalmente" de xUnit.net, lo que significa que el ejecutor de pruebas puede o no usar el reportero Allure xUnit.net por defecto en cada ejecución. Esto suele suceder cuando se ejecutan pruebas en una plataforma CI, como Microsoft Azure o TeamCity, ya que un reportero que envía los resultados de las pruebas a la plataforma CI puede estar habilitado además de Allure xUnit.net en dicho entorno.
La forma de seleccionar el reportero depende del ejecutor de pruebas que uses en el proyecto. Por ejemplo, si usas el ejecutor predeterminado de xUnit.net
xunit.runner.visualstudio, necesitas modificar la configuración deReporterSwitch:xml<?xml version="1.0" encoding="utf-8"?> <RunSettings> <RunConfiguration> <ReporterSwitch>allure</ReporterSwitch> </RunConfiguration> </RunSettings>plaindotnet test -- RunConfiguration.ReporterSwitch=allureTIP
Por defecto, Allure xUnit.net también intentará ejecutar otro reportero habilitado ambientalmente, si está presente. Este comportamiento puede cambiarse utilizando la opción de configuración
xunitRunnerReporter.
3. Ejecuta las pruebas
Ejecuta tus pruebas de xUnit.net de la misma manera que normalmente lo harías. Por ejemplo:
dotnet testEsto guardará los datos necesarios en el directorio allure-results u otro directorio, según la configuración de allure.directory. Si el directorio ya existe, los nuevos archivos se añadirán a los existentes, para que un informe futuro se base en todos ellos.
4. Genera un informe
Finalmente, convierte los resultados de las pruebas en un informe en HTML. Esto se puede hacer con uno de dos comandos:
allure generateprocesa los resultados de las pruebas y guarda un informe HTML en el directorioallure-report. Para ver el informe, usa el comandoallure open.Usa este comando si necesitas guardar el informe para futura referencia o para compartirlo con tus compañeros.
allure servecrea el mismo informe queallure generate, pero lo coloca en un directorio temporal y comienza un servidor web local configurado para mostrar el contenido de este directorio. El comando abrirá automáticamente la página principal del informe en un navegador web.Usa este comando si necesitas ver el informe por ti mismo y no necesitas guardarlo.
Escribir pruebas
El adaptador Allure xUnit.net extiende las características estándar de informes de xUnit.net proporcionando capacidades adicionales para crear pruebas más informativas y estructuradas. Esta sección destaca las mejoras clave que se pueden utilizar:
- Anotación de Metadatos: Mejora los informes de las pruebas con descripciones, enlaces y otros metadatos.
- Organización de Pruebas: Estructura tus pruebas en jerarquías claras para una mejor legibilidad y organización.
- Distinción de estados de las pruebas: Distingue entre afirmaciones fallidas y excepciones no controladas con estados fallidos y rotos.
- División en pasos: Divide las pruebas en pasos más pequeños para facilitar su comprensión y mantenimiento.
- Métodos Constructores y Dispose: Incluye la inicialización y finalización de contextos compartidos en el informe.
- Pruebas parametrizadas: Describe claramente los parámetros para las pruebas parametrizadas para especificar diferentes escenarios.
- Archivos adjuntos: Captura automáticamente capturas de pantalla y otros archivos durante la ejecución de la prueba.
- Selección de pruebas: Usa un archivo de plan de pruebas para seleccionar qué pruebas ejecutar, lo que permite una ejecución flexible de las pruebas.
- Detalles del entorno: Incluye información completa del entorno para acompañar el informe de la prueba.
En la mayoría de los casos, Allure xUnit.net ofrece dos formas diferentes de usar una característica: la API de Atributos y la API en tiempo de ejecución.
API de Atributos: añade un atributo de C# a un método de prueba o a toda una clase para agregar ciertos datos al resultado de la prueba. Cuando usas este enfoque, se garantiza que los datos se añadirán independientemente de cómo se ejecute la prueba.
API en tiempo de ejecución: usa las funciones de Allure para agregar ciertos datos al resultado de la prueba durante su ejecución. Este enfoque permite construir los datos de forma dinámica.
Ten en cuenta que se recomienda llamar a las funciones de Allure lo más cerca posible del inicio de la prueba. De esta manera, los datos se agregarán incluso si la prueba falla temprano.
Especificar descripción, enlaces y otros metadatos
Hay muchos metadatos que puedes agregar a cada prueba para que aparezcan en el informe. Consulta la referencia para más detalles.
using Allure.Net.Commons;
using Allure.Xunit.Attributes;
using Xunit;
public class TestLabels
{
[Fact]
[AllureSeverity(SeverityLevel.critical)]
[AllureOwner("John Doe")]
[AllureLink("Website", "https://dev.example.com/")]
[AllureIssue("UI-123")]
[AllureTms("TMS-456")]
public void TestCreateLabel()
{
// ...
}
}using Allure.Net.Commons;
using Xunit;
public class TestLabels
{
[Fact]
public void TestCreateLabel()
{
AllureApi.SetSeverity(SeverityLevel.critical);
AllureApi.SetOwner("John Doe");
AllureApi.AddLink("Website", "https://dev.example.com/");
AllureApi.AddIssue("UI-123");
AllureApi.AddTmsItem("TMS-456");
// ...
}
}Organizar pruebas
Como se describe en Mejorar la navegación en tu informe de pruebas, Allure admite múltiples formas de organizar las pruebas en estructuras jerárquicas. Allure xUnit.net proporciona la API para asignar los campos relevantes a las pruebas ya sea añadiendo atributos o “dinámicamente” (igual que con los campos de metadatos).
Para especificar la ubicación de una prueba en la jerarquía basada en comportamientos:
using Allure.Xunit.Attributes;
using Xunit;
[AllureEpic("Web interface")]
[AllureFeature("Essential features")]
public class TestLabels
{
[Fact]
[AllureStory("Labels")]
public void TestCreateLabel()
{
// ...
}
}using Allure.Net.Commons;
using Xunit;
public class TestLabels
{
[Fact]
public void TestCreateLabel()
{
AllureApi.AddEpic("Web interface");
AllureApi.AddFeature("Essential features");
AllureApi.AddStory("Labels");
// ...
}
}Para especificar la ubicación de una prueba en la jerarquía basada en suites:
using Allure.Xunit.Attributes;
using Xunit;
[AllureParentSuite("Web interface")]
[AllureSuite("Essential features")]
public class TestLabels
{
[Fact]
[AllureSubSuite("Labels")]
public void TestCreateLabel()
{
// ...
}
}using Allure.Net.Commons;
using Xunit;
public class TestLabels
{
[Fact]
public void TestCreateLabel()
{
AllureApi.AddParentSuite("Web interface");
AllureApi.AddSuite("Essential features");
AllureApi.AddSubSuite("Labels");
// ...
}
}La ubicación de una prueba en la jerarquía basada en paquetes se define por los nombres completamente calificados de las clases en las que están declaradas, con los prefijos comunes mostrados como paquetes padres.
Distinguir entre estados de las pruebas
Cuando una prueba lanza una excepción, Allure xUnit.net refleja esto asignando un estado de prueba apropiado:
- Si la clase de la excepción pertenece al espacio de nombres
Xunit.Sdk, la prueba se considera Fallida. - Con cualquier otra excepción, la prueba se considera Rota.
Si deseas que tu prueba con excepciones no controladas sea Fallida en lugar de Rota, hay varios enfoques para lograrlo. Por ejemplo, en una afirmación (por ejemplo, en Assert.Equal), asegúrate de que evaluar los argumentos (por ejemplo, acceder a un elemento de una lista) no cause una excepción.
Alternativamente, considera envolver el código que puede lanzar en un bloque try..catch y fallar la prueba explícitamente.
using Xunit;
public class TestTryCatch
{
[Fact]
public void ThisTestWillBeFailed()
{
string value = GetValueOrFail();
Assert.Equal("foo", value);
}
static string GetValueOrFail()
{
string value = default;
try
{
value = GetValue();
}
catch (Exception e)
{
Assert.Fail(e.Message);
}
return value;
}
static string GetValue()
{
throw new Exception();
}
}using Xunit;
public class TestBroken
{
[Fact]
public void ThisTestWillBeBroken()
{
string value = GetValue();
Assert.Equal("foo", value);
}
static string GetValue()
{
throw new Exception();
}
}INFO
Cuando se lanza una excepción desde dentro de un paso, el estado del paso se selecciona según la configuración de allure.failExceptions.
Dividir una prueba en pasos
Allure xUnit.net proporciona tres formas de crear pasos y sub-pasos: “pasos basados en atributos”, “pasos lambda” y “pasos no-op”, consulta la referencia.
using Allure.Net.Commons;
using Allure.Xunit.Attributes.Steps;
using Xunit;
public class TestLabels
{
[Fact]
public void TestCreateLabel()
{
TestDomain("https://domain1.example.com/");
TestDomain("https://domain2.example.com/");
}
[AllureStep("Test {url}")]
private void TestDomain([Name("Webpage URL")] string url)
{
AllureLifecycle.Instance.UpdateStep(stepResult =>
stepResult.parameters.Add(
new Parameter {
name = "Started at",
value = DateTime.Now.ToString()
}
)
);
OpenBrowser();
GoToWebpage(url);
CloseBrowser();
}
[AllureStep("Open web browser")]
private void OpenBrowser()
{
// ...
}
[AllureStep("Visit {url}")]
private void GoToWebpage([Skip] string url)
{
// ...
}
[AllureStep("Close web browser")]
private void CloseBrowser()
{
// ...
}
}using Allure.Net.Commons;
using Xunit;
public class TestLabels
{
[Fact]
public void TestCreateLabel()
{
string[] urls =
{
"https://domain1.example.com/",
"https://domain2.example.com/"
};
foreach (string url in urls)
{
AllureApi.Step($"Test {url}", () =>
{
AllureLifecycle.Instance.UpdateStep(stepResult =>
{
stepResult.parameters.Add(
new Parameter { name = "Webpage URL", value = url }
);
});
AllureApi.Step("Opening web browser...");
// ...
AllureApi.Step($"Visiting {url}...");
// ...
AllureApi.Step("Closing web browser...");
// ...
});
}
}
}Describir los constructores y los métodos Dispose
Por defecto, un informe de prueba no incluye información sobre los constructores y métodos Dispose en las clases de prueba de xUnit.net. Para incluir esta información, agrega las anotaciones [AllureBefore] y [AllureAfter] a los métodos que configuran y limpian el contexto de la prueba.
Los métodos se mostrarán como tipos especiales de pasos.
using Allure.Xunit.Attributes.Steps;
using Xunit;
public class TestLabels : IDisposable
{
[AllureBefore("Setup test context")]
public TestLabels()
{
// ...
}
[Fact]
public void TestCreateLabel()
{
// ...
}
[AllureAfter("Clean test context")]
public void Dispose()
{
// ...
}
}Describir pruebas parametrizadas
Al utilizar el patrón de pruebas parametrizadas, usa el atributo [Theory] y otros atributos de xUnit.net o la función AddTestParameter(), consulta la referencia.
using Xunit;
public class TestLabels
{
[Theory]
[InlineData("johndoe", "qwerty")]
[InlineData("[email protected]", "qwerty")]
public void TestCreateLabel(string login, string password)
{
// ...
}
}using Allure.Net.Commons;
using Xunit;
public class TestLabels
{
[Fact]
public void TestAuthenticationWithUsername()
{
AllureApi.AddTestParameter("login", "johndoe");
AllureApi.AddTestParameter("password", "qwerty", ParameterMode.Masked);
// ...
}
[Fact]
public void TestAuthenticationWithEmail()
{
AllureApi.AddTestParameter("login", "[email protected]");
AllureApi.AddTestParameter("password", "qwerty", ParameterMode.Masked);
// ...
}
}Adjuntar capturas de pantalla y otros archivos
Puedes adjuntar cualquier tipo de archivo a tu informe de Allure. Por ejemplo, una forma popular de hacer que un informe sea más fácil de entender es adjuntar una captura de pantalla de la interfaz de usuario en un momento determinado.
Allure xUnit.net ofrece varias formas de crear un archivo adjunto, tanto a partir de archivos existentes como generados dinámicamente, consulta la referencia.
using System.IO;
using System.Text;
using Allure.Net.Commons;
using Xunit;
public class TestLabels
{
[Fact]
public void TestCreateLabel()
{
// ...
AllureApi.AddAttachment(
"data.txt",
"text/plain",
Encoding.UTF8.GetBytes("This is the file content.")
);
AllureApi.AddAttachment(
"image1.png",
"image/png",
File.ReadAllBytes("/path/to/image1.png")
);
AllureApi.AddAttachment(
"image2.png",
"image/png",
"/path/to/image2.png"
);
}
}Seleccionar pruebas a través de un archivo de plan de pruebas
Si la variable de entorno ALLURE_TESTPLAN_PATH está definida y apunta a un archivo existente, xUnit.net solo ejecutará las pruebas listadas en este archivo.
Aquí tienes un ejemplo de cómo ejecutar pruebas según un archivo llamado testplan.json:
export ALLURE_TESTPLAN_PATH=testplan.json
dotnet test$Env:ALLURE_TESTPLAN_PATH = "testplan.json"
dotnet testInformación del entorno
Para la página principal del informe, puedes recopilar varias informaciones sobre el entorno en el que se ejecutaron las pruebas.
Por ejemplo, es una buena idea usar esto para recordar la versión del sistema operativo y la versión de .NET. Esto puede ayudar al futuro lector a investigar errores que solo se reproducen en algunos entornos.
Para proporcionar la información del entorno, coloca un archivo llamado environment.properties en el directorio allure-results después de ejecutar las pruebas. Consulta el ejemplo en Archivo de entorno.
Ten en cuenta que esta función debe usarse para propiedades que no cambian para todas las pruebas en el informe. Si tienes propiedades que pueden ser diferentes para diferentes pruebas, considera usar Pruebas parametrizadas.