Introducción a las pruebas en Go

Genera reportes HTML atractivos usando Allure Report y tus pruebas en Go.

INFO

El paquete principal para el usuario es commons/gotest, que funciona con el paquete integrado testing de Go. Si estás creando tu propia integración para un runner personalizado o una librería auxiliar, utiliza commons en su lugar. Ambos paquetes se encuentran en el repositorio oficial allure-go, que también ofrece paquetes de aserciones compatibles con testify y helpers para evidencia HTTP.

Configuración

1. Prepara tu proyecto

1. Asegúrate de tener instalada una versión reciente de la herramienta Go.

   Los paquetes oficiales allure-go requieren Go 1.25 o superior.

2. Abre una terminal y ve al directorio del proyecto. Por ejemplo:

   cd /home/user/myproject

3. Instala Allure Report siguiendo la guía de instalación.

4. Añade la integración gotest:

   go get github.com/allure-framework/allure-go/commons/gotest

5. Envuelve tus pruebas con allure.Test. Dentro del cuerpo, utiliza el contexto proporcionado para declarar pasos, parámetros y adjuntos.

   package example_test
   
   import (
       "testing"
   
       allure "github.com/allure-framework/allure-go/commons/gotest"
   )
   
   func TestLogin(t *testing.T) {
       allure.Test(t, "inicia sesión con credenciales válidas", func(a *allure.Context) {
           a.Step("enviar credenciales", func(a *allure.Context) {
               a.Parameter("user", "alice")
               a.Attachment("request", []byte(`{"user":"alice"}`), "application/json")
           })
           session := allure.Step(a, "crear sesión", func(a *allure.Context) string {
               return "session-1"
           })
           a.Parameter("session", session)
       },
           allure.WithOwner("qa-team"),
           allure.WithDescription("Verifica que las credenciales válidas crean una sesión."),
       )
   }

2. Ejecuta las pruebas

Ejecuta tus pruebas como de costumbre:

go test ./...

Por defecto, la integración escribe los resultados en un directorio allure-results junto a cada paquete de prueba. Go ejecuta cada binario de prueba en el directorio fuente de su paquete, así que en un módulo con varios paquetes de prueba el valor relativo por defecto produce varios directorios allure-results.

Para recopilar todos los resultados en un solo lugar, establece ALLURE_RESULTS_DIR con una ruta absoluta antes de la ejecución de prueba:

ALLURE_RESULTS_DIR=$PWD/allure-results go test ./...

Si el directorio de resultados ya existe, los nuevos archivos se añaden a los existentes, de modo que un futuro reporte se basará en todos ellos.

3. Genera un reporte

Después de la ejecución de prueba, genera y abre el reporte con la CLI de Allure:

allure generate ./allure-results --output ./allure-report
allure open ./allure-report

Escribiendo pruebas

La integración de Allure para Go amplía la salida estándar de go test con funciones avanzadas de reporte. Puedes usarla para:

• añadir descripciones, responsables, enlaces y otros metadatos,
• organizar pruebas en jerarquías basadas en comportamiento y suites,
• dividir la ejecución en pasos anidados,
• describir parámetros y adjuntos,
• reportar aserciones de testify como pasos,
• adjuntar evidencia estructurada de tráfico HTTP,
• ejecutar solo pruebas seleccionadas mediante un archivo de plan de pruebas.

Añadir metadatos

Los metadatos que se conocen antes de ejecutar el cuerpo de la prueba se deben pasar como opciones estáticas allure.With..., ya que participan en el filtrado por plan de pruebas. Los metadatos descubiertos durante la ejecución pueden añadirse en tiempo de ejecución con métodos sobre el *allure.Context de la prueba:

func TestLogin(t *testing.T) {
    allure.Test(t, "Login funciona", func(a *allure.Context) {
        a.Label("layer", "web")
        a.Link("https://example.com/docs", "Documentación relacionada", "link")
    },
        allure.WithDescription("Esta prueba verifica el inicio de sesión con nombre de usuario y contraseña."),
        allure.WithOwner("John Doe"),
        allure.WithTag("smoke"),
        allure.WithSeverity("critical"),
        allure.WithAllureID("123"),
        allure.WithIssue("AUTH-123", "https://jira.example.com/browse/AUTH-123"),
        allure.WithTMS("TMS-456", "https://tms.example.com/cases/TMS-456"),
    )
}

Organizar pruebas

Allure admite jerarquías tanto basadas en comportamiento como en suites. Por ejemplo:

func TestLogin(t *testing.T) {
    allure.Test(t, "Login funciona", func(a *allure.Context) {
        // ...
    },
        allure.WithEpic("Web interface"),
        allure.WithFeature("Authentication"),
        allure.WithStory("Login with username and password"),

        allure.WithParentSuite("UI tests"),
        allure.WithSuite("Authentication"),
        allure.WithSubSuite("Positive scenarios"),
    )
}

Cuando no se establecen etiquetas de suite explícitamente, la integración las deriva automáticamente de la ruta del archivo de prueba relativa a la raíz del módulo. Establecer cualquiera de WithParentSuite, WithSuite o WithSubSuite (o las etiquetas equivalentes en tiempo de ejecución) reemplaza toda la jerarquía derivada.

Dividir una prueba en pasos

Usa a.Step para reportar un bloque de código como un paso. Los pasos pueden ser anidados:

func TestLogin(t *testing.T) {
    allure.Test(t, "Login funciona", func(a *allure.Context) {
        a.Step("Abrir página de login", func(a *allure.Context) {
            // ...
        })
        a.Step("Enviar credenciales", func(a *allure.Context) {
            a.Step("Rellenar el formulario", func(a *allure.Context) {
                // ...
            })
            a.Step("Hacer clic en el botón", func(a *allure.Context) {
                // ...
            })
        })
    })
}

Cuando un paso debe producir un valor, utiliza la función genérica a nivel de paquete allure.Step:

token := allure.Step(a, "Autorizar", func(a *allure.Context) string {
    return "token-123"
})

Un paso que produce un panic se reporta como roto con el mensaje y el stack trace; un paso en el que la prueba falla o es omitida se reporta con el estado correspondiente.

Añadir parámetros y adjuntos

Los parámetros y adjuntos se almacenan en los resultados generados por Allure y se muestran en el reporte:

func TestLogin(t *testing.T) {
    allure.Test(t, "Login funciona", func(a *allure.Context) {
        a.Parameter("browser", "firefox")
        a.Attachment(
            "request.json",
            []byte(`{"username":"demo","rememberMe":true}`),
            "application/json",
        )
        a.AttachmentPath("server log", "./testdata/server.log", "text/plain")
    }, allure.WithParameter("environment", "staging"))
}

Los adjuntos añadidos dentro de un paso se asocian a ese paso. La extensión del archivo almacenado se deriva automáticamente del tipo de contenido.

Reportar aserciones de testify como pasos

Si tus pruebas usan testify, reemplaza las importaciones de aserciones por los paquetes proxy de Allure del módulo separado github.com/allure-framework/allure-go/testify:

 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 mantienen la API exacta de testify. Pasa el contexto de Allure a en lugar de t para reportar cada aserción como un paso de Allure:

func TestProfile(t *testing.T) {
    allure.Test(t, "carga perfil", func(a *allure.Context) {
        assert.Equal(a, "alice", profile.Name)
        require.NoError(a, err)
        assert.New(a).Len(profile.Roles, 2)
    })
}

Las aserciones que aún reciben un *testing.T simple se comportan exactamente como testify original, sin reporte de pasos.

Adjuntar tráfico HTTP

Usa el paquete commons/httpexchange cuando las pruebas requieran evidencia estructurada de solicitudes y respuestas. Para capturar solicitudes realizadas por un cliente HTTP, envuelve su transport:

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

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

Para capturar solicitudes recibidas por un servicio falso httptest.Server, envuelve su handler:

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

Cada intercambio capturado se convierte en un adjunto en el formato HTTP Exchange de Allure, mostrando el método, URL, cabeceras, cookies, parámetros de consulta, estado y cuerpos. Credenciales comunes como cabeceras Authorization, cookies y parámetros de consulta tipo token se ocultan por defecto. Consulta la Referencia para las opciones disponibles.

Seleccionar pruebas mediante un archivo de plan de pruebas

La integración admite el mecanismo estándar de plan de pruebas de Allure mediante la variable de entorno ALLURE_TESTPLAN_PATH.

Crea un archivo JSON como:

{
  "version": "1.0",
  "tests": [
    { "id": "123" },
    { "selector": "example/login_test.go/TestLogin/logs_in_with_valid_credentials" }
  ]
}

Luego ejecuta las pruebas con:

ALLURE_TESTPLAN_PATH=./testplan.json go test ./...

Las entradas con id coinciden con pruebas que declaran un Allure ID, por ejemplo mediante allure.WithAllureID("123"). Las entradas con selector coinciden con el nombre completo de la prueba, que consiste en la ruta del archivo de prueba relativa a la raíz del módulo y el nombre completo de la prueba en Go. Las pruebas no seleccionadas por el plan se omiten antes de ejecutar su cuerpo.

Crear una integración personalizada

Si necesitas integrar Allure con un framework de pruebas personalizado en Go o una librería auxiliar, utiliza el módulo commons:

go get github.com/allure-framework/allure-go/commons

Las librerías auxiliares que se ejecutan dentro de una prueba activa de Allure solo necesitan un context.Context y el facade de commons — las llamadas no hacen nada si no hay una prueba activa:

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

func instrument(ctx context.Context) {
    _ = commons.Step(ctx, "llamar endpoint de login", func(ctx context.Context) error {
        return commons.Attachment(ctx, "payload", []byte(`{"ok":true}`), commons.AttachmentOptions{
            ContentType: "application/json",
        })
    })
}

Los adaptadores que gestionan el ciclo de vida de la prueba por sí mismos utilizan además los paquetes runtime, writer, model y testplan. Consulta la Referencia para las funciones y opciones principales, o Configuración para las variables de entorno soportadas.