Entornos Allure 3

Allure Report 3 ofrece una nueva forma de organizar los resultados de pruebas por entornos, permitiéndote agrupar pruebas por sistemas operativos, navegadores, despliegues - o cualquier otra forma de categorización, y comparar resultados de diferentes entornos fácilmente.

Esta característica se basa en etiquetas de resultados de pruebas: puedes mapear ciertas etiquetas (o combinaciones de etiquetas) a un nombre de entorno específico, y Allure Report 3 dividirá todos los resultados de pruebas en la página de inicio del reporte en jerarquías separadas, entre las cuales puedes cambiar a través del menú desplegable Entornos.

Además, en la pestaña Entornos de cada resultado de prueba podrás ver los resultados disponibles de la misma prueba desde otros entornos.

Requisitos previos

• Esta característica requiere que uses un archivo de configuración dinámico (.mjs, .cjs, .js) para Allure Report 3.
• Debes establecer las etiquetas que almacenan información del entorno en el código de tus pruebas. Por favor, consulta la documentación del integración de framework que estés usando para saber cómo hacerlo.

Configuración básica

Los entornos están gobernados por el parámetro de configuración environments.

Las claves del objeto environments son IDs de entorno — identificadores cortos usados internamente (solo letras latinas, dígitos, guiones bajos y guiones, máximo 64 caracteres). Cada entrada requiere una función matcher y también acepta un campo opcional name para el nombre para mostrar en el reporte. Si se omite name, se usa el ID como nombre para mostrar.

Los ejemplos a continuación muestran cómo asignar entornos basándose en una sola etiqueta o múltiples etiquetas. Allure buscará etiquetas llamadas os y, en el ejemplo de dos etiquetas, browser, y asignará entornos en consecuencia:

Una etiqueta → Un entorno

{
  environments: {
    windows: {
      matcher: ({ labels }) =>
        labels.find(({ name, value }) => name === "os" && value === "Windows"),
    },
    macos: {
      matcher: ({ labels }) =>
        labels.find(({ name, value }) => name === "os" && value === "macOS"),
    },
    linux: {
      matcher: ({ labels }) =>
        labels.find(({ name, value }) => name === "os" && value === "Linux"),
    }
  }
}

Dos etiquetas → Un entorno

{
  environments: {
    "windows-chrome": {
        matcher: ({ labels }) =>
        labels.some(l => l.name === "os" && l.value === "Windows") &&
        labels.some(l => l.name === "browser" && l.value === "Chrome"),
    },
    "windows-firefox": {
        matcher: ({ labels }) =>
        labels.some(l => l.name === "os" && l.value === "Windows") &&
        labels.some(l => l.name === "browser" && l.value === "Firefox"),
    },
    "ubuntu-chrome": {
        matcher: ({ labels }) =>
        labels.some(l => l.name === "os" && l.value === "Ubuntu") &&
        labels.some(l => l.name === "browser" && l.value === "Chrome"),
    },
    "ubuntu-firefox": {
        matcher: ({ labels }) =>
        labels.some(l => l.name === "os" && l.value === "Ubuntu") &&
        labels.some(l => l.name === "browser" && l.value === "Firefox"),
    }
  }
}

Para establecer un nombre para mostrar diferente al ID, agrega el campo name:

{
  environments: {
    prod_env: {
      name: "Production",   // se muestra en el reporte; el ID "prod_env" se usa internamente
      matcher: ({ labels }) =>
        labels.find(({ name, value }) => name === "env" && value === "production"),
    },
  }
}

Las configuraciones anteriores resultan en menús de entorno como estos:

Cómo funcionan las funciones de coincidencia

• Allure lee archivos de resultados de pruebas y carga todas las labels de cada resultado de prueba.
• La función de coincidencia recibe { labels: TestLabel[] } del proceso de Allure Report. Cada etiqueta es { name: string, value: string }.
• Si el resultado de la prueba pertenece al entorno, la función de coincidencia devuelve true.
• La primera coincidencia gana - los resultados de pruebas no pueden ser asignados a múltiples entornos, por lo que el orden de los entornos en el archivo de configuración importa.
• Si Allure no puede hacer coincidir un resultado de prueba con ningún entorno, lo asigna al entorno default, para que no se pierdan resultados de pruebas.

Variables de entorno

Puedes agregar cualquier metadatos que se apliquen a todo el reporte a través del parámetro de configuración global variables. Allure los muestra en la parte superior de la página de inicio del reporte en la sección Variables.

Además de las variables globales, puedes establecer variables específicas de entorno, que pueden sobrescribir variables globales existentes, o mostrarse en addition a ellas, cuando seleccionas un entorno específico:

// Variables Globales vs Variables Específicas de Entorno
{
  variables: {
    "App Version": "2.5.1",            // Se muestra en todas partes
    "Build Number": "#1234",         // Se muestra en todas partes
    "Database": "prod-db-primary"      // Se muestra, a menos que se sobrescriba
  },
  environments: {
    staging: {
        matcher: ({ labels }) =>
        labels.some(({ name, value }) => name === "env" && value === "staging"),
        variables: {
            "Server": "staging.example.com", // Se muestra para staging
            "Database": "staging-db",        // Sobrescribe la variable global para staging
        }
    },
    production: {
        matcher: ({ labels }) =>
        labels.some(({ name, value }) => name === "env" && value === "production"),
        variables: {
            "Server": "api.example.com",     // Se muestra para production
        }
    }
  }
}

Forzar un único entorno

Cuando no necesitas el mapeo basado en etiquetas y ya sabes a qué entorno pertenece una ejecución, puedes usar la opción de configuración de nivel superior environment para asignar todos los resultados de pruebas a un ID de entorno directamente, omitiendo completamente la lógica del matcher:

export default {
  environment: "staging",
};

Esto es el equivalente en archivo de configuración de la bandera CLI --environment descrita a continuación. La bandera CLI tiene prioridad si ambas están establecidas.

Restricción de entornos válidos

La opción de configuración de nivel superior allowedEnvironments te permite declarar una lista de permisos explícita de IDs de entorno. Cualquier ID de entorno — del mapa environments, la sobrescritura environment, o los datos de resultados de pruebas — que no esté en la lista provoca un error de validación al inicio:

export default {
  allowedEnvironments: ["staging", "production", "windows", "macos"],
};

Usa esto para detectar configuraciones incorrectas de entorno de forma temprana, especialmente en proyectos donde el conjunto de entornos válidos es fijo.

Sobrescritura CLI y flujos de trabajo CI/CD

Allure CLI te permite sobrescribir la asignación de entorno para todo el lanzamiento de pruebas usando el comando envolvente allure run.

Usa --environment para especificar el entorno por su ID (la clave del config):

allure run --environment="<id_entorno>" -- <comando_prueba>

O usa --environment-name para especificarlo por su nombre para mostrar:

allure run --environment-name="<nombre_para_mostrar_del_entorno>" -- <comando_prueba>

--environment tiene prioridad sobre --environment-name si se proporcionan ambos. Ambos tienen prioridad sobre el valor environment del archivo de configuración.

Por ejemplo:

allure run --environment="prod_env" -- pnpm test
allure run --environment-name="Production" -- pnpm test

Su uso principal es ejecutar pruebas en múltiples entornos en flujos de trabajo CI/CD y crear reportes combinados con la ayuda de la funcionalidad de construcciones multietapa:

• Ejecutas tus pruebas en diferentes entornos y guardas cada ejecución como un archivo de volcado.
• Luego recopilas todos los archivos de volcado y construyes un único reporte multietapa a partir de ellos.
• Allure mapea los resultados de pruebas de todas las ejecuciones a sus entornos asignados y obtienes un reporte unificado bien estructurado, donde puedes ver y comparar fácilmente cómo se desempeñan tus pruebas en diferentes contextos.

A continuación se muestra un fragmento del flujo de trabajo de demostración de Allure Report 3 en GitHub, ilustrando esta idea.

jobs:
  test:
    name: Build
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
    runs-on: ${{ matrix.os }}

    steps:
      # ...
      # Pasos de configuración del entorno de prueba
      # ...

      - name: Test Project
        # Una ejecución completa de pruebas por sistema operativo guardada como archivo de volcado
        run: pnpm allure run --config=./allurerc.mjs --environment="${{ matrix.os }}" --dump="allure-results-${{ matrix.os }}" -- pnpm test

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v5
        with:
          name: allure-results-${{ matrix.os }}
          path: ./allure-results-${{ matrix.os }}.zip
          compression-level: 0

  report:
    runs-on: ubuntu-latest
    needs: test
    steps:
      # ...
      # Pasos de configuración del generador de reportes
      # ...

      # Obteniendo el archivo de volcado para la ejecución de pruebas en Ubuntu
      - name: Download allure results from Ubuntu
        uses: actions/download-artifact@v6
        with:
          name: allure-results-ubuntu-latest
          path: ./

      # Obteniendo el archivo de volcado para la ejecución de pruebas en macOS
      - name: Download allure results from macOS
        uses: actions/download-artifact@v6
        with:
          name: allure-results-macos-latest
          path: ./

      - name: Build report
        # Construyendo el reporte multietapa desde todos los archivos de volcado obtenidos
        run: pnpm allure generate --dump="allure-results-*.zip" --output=./allure-report

        # ...
        # Pasos de despliegue del reporte
        # ...

TIP

Aunque la opción --environment sobrescribe las reglas de mapeo de etiquetas en el archivo de configuración, aún recogerá cualquier variable especificada para el entorno que coincida con el que pasas. Esto significa que puedes definir variables de entorno en la configuración incluso cuando uses --environment para asignar entornos.

{
  environments: {
    staging: {
        // matcher redundante cuando se usa la bandera --environment
        variables: {
            "Server": "staging.example.com",
            "Database": "staging-db"
        }
    },
    production: {
        variables: {
            "Server": "api.example.com",
            "Database": "prod-db-primary"
        }
    }
  }
}

La antigua característica de entornos

Allure 3 aún admite agregar metadatos de entorno a un reporte usando el método heredado de Allure 2: si se descubre un archivo environment.properties en el directorio de resultados, Allure muestra los datos de este en la parte superior de la página del reporte en la sección Metadata.

Esto puede complementar o entrar en conflicto con tu configuración de entornos, así que asegúrate de deshacerte de este archivo, o de armonizarlo con tu nueva configuración de entornos - lo que mejor te convenga.