Quality Gate Allure 3

Quality Gate es una característica integrada de Allure Report 3 que te permite aplicar un estándar de calidad en tu proyecto, típicamente cuando está a punto de avanzar de una etapa de despliegue a otra. Esta característica falla una ejecución de pruebas si viola el conjunto de reglas definido, evitando así el despliegue de un proyecto que no cumple con el estándar de calidad deseado.

Actualmente, Allure Report tiene 4 reglas incorporadas que puedes usar:

Nombre de regla	Descripción de regla	Nombre de función de regla	Unidades
`maxFailures`	Número máximo permitido de pruebas fallidas (excluye problemas conocidos)	`maxFailuresRule`	Número de pruebas
`minTestsCount`	Número mínimo requerido de pruebas ejecutadas	`minTestsCountRule`	Número de pruebas
`successRate`	Tasa de éxito mínima requerida para pruebas (excluye problemas conocidos)	`successRateRule`	Ratio (0.0 a 1.0)
`maxDuration`	Duración máxima permitida para cualquier prueba individual	`maxDurationRule`	Milisegundos

También puedes usar reglas de terceros y escribir reglas completamente personalizadas tú mismo.

Configuración Básica

Reglas Incorporadas

Como otras características avanzadas, puedes configurar Quality Gate en el archivo de configuración de tiempo de ejecución.

Dependiendo del formato, agrega estas líneas a él:

allurerc.mjsallurerc.jsonallurerc.yaml

javascript

import { defineConfig } from "allure";

export default defineConfig({
  qualityGate: {
    rules: [
      {
        <nombre-de-regla>: <valor-esperado>,
      },
    ],
 },
})

json

{
  "qualityGate": {
    "rules": [
      {
        "<nombre-de-regla>": "<valor-esperado>"
      }
    ]
  }
}

yaml

qualityGate:
  rules:
    - <nombre-de-regla>: <valor-esperado>

¿Qué formato de configuración usar?

Generalmente, si solo usas las reglas incorporadas sin ninguna lógica adicional aplicada, puedes apegarte a archivos de configuración estáticos .json o .yaml. Si quieres personalizar cualquier cosa, aplicar filtros adicionales a los resultados de prueba analizados, o usar cualquier regla personalizada, necesitas la configuración dinámica .mjs o .js, ya que estarás agregando código ejecutable a ella.

Por ejemplo:

import { defineConfig } from "allure";

export default defineConfig({
  qualityGate: {
    rules: [
      {
        maxFailures: 5,
        minTestsCount: 30,
        // código ejecutable que valida solo resultados de prueba con etiqueta de severidad crítica
        filter: (tr) =>
          tr.labels.some((label) => label.name === "severity" && label.value === "critical"),
      },
    ],
  },
});

Si cualquiera de las reglas maxFailures y minTestsCount que configuraste aquí fallan, tu ejecución se completará con código de salida 1, Quality Gate imprimirá un mensaje reportando qué regla falló en la consola, y verás el código de salida en el reporte HTML generado de la ejecución de prueba.

Fallo de Allure Quality Gate

Si ninguna regla de Quality Gate falla, el código de salida será 0, y el estado del reporte es pasado.

Fast Fail

Si quieres terminar la ejecución de prueba inmediatamente cuando al menos una regla de Quality Gate falla – agrega la propiedad fastFail al conjunto de reglas:

import { defineConfig } from "allure";

export default defineConfig({
  qualityGate: {
    rules: [
      {
        maxFailures: 5,
        fastFail: true,
      },
    ],
  },
});

No todas las reglas tienen sentido con fastFail. No recomendamos habilitar fastFail en conjuntos de reglas que incluyen reglas como minTestsCount y successRate, porque los valores que verifican solo pueden calcularse correctamente después de que se reciban todos los resultados de las pruebas, es decir, después de que la ejecución de pruebas ya haya terminado. Si deseas usar estas reglas, recomendamos moverlas a un nuevo conjunto de reglas (ver abajo) con fastFail establecido en false.

Múltiples Conjuntos de Reglas

También puedes definir múltiples conjuntos de reglas de Quality Gate. Esto puede ser útil cuando quieres separar las reglas de fallo rápido de todas las demás:

import { defineConfig } from "allure";

export default defineConfig({
  qualityGate: {
    rules: [
      {
        // usa el campo id para hacer las reglas del conjunto más fáciles de identificar
        id: "conjunto de fallo rápido",
        maxFailures: 5,
        fastFail: true,
      },
      {
        id: "conjunto sin fallo rápido",
        successRate: 0.95,
      },
    ],
  },
});

Ejecutar Allure con Quality Gates Habilitados

Hay tres comandos CLI de Allure que aplican quality gates:

allure run - aplica los quality gates marcados con fastFail a medida que avanza la ejecución de pruebas y verifica si debe terminarse anticipadamente; una vez que la ejecución de pruebas finaliza, aplica todos los quality gates a los resultados de prueba finales.
allure generate - aplica los quality gates contra todos los resultados de prueba de todos los directorios coincidentes antes de que se generen los reportes.
allure quality-gate - aplica los quality gates contra todos los resultados de prueba de todos los directorios coincidentes. No genera reportes.

TIP

En este momento Quality Gate no es compatible con reintentos. allure run --rerun 3 -- <comando de prueba> no funcionará si tienes quality gate habilitado en tu configuración de Allure 3.

allure run y allure generate siempre usan las reglas especificadas en el archivo de configuración.

allure quality-gate usa la configuración por defecto, pero también permite definir las reglas a través del CLI usando estas opciones:

--max-failures
--min-tests-count
--success-rate

Por ejemplo:

bash

allure quality-gate --max-failures 5

Si se usa cualquiera de estas, el archivo de configuración es ignorado y las reglas del comando CLI se usan en su lugar.

Configuración Avanzada

Las características en esta sección requieren archivos de configuración dinámicos (.mjs/.js) que pueden ejecutar código JavaScript.

Filtros Personalizados

Puedes aplicar lógica de filtrado personalizada a los resultados de prueba que Quality Gate analiza.

El segundo conjunto de reglas en el ejemplo a continuación valida solo resultados de prueba con etiqueta de severidad crítica: si alguna prueba de este tipo falla, toda la ejecución falla inmediatamente, porque fastFail está establecido en true para este conjunto de reglas.

import { defineConfig } from "allure";

export default defineConfig({
  qualityGate: {
    rules: [
      // el primer conjunto de reglas permite tener hasta 10 pruebas fallidas en total, no fallará en tiempo de ejecución y reportará el resultado de validación al final
      {
        id: "primer-conjunto",
        maxFailures: 10,
      },
      // el segundo conjunto de reglas falla inmediatamente si hay al menos un fallo de prueba crítico
      {
        id: "segundo-conjunto",
        maxFailures: 0,
        fastFail: true,
        // valida solo resultados de prueba con etiqueta de severidad crítica
        filter: (tr) =>
          tr.labels.some((label) => label.name === "severity" && label.value === "critical"),
      },
    ],
  },
});

Campo `use`

El arreglo use en la configuración de Allure 3 es una lista de implementaciones de reglas, donde cada implementación es un objeto que define cómo funciona una regla específica.

La lista predeterminada incluye las implementaciones de todas las reglas incorporadas, por lo que si solo las estás usando, como en los ejemplos de la sección Configuración Básica, puedes omitirlo.

Pero cuando necesites introducir una regla personalizada o modificar una existente, debes proporcionar tu propia lista, y esta lista debe incluir las implementaciones de todas las reglas mencionadas en tus conjuntos de reglas - tanto predeterminadas como personalizadas.

Debes importar las implementaciones de reglas incorporadas desde @allurereport/core, y las implementaciones de reglas personalizadas desde los paquetes o archivos que las contengan:

import { maxFailuresRule } from "@allurereport/core";
import { defineConfig } from "allure";
import { ruleImplementation1, ruleImplementation2 } from "custom-rules";

export default defineConfig({
  qualityGate: {
    rules: [
      {
        maxFailures: 5,
        rule1: 1,
        rule2: 2,
      },
    ],
    use: [
      maxFailuresRule, // implementa maxFailures, que es incorporada, pero aún tienes que listarla, porque también estás usando reglas personalizadas
      ruleImplementation1, // implementa la regla personalizada rule1
      ruleImplementation2, // implementa la regla personalizada rule2
    ],
  },
});

Personalizar el Mensaje de una Regla

Si una regla falla, Allure imprime un mensaje en la consola. Puedes personalizar este mensaje a tu gusto redefiniendo la función message en el arreglo use de la configuración de Quality Gate.

import { maxFailuresRule } from "@allurereport/core";
import { defineConfig } from "allure";

export default defineConfig({
  qualityGate: {
    rules: [
      {
        maxFailures: 5,
      },
    ],
    use: [
      {
        // no olvides usar el operador rest spread para mantener intactos los demás campos de la regla
        ...maxFailuresRule,
        message: ({ expected, actual }) =>
          `Mensaje personalizado: esperado ${expected}, obtenido ${actual}`,
      },
    ],
  },
});

Usar Reglas Externas

Puedes usar reglas de Quality Gate de terceros:

instala el paquete con la regla en tu proyecto
importa las reglas del paquete
proporciónalas al campo use en la configuración de quality gate:

import { defineConfig } from "allure";
import { rule1, rule2 } from "custom-rules-package";

export default defineConfig({
  qualityGate: {
    rules: [
      // define conjuntos de reglas según la firma de las reglas externas
    ],
    use: [rule1, rule2],
  },
});

TIP

Si quieres usar reglas predeterminadas y externas juntas, asegúrate de importar las reglas predeterminadas del paquete allure/rules e incluirlas en el arreglo use también:

import { defineConfig } from "allure";
// importa reglas predeterminadas de una vez
import { qualityGateDefaultRules } from "allure/rules";
// o impórtalas por separado
import { maxDurationRule, maxFailuresRule, minTestsCountRule, successRateRule } from "allure/rules";
import { rule1, rule2 } from "custom-rules-package";

export default defineConfig({
  qualityGate: {
    rules: [
      // define conjuntos de reglas según la firma de las reglas externas
    ],
    use: [...qualityGateDefaultRules, rule1, rule2],
  },
});

Si no reasignas el campo use, Allure usará solo las reglas predeterminadas automáticamente sin importaciones adicionales.

Crear Reglas Personalizadas

Puedes crear tus propias reglas de quality gate implementando la interfaz QualityGateRule<T,K=T>, donde T es el tipo del valor que la regla está verificando, y K es el tipo del resultado intermedio que la regla está usando para mantener el estado entre los lotes de resultados de pruebas que procesa.

WARNING

Si estás usando TypeScript, ¡asegúrate de compilar tu archivo de regla personalizada antes de usarlo! Allure no soporta la compilación de TypeScript al vuelo.

Así es como se define la regla integrada maxFailures en el código de Allure Report:

TypeScriptJavaScript

import { filterUnsuccessful } from "@allurereport/core-api";
import { type QualityGateRule } from "@allurereport/plugin-api";

export const maxFailuresRule: QualityGateRule<number> = {
  rule: "maxFailures",
  message: ({ actual, expected }) =>
    `The number of failed tests ${String(actual)} exceeds the allowed threshold value ${String(expected)}`,
  validate: async ({ trs, knownIssues, expected, state }) => {
    const knownIssuesHistoryIds = knownIssues.map(({ historyId }) => historyId);
    const unknown = trs.filter(
      (tr) => !tr.historyId || !knownIssuesHistoryIds.includes(tr.historyId),
    );
    const failedTrs = unknown.filter(filterUnsuccessful);
    const actual = failedTrs.length + (state.getResult() ?? 0);
    state.setResult(actual);
    return {
      success: actual <= expected,
      actual,
    };
  },
};

import { filterUnsuccessful } from "@allurereport/core-api";

export const maxFailuresRule = {
  rule: "maxFailures",
  message: ({ actual, expected }) =>
    `The number of failed tests ${String(actual)} exceeds the allowed threshold value ${String(expected)}`,
  validate: async ({ trs, knownIssues, expected, state }) => {
    const knownIssuesHistoryIds = knownIssues.map(({ historyId }) => historyId);
    const unknown = trs.filter(
      (tr) => !tr.historyId || !knownIssuesHistoryIds.includes(tr.historyId),
    );
    const failedTrs = unknown.filter(filterUnsuccessful);
    const actual = failedTrs.length + (state.getResult() ?? 0);
    state.setResult(actual);
    return {
      success: actual <= expected,
      actual,
    };
  },
};

El objeto de regla contiene los siguientes campos:

rule – el nombre de la regla que se usa para identificar la regla en el archivo de configuración; también se usa en el mensaje de error de validación impreso en la consola si la regla falla

message – función que renderiza el mensaje de error de validación; puede ser redefinida en el archivo de configuración:

recibe un objeto con los siguientes campos:
- actual: el valor real calculado por la función validate.
- expected: el valor esperado configurado en el conjunto de reglas.
debe retornar una cadena de texto para mostrar.

validate – función de validación que implementa la lógica de validación:

recibe un objeto con los siguientes campos:
- trs: un arreglo de resultados de prueba. Estos pueden ser todos los resultados de prueba producidos en la ejecución o solo una porción de ellos, es decir, un lote.
- knownIssues: un arreglo de objetos de problemas conocidos. Cada objeto tiene el campo historyId. Usualmente, querrás que la regla ignore los resultados de prueba con historyId que coincida con uno de los problemas conocidos.
- expected: el valor esperado de tipo T configurado en el conjunto de reglas.
- state: un objeto que mantiene el estado a través de múltiples llamadas a validate contra diferentes lotes de resultados de prueba. Ver un ejemplo más abajo.
debe retornar una promesa que se resuelve a un objeto con los siguientes campos:
- success: el resultado de la validación (true o false).
- actual: el valor calculado que la regla ha verificado.

Para crear una regla personalizada, define un objeto con la estructura descrita anteriormente.

`state` y Lógica de Fast Fail

Allure Report aplica las reglas de quality gate de dos maneras diferentes:

cuando la ejecución de pruebas se completa sin activar fast fail, y todos los resultados de prueba están listos: Allure simplemente aplica todas las reglas de quality gate al conjunto completo de resultados.
mientras la ejecución de pruebas está en progreso: Allure recibe lotes de resultados de prueba del framework de pruebas a medida que avanza sobre las pruebas y los verifica contra las reglas de quality gate de los conjuntos fastFail. Si se viola una regla de un conjunto fastFail, Allure termina la ejecución de pruebas y agrega datos de diagnóstico al reporte.

Algunas reglas funcionan de la misma manera en ambos contextos. Por ejemplo, puedes definir una regla que verifique que todos los bloqueadores pasen: tal regla evalúa los resultados de prueba uno por uno y está bien definida contra cualquier subconjunto de los resultados de prueba.

Otras reglas, por otro lado, dependen de algún estado que debe persistir a través de los lotes de resultados de prueba. La regla incorporada maxFailures mostrada arriba es un buen ejemplo: con fastFail habilitado debe contar las pruebas fallidas a medida que aparecen durante toda la duración de la ejecución. Tales reglas deben usar el objeto state que se pasa en la función validate:

import type { QualityGateRule } from "allure/rules";

export const myRule: QualityGateRule<number> = {
  rule: "myRule",
  message: ({ expected, actual }) =>
    `La regla personalizada ha fallado. Esperado: ${expected} no es igual a ${actual}`,
  validate: async ({ trs, expected, state }) => {
    // no hay valor inicial en el estado, así que usamos 0 como respaldo
    const previous = state.getResult() ?? 0;
    const actual = previous + trs.length;

    state.setResult(actual);

    return {
      success: actual === expected,
      actual,
    };
  },
};

Importar y Habilitar Regla Personalizada

Luego importa la regla al archivo de configuración, agrégala a la lista use, junto con la regla predeterminada que también quieres usar:

import { maxFailuresRule } from "@allurereport/core";
import { defineConfig } from "allure";
import { myRule } from "./myRule.js";

export default defineConfig({
  qualityGate: {
    rules: [
      {
        maxFailures: 5,
        myRule: 10,
      },
    ],
    use: [maxFailuresRule, myRule],
  },
});

Generalmente puedes colocar el código de tu regla personalizada en cualquier lugar de tu proyecto siempre que Node pueda resolverlo exitosamente.

Código Fuente de Reglas Incorporadas

Puedes encontrarlo en este repositorio.

Usar Variables de Entorno en Reglas

Si necesitas pasar el valor esperado de una regla desde el exterior (por ejemplo, desde una definición de flujo de trabajo), puedes usar variables de entorno en archivos de configuración dinámicos:

Allure configCI

import { defineConfig } from "allure";
import { myRule } from "./myRule.js";

const { MY_RULE_VALUE } = process.env;

export default defineConfig({
  name: "Allure Report 3",
  qualityGate: {
    rules: [
      {
        // usa 100 como valor de respaldo cuando la variable de entorno no está establecida
        myRule: MY_RULE_VALUE ? Number(MY_RULE_VALUE) : 100,
      },
    ],
    use: [myRule],
  },
});

yaml

jobs:
  test:
    runs-on: "ubuntu-latest"
    steps:
      # ...

      - run: npx allure run -- npm test
        env:
          MY_RULE_VALUE: 10

      # ...

Instalación y Actualización

Instalación y Actualización

Quality Gate Allure 3

Configuración Básica

Reglas Incorporadas

Fast Fail

Múltiples Conjuntos de Reglas

Ejecutar Allure con Quality Gates Habilitados

Configuración Avanzada

Filtros Personalizados

Campo `use`

Personalizar el Mensaje de una Regla

Usar Reglas Externas

Crear Reglas Personalizadas

`state` y Lógica de Fast Fail

Importar y Habilitar Regla Personalizada

Código Fuente de Reglas Incorporadas

Usar Variables de Entorno en Reglas

Powered by

Suscríbete a nuestro boletín

Allure TestOps

Compañía

Quality Gate Allure 3 ​

Configuración Básica ​

Reglas Incorporadas ​

Fast Fail ​

Múltiples Conjuntos de Reglas ​

Ejecutar Allure con Quality Gates Habilitados ​

Configuración Avanzada ​

Filtros Personalizados ​

Campo use ​

Personalizar el Mensaje de una Regla ​

Usar Reglas Externas ​

Crear Reglas Personalizadas ​

state y Lógica de Fast Fail ​

Importar y Habilitar Regla Personalizada ​

Código Fuente de Reglas Incorporadas ​

Usar Variables de Entorno en Reglas ​

Powered by

Suscríbete a nuestro boletín

Allure TestOps

Compañía

Quality Gate Allure 3

Configuración Básica

Reglas Incorporadas

Fast Fail

Múltiples Conjuntos de Reglas

Ejecutar Allure con Quality Gates Habilitados

Configuración Avanzada

Filtros Personalizados

Campo `use`

Personalizar el Mensaje de una Regla

Usar Reglas Externas

Crear Reglas Personalizadas

`state` y Lógica de Fast Fail

Importar y Habilitar Regla Personalizada

Código Fuente de Reglas Incorporadas

Usar Variables de Entorno en Reglas