Categorías

Allure Report te ayuda a rastrear errores (y, opcionalmente, cualquier otro tipo de resultado de prueba) dividiéndolos en categorías basadas en los estados y mensajes de salida de las pruebas.

TIP

Cada resultado pertenece a una sola categoría. Puede ser una de las categorías predeterminadas que Allure asigna automáticamente, o una categoría personalizada que tú defines.

En la pestaña Categorías de un reporte de pruebas, las pruebas se agrupan por su categoría, su mensaje de error y, opcionalmente, por varios otros niveles de categorización.

Categorías predeterminadas

Allure define dos categorías predeterminadas de errores, ambas incluyen pruebas que no terminaron con éxito:

• Defectos del producto - pruebas Fallidas.
• Defectos de prueba - pruebas Rotas.

Categorías personalizadas

Puedes definir cualquier número de categorías personalizadas. Todos los resultados de prueba se comparan primero con tus categorías personalizadas, en el orden en que las defines. Las pruebas fallidas o rotas que no coinciden con ninguna categoría personalizada se asignan automáticamente a las categorías predeterminadas.

Allure Report 3

En Allure Report 3 puedes configurar categorías personalizadas en el campo categories del archivo de configuración de tiempo de ejecución.

Los ejemplos a continuación muestran los dos enfoques principales para definir categorías, con todas las configuraciones disponibles incluidas.

Discutiremos las diferencias entre estos dos enfoques más adelante.

Categories via object matchers

import { defineConfig } from "allure";

export default defineConfig({
  name: "Allure Report 3",
  output: "./allure-report",
  historyPath: "./history.jsonl", //requerido para identificar de inestabilidad (“flaky”) y de transiciones de estado
  categories: {
    rules: [
      {
        name: "Critical regressions by layer",
        id: "critical-regressions-by-layer",
        // esta sección determina qué se incluye en la categoría
        matchers: {
          statuses: ["failed", "broken"],
          flaky: false,
          labels: { severity: "critical" },
          message: /expected|API/, // acepta expresiones regulares
          trace: /AssertionError|timeout|unexpected/, // acepta expresiones regulares
          transitions: ["regressed", "malfunctioned"],
          environments: ["staging", "production"],
        },

        // esta sección determina cómo se presenta la categoría
        groupBy: ["layer", "owner", "status"],
        groupByMessage: true,
        groupEnvironments: true,
        expand: true,
        hide: false,
      },
    ],
  },
});

Categories via function matchers

import { defineConfig } from "allure";

export default defineConfig({
  name: "Allure Report 3",
  output: "./allure-report",
  historyPath: "./history.jsonl", //requerido para identificar de inestabilidad (“flaky”) y de transiciones de estado
  categories: {
    rules: [
      {
        name: "Critical regressions by layer",
        id: "critical-regressions-by-layer",
        // esta sección determina qué se incluye en la categoría
        matchers: (data) =>
          (data.status === "failed" || data.status === "broken") &&
          !data.flaky &&
          data.labels.some((l) => l.name === "severity" && l.value === "critical") &&
          /expected|API/.test(data.message ?? "") &&
          /AssertionError|timeout|unexpected/.test(data.trace ?? "") &&
          (data.transition === "regressed" || data.transition === "malfunctioned") &&
          (data.environment === "staging" || data.environment === "production"),
        // esta sección determina cómo se presenta la categoría
        groupBy: ["layer", "owner", "status"],
        groupByMessage: true,
        groupEnvironments: true,
        expand: true,
        hide: false,
      },
    ],
  },
});

Ambos ejemplos crean una categoría personalizada que se ve así:

Como se muestra en los ejemplos anteriores, las categorías personalizadas se definen en el campo de configuración categories, que es un objeto con un arreglo rules.

Cada regla en el arreglo rules es una definición de categoría personalizada, con las siguientes configuraciones disponibles:

• name (string, requerido) — el título de la categoría que se muestra en el reporte. Se puede cambiar libremente sin afectar la identidad de la categoría cuando se establece id.

• id (string, opcional) — un identificador estable para la categoría. Se utiliza para rastrear la identidad de la categoría a lo largo de ejecuciones del reporte, de modo que los cambios en name no rompan el historial ni creen entradas duplicadas. Si se omite, se usa name como id. Debe ser una cadena no vacía sin espacios en blanco al inicio/final ni caracteres de control. Dos reglas con el mismo id se fusionan.

• matchers (requerido) — determina qué resultados de prueba pertenecen a la categoría buscando metadatos especificados en tus resultados de prueba. matchers puede ser:

• Object matcher - un objeto plano con cualquier combinación de:

  • statuses: TestStatus[] - coincide con el estado de la prueba, p. ej. ["failed", "broken"].
  • flaky: boolean - determina si la categoría debe incluir pruebas inestables. Requiere historial para funcionar.
  • labels: { [labelName]: string | RegExp } - coincide con etiquetas, como expresión regular. La entrada de cadena se convierte en un objeto RegExp, por lo que cualquier metacarácter de regex incluido en la cadena (como ., * o ^) afectará cómo se comporta la coincidencia, p. ej. { owner: /^alice/ } coincidirá con todos los resultados donde la etiqueta owner comience con alice.
  • message: (sub)cadena | RegExp - coincide con el mensaje de error como expresión regular. Al igual que con labels, cualquier metacarácter de regex en una cadena proporcionada afectará la coincidencia.
  • trace: (sub)cadena | RegExp - coincide con el stack trace como expresión regular. Al igual que con labels, cualquier metacarácter de regex en una cadena proporcionada afectará la coincidencia.
  • transitions: TestStatusTransition[] - coincide con transiciones, p. ej. ["new", "regressed"]. Requiere historial para funcionar.
  • environments: string[] - coincide con entornos.

  Las pruebas que cumplan todas estas condiciones serán incluidas (se aplica lógica AND).

• Function matcher — (data) => boolean, donde data contiene status, labels, message, trace, flaky, duration, transition, environment.

  El function matcher requiere configuración dinámica para funcionar, y al igual que con los object matchers, debes habilitar el historial para coincidir con flaky y transition, y configurar los entornos para coincidir con environment.

  Al usar function matchers, puedes filtrar adicionalmente por duration (p. ej. (data) => data.duration > 5000), implementar compuertas lógicas complejas entre múltiples condiciones y usar expresiones JavaScript arbitrarias para ajustar tus categorías.

• Array — cualquier combinación de los anteriores; la prueba coincide si algún matcher del arreglo coincide (se aplica lógica OR).

• groupBy (array, opcional) — controla la jerarquía de anidamiento dentro del árbol de categorías. Cada elemento es un selector de cadena incorporado o un objeto de etiqueta personalizado:

  • Incorporados: "flaky", "owner", "severity", "transition", "status", "environment", "layer"
  • Etiquetas personalizadas: { label: "myCustomLabel" }

  Ejemplo: groupBy: ["severity", { label: "feature" }] crea dos niveles de agrupación — primero por severidad, luego por característica — antes de mostrar los resultados de prueba individuales.

• groupByMessage (boolean, por defecto true) — Cuando es true, agrega un nivel de agrupación adicional por debajo de los niveles de groupBy, agrupando las pruebas que comparten el mismo mensaje de error. Los mensajes largos obtienen un botón "mostrar más/menos" en la interfaz.

• groupEnvironments (boolean, opcional) — controla si se agrupan pruebas de diferentes entornos juntas (mostrando el nombre de la prueba una vez, con hojas etiquetadas por entorno debajo).

• expand (boolean, por defecto false) — si la categoría está expandida por defecto en la interfaz.

• hide (boolean, por defecto false) — si se excluye esta categoría del árbol completamente (las pruebas coincidentes aún son consumidas por la regla, evitando que coincidan con reglas posteriores y categorías predeterminadas).

También puedes establecer categories: false para deshabilitar las categorías completamente (ni las categorías predeterminadas ni las reglas personalizadas se aplicarán).

Ejemplos variados de configuración de categorías personalizadas

import { defineConfig } from "allure";

export default defineConfig({
  name: "Allure Report 3",
  output: "./allure-report",
  historyPath: "./history.jsonl", // requerido para la detección de intermitentes y transiciones
  categories: {
    rules: [
      // 1. Matcher de objeto, todos los groupBy incorporados, groupByMessage, groupEnvironments explícito true
      {
        id: "critical-failures-by-layer",
        name: "Critical failures by layer",
        matchers: {
          statuses: ["failed"],
          labels: { severity: "critical" },
        },
        groupBy: ["severity", "owner", "layer", "status", "transition", "flaky"],
        groupByMessage: true,
        groupEnvironments: true,
        expand: true,
        hide: false,
      },

      // 2. Selector de etiqueta personalizada en groupBy, groupEnvironments explícito false
      {
        id: "failures-by-component",
        name: "Failures by component",
        matchers: {
          statuses: ["failed", "broken"],
          labels: { component: /.+/ },
        },
        groupBy: [{ label: "epic" }, { label: "feature" }],
        groupByMessage: true,
        groupEnvironments: false,
        expand: false,
        hide: false,
      },

      // 3. Matcher de función, groupByMessage false, groupEnvironments auto (omitido)
      {
        id: "long-running-tests",
        name: "Long running tests",
        matchers: (data) => data.duration > 5000,
        groupBy: ["owner"],
        groupByMessage: false,
        expand: false,
        hide: false,
      },

      // 4. Array de matchers (lógica OR), mezcla de objeto y función
      {
        id: "flaky-or-regressed",
        name: "Flaky or regressed",
        matchers: [{ flaky: true }, (data) => data.transition === "regressed"],
        groupBy: ["flaky", "transition"],
        groupByMessage: true,
        groupEnvironments: true,
        expand: true,
        hide: false,
      },

      // 5. Coincidencia de regex en mensajes
      {
        id: "connection-errors",
        name: "Connection errors",
        matchers: {
          message: /ECONNRESET|connection failed|timeout/,
          statuses: ["broken"],
        },
        groupBy: ["environment", "layer"],
        groupByMessage: true,
        groupEnvironments: false,
        expand: false,
        hide: false,
      },

      // 6. Matcher de transición, que incluye nuevas pruebas que pasaron
      {
        id: "new-and-regressed-tests",
        name: "New and regressed tests",
        matchers: {
          transitions: ["new", "regressed"],
        },
        groupBy: ["transition", "owner"],
        groupByMessage: false,
        groupEnvironments: true,
        expand: true,
        hide: false,
      },

      // 7. Categoría oculta — consume las pruebas coincidentes para que no caigan en las predeterminadas
      {
        id: "other-failed-and-broken-tests",
        name: "Other failed and broken tests",
        matchers: {
          statuses: ["failed", "broken"],
        },
        groupBy: [],
        groupByMessage: false,
        groupEnvironments: false,
        expand: false,
        hide: true, // la categoría no se mostrará en el reporte
      },
    ],
  },
  plugins: {
    awesome: {
      options: {
        reportName: "Allure Report",
        singleFile: false,
        reportLanguage: "en",
      },
    },
  },
  // configuración de entornos, configurada para que groupEnvironments funcione
  environments: {
    staging: {
      matcher: ({ labels }) =>
        labels.some(({ name, value }) => name === "env" && value === "staging"),
    },
    production: {
      matcher: ({ labels }) =>
        labels.some(({ name, value }) => name === "env" && value === "production"),
    },
  },
});

Allure Report 2

En Allure Report 2 puedes definir categorías personalizadas colocando un archivo de categorías en el directorio de resultados de las pruebas (consulta Cómo funciona). Allure verifica cada prueba con todas las categorías en el archivo, de arriba hacia abajo. A la prueba se le asigna la primera categoría coincidente. Si no se encuentran coincidencias, Allure utiliza una de las categorías predeterminadas si la prueba no tiene éxito o ninguna categoría en caso contrario.

Algunos complementos de Allure pueden generar el archivo de categorías automáticamente según la configuración del proyecto. Consulta la documentación de tu integración.