Referencia de pruebas en Go

Estos son los principales componentes que puedes usar para integrar pruebas en Go con Allure utilizando el paquete github.com/allure-framework/allure-go/commons/gotest. Importe el paquete bajo el alias allure:

import allure "github.com/allure-framework/allure-go/commons/gotest"

Funciones de prueba

allure.Test

allure.Test(t, name, body, options...) reporta un resultado de prueba de Allure con nombre. Crea un subtest de Go mediante t.Run(name, ...), por lo que los fallos, omisiones, logs, limpiezas, pasos y adjuntos quedan asociados al resultado correcto, y el filtrado estándar go test -run sigue funcionando:

func TestLogin(t *testing.T) {
    allure.Test(t, "logs in with valid credentials", func(a *allure.Context) {
        // ...
    }, allure.WithOwner("qa-team"))
}

Una función de prueba en Go puede contener múltiples llamadas a allure.Test; cada una produce un resultado de Allure separado.

allure.Wrap

allure.Wrap(t, body, options...) reporta la prueba actual de Go como exactamente un resultado de Allure. Utiliza t.Name() como nombre del resultado y no crea un subtest hijo:

func TestLogin(t *testing.T) {
    allure.Wrap(t, func(a *allure.Context) {
        // ...
    })
}

allure.Wrap solo puede llamarse una vez por prueba y no puede combinarse con allure.Test en el mismo *testing.T — usa allure.Test cuando una prueba de Go debe producir varios resultados de Allure con nombre.

allure.Step

La función genérica a nivel de paquete allure.Step(a, name, body) reporta un paso cuyo cuerpo retorna un valor tipado:

session := allure.Step(a, "create session", func(a *allure.Context) string {
    return "session-1"
})

Para pasos sin valor de retorno, utiliza el método a.Step.

Estados

El estado reportado de la prueba sigue el resultado de la prueba en Go: passed, failed (tras t.Error, t.Fatal o una aserción fallida), o skipped (tras t.Skip). Un panic en el cuerpo de la prueba se reporta como broken con el mensaje y el stack trace del panic, y luego se vuelve a lanzar para que go test lo maneje como de costumbre.

Opciones estáticas

Las opciones se pasan como argumentos finales a allure.Test y allure.Wrap. Se aplican antes de ejecutar el cuerpo de la prueba, lo que las hace visibles para el filtrado por plan de pruebas. Prefiere las opciones para metadatos conocidos de antemano; usa la API de contexto en tiempo de ejecución para metadatos descubiertos durante la ejecución.

Etiquetas

• allure.WithLabel(name, value)
• allure.WithLabels(labels...) — acepta valores model.Label
• allure.WithTag(value)
• allure.WithSeverity(value)
• allure.WithOwner(value)
• allure.WithAllureID(id)

Jerarquías

• allure.WithEpic(value)
• allure.WithFeature(value)
• allure.WithStory(value)
• allure.WithParentSuite(value)
• allure.WithSuite(value)
• allure.WithSubSuite(value)
• allure.WithPackage(value)

Configurar cualquiera de las etiquetas parentSuite, suite o subSuite desactiva la jerarquía automática de suites derivada de la ruta del archivo de prueba.

Enlaces

• allure.WithLink(url, name, linkType)
• allure.WithLinks(links...) — acepta valores model.Link
• allure.WithIssue(name, url)
• allure.WithTMS(name, url)

Parámetros

• allure.WithParameter(name, value)
• allure.WithParameterOptions(name, value, options)

allure.ParameterOptions controla la visualización y el comportamiento del historial:

allure.WithParameterOptions("password", "qwerty", allure.ParameterOptions{
    Excluded: true,                      // no afecta el ID de historial
    Mode:     model.ParameterModeMasked, // model.ParameterModeDefault, Masked o Hidden
})

Descripciones e identidad

• allure.WithDescription(markdown)
• allure.WithDescriptionHTML(html)
• allure.WithDisplayName(name) — sobrescribe el nombre mostrado en el reporte
• allure.WithTestCaseName(name) — establece el nombre lógico del caso de prueba
• allure.WithTestCaseID(id) — sobrescribe el ID de caso de prueba calculado
• allure.WithHistoryID(id) — sobrescribe el ID de historial calculado

Plan de pruebas

• allure.WithTestPlan(plan) — utiliza un *testplan.Plan ya cargado en vez de ALLURE_TESTPLAN_PATH
• allure.WithTestPlanPath(path) — carga un plan de pruebas desde un archivo específico

Avanzado

• allure.WithWriter(writer) — dirige los artefactos de esta prueba a un writer.Writer personalizado, por ejemplo un writer en memoria en pruebas de adaptadores
• allure.WithClock(now) — reemplaza la fuente de timestamp en milisegundos
• allure.WithIDGenerator(newID) — reemplaza el generador de UUID

API de contexto en tiempo de ejecución

El cuerpo de la prueba recibe un *allure.Context (llamado a por convención) que combina acceso al *testing.T subyacente con métodos de reporte de Allure.

Puente a testing.T

• a.T() — el *testing.T subyacente
• a.Name() — el nombre actual de la prueba en Go
• a.Helper() — marca el llamador como helper de prueba
• a.Errorf(format, args...) — falla la prueba y registra el mensaje como detalles de estado de Allure
• a.Fatal(args...), a.Fatalf(format, args...) — falla la prueba con detalles de estado y detiene la ejecución
• a.FailNow() — falla y detiene sin mensaje
• a.Context() — el context.Context que lleva el estado activo de Allure; pásalo a librerías auxiliares como httpexchange

Los mensajes de fallo reportados mediante a.Errorf, a.Fatal y a.Fatalf aparecen como detalles de estado del resultado en el reporte. Las llamadas hechas directamente sobre a.T() siguen fallando la prueba correctamente pero no registran detalles de estado.

Pasos

• a.Step(name, body) — reporta body como un paso; los pasos se anidan naturalmente
• a.StepDisplayName(name) — renombra el paso activo
• a.StepParameter(name, value) — agrega un parámetro al paso activo
• a.StepDescription(markdown), a.StepDescriptionHTML(html) — establece la descripción del paso activo

a.Step("submit credentials", func(a *allure.Context) {
    a.StepParameter("endpoint", "/login")
    a.Step("wait for redirect", func(a *allure.Context) {
        // ...
    })
})

Metadatos

• a.Label(name, value)
• a.Link(url, name, linkType)
• a.Parameter(name, value)
• a.Description(markdown), a.DescriptionHTML(html)
• a.DisplayName(name)
• a.TestCaseName(name), a.TestCaseID(id), a.HistoryID(id)

Estos son los equivalentes en tiempo de ejecución de las opciones estáticas. Ten en cuenta que los metadatos en tiempo de ejecución se aplican después del filtrado por plan de pruebas, por lo que un Allure ID necesario para la selección debe establecerse con allure.WithAllureID.

Adjuntos

• a.Attachment(name, content, contentType) — adjunta bytes en memoria
• a.AttachmentPath(name, path, contentType) — adjunta un archivo existente

Los adjuntos se agregan al paso activo, o a la prueba misma cuando no hay un paso activo. Para adjuntos en memoria, la extensión del archivo almacenado se deriva del tipo de contenido (por ejemplo, application/json produce un archivo .json); los adjuntos de archivo mantienen la extensión del archivo fuente.

Diagnósticos a nivel de ejecución

• a.GlobalAttachment(name, content, contentType), a.GlobalAttachmentPath(name, path, contentType) — adjunta evidencia a la ejecución de prueba completa en vez de a una sola prueba, por ejemplo un log de servicio recolectado una vez por ejecución
• a.GlobalError(details) — registra un error a nivel de ejecución, aceptando un valor model.StatusDetails

Aserciones de Testify

El módulo separado github.com/allure-framework/allure-go/testify proporciona reemplazos directos para los paquetes assert y require de testify que reportan cada llamada de aserción como un paso de Allure:

go get github.com/allure-framework/allure-go/testify/assert
go get github.com/allure-framework/allure-go/testify/require

 import (
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
+	"github.com/allure-framework/allure-go/testify/assert"
+	"github.com/allure-framework/allure-go/testify/require"
 )

Los paquetes proxy reflejan la API original de testify, incluyendo los objetos de aserción assert.New(...) / require.New(...). Lo que se reporta depende del primer argumento de cada llamada:

• pasar el contexto de Allure a reporta la aserción como un paso de Allure; las aserciones fallidas agregan detalles de estado, incluyendo los valores esperado y actual,
• pasar t o a.T() mantiene el comportamiento estándar de testify sin reporte de pasos.

allure.Test(t, "loads profile", func(a *allure.Context) {
    assert.Equal(a, "alice", profile.Name) // reportado como paso
    require.NoError(a, err)                // reportado como paso
    assert.Equal(t, "alice", profile.Name) // testify estándar, sin paso
})

Los tipos de contexto de prueba de otras integraciones pueden optar por el reporte de pasos si implementan la interfaz TestingT de testify y la interfaz commons.ContextProvider (un método Context() context.Context).

Adjuntos de intercambio HTTP

El paquete github.com/allure-framework/allure-go/commons/httpexchange produce adjuntos en el formato Allure HTTP Exchange (application/vnd.allure.http+json, almacenados con la extensión .httpexchange), que los visores de reportes muestran como evidencia estructurada de solicitud/respuesta.

Helpers de captura

• httpexchange.NewTransport(ctx, base, options...) — envuelve un http.RoundTripper; cada solicitud enviada por el cliente se adjunta a la prueba o paso activo
• httpexchange.NewHandler(ctx, next, options...) — envuelve un http.Handler; cada solicitud recibida por el servidor se adjunta, lo que es útil para fakes tipo httptest.Server

client := &http.Client{
    Transport: httpexchange.NewTransport(a.Context(), http.DefaultTransport),
}

server := httptest.NewServer(httpexchange.NewHandler(a.Context(), handler))

Ambos toman el contexto de Allure desde a.Context() y no hacen nada de forma segura cuando no hay una prueba de Allure activa.

Construcción manual de intercambios

Cuando los bytes del cuerpo ya han sido capturados por tu propio código:

• httpexchange.NewExchange(req, requestBody, resp, responseBody, options...) — construye un intercambio completo a partir de valores *http.Request y *http.Response
• httpexchange.FromRequest(req, body, options...), httpexchange.FromResponse(resp, body, options...) — construyen la parte de solicitud o respuesta por separado
• httpexchange.Attach(ctx, name, exchange) — adjunta un intercambio a la prueba o paso activo
• httpexchange.Marshal(exchange) — serializa un intercambio a JSON sin adjuntarlo

Opciones

• httpexchange.WithBodyLimit(limit) — limita los valores de cuerpo capturados, 64 KiB por defecto; un límite negativo captura todo, cero registra metadatos del cuerpo sin contenido
• httpexchange.WithRedactedHeaders(names...) — agrega nombres de encabezado a redactar; por defecto se redactan Authorization, Proxy-Authorization, Cookie, Set-Cookie, X-Api-Key y X-Auth-Token
• httpexchange.WithRedactedQueryParameters(names...) — agrega parámetros de consulta a redactar; nombres comunes tipo token como token, password, api_key y client_secret se redactan por defecto
• httpexchange.WithRedactedFormFields(names...) — agrega campos de formulario URL-encoded a redactar; se aplican los mismos valores por defecto tipo token
• httpexchange.WithRedactedCookies(names...) — agrega nombres de cookie a redactar; por defecto, se redactan todos los valores de cookie
• httpexchange.WithAttachmentName(name) / httpexchange.WithAttachmentNamer(func) — establece un nombre de adjunto fijo o calculado; el valor por defecto es HTTP <method> <path-and-query>, por ejemplo HTTP GET /orders?page=2
• httpexchange.WithStartStop(start, stop) — establece timestamps explícitos del intercambio en milisegundos de época Unix
• httpexchange.WithError(err) / httpexchange.WithErrorDetails(name, message, stack) — registra un error a nivel de transporte en el intercambio

Los valores redactados se reemplazan por el marcador __ALLURE_REDACTED__, que los visores de reportes muestran como indicador de redacción.

Construyendo una integración personalizada con commons

Utiliza el módulo github.com/allure-framework/allure-go/commons cuando necesites integrar Allure con un sistema de pruebas personalizado, o escribir una librería auxiliar que reporte en cualquier prueba de Allure que esté activa.

Las librerías auxiliares solo necesitan las funciones fachada, que reflejan la API de contexto en tiempo de ejecución pero aceptan un context.Context y retornan errores. Todas ellas no hacen nada de forma segura cuando no hay un runtime de Allure vinculado al contexto:

import commons "github.com/allure-framework/allure-go/commons"

func instrument(ctx context.Context) error {
    if err := commons.Owner(ctx, "qa-team"); err != nil {
        return err
    }
    return commons.Step(ctx, "call login endpoint", func(ctx context.Context) error {
        return commons.Attachment(ctx, "payload", []byte(`{"ok":true}`), commons.AttachmentOptions{
            ContentType: "application/json",
        })
    })
}

Los principales grupos de funciones fachada son:

• etiquetas y enlaces: Label, Labels, Tag, Severity, Owner, Epic, Feature, Story, ParentSuite, Suite, SubSuite, Package, AllureID, Link, Links, Issue, TMS
• metadatos de prueba: Parameter, ParameterWithOptions, Description, DescriptionHTML, DisplayName, TestCaseName, TestCaseID, HistoryID
• pasos: Step, StepValue (retorna un valor tipado), StartStep, StopStep, LogStep (registra un paso ya completado), StepDisplayName, StepParameter, StepParameterWithOptions, StepDescription, StepDescriptionHTML
• adjuntos y diagnósticos: Attachment, AttachmentPath, GlobalAttachment, GlobalAttachmentPath, GlobalError

Los adaptadores que gestionan el ciclo de vida de la prueba por sí mismos se basan en los subpaquetes de bajo nivel:

• commons/runtime — el puente de mensajes vinculado al contexto; vincula la propiedad con runtime.WithRuntime, runtime.WithTest, runtime.WithFixture y runtime.WithStep
• commons/writer — persistencia de resultados: NewFileSystemWriter para directorios allure-results, NewInMemoryWriter para pruebas, NewMultiWriter para distribuir
• commons/model — los tipos serializables de resultado de Allure (TestResult, StepResult, Label, Link, Parameter, Status, StatusDetails y otros)
• commons/testplan — carga y coincidencia de plan de pruebas: LoadFromEnv, LoadFile, Parse, Includes
• commons/ids — helpers de identidad estable: New, TestCaseID, HistoryID
• commons/clock — helpers de timestamp en milisegundos de época Unix
• commons/lifecycle — interfaces de ciclo de vida y hooks de eventos para autores de adaptadores