Metadatos y enlaces de pruebas de Cypress

probara cuenta al reporter algo más sobre una prueba, desde el cuerpo de la prueba o desde un hook beforeEach o afterEach. El archivo de soporte lo publica como un global de la spec, así que una spec lo llama sin importar nada:

cypress/e2e/payments.cy.js

it('pays with a card', () => {
  probara.title('Pays with a saved card').suite(['Payments', 'Cards']).tags('smoke');
  cy.get('.pay').click();
});

Los helpers necesitan el plugin y el archivo de soporte (registro). El paquete incluye sus tipos, así que las specs en TypeScript también tienen el global probara.

Helper	Qué hace	Llamadas repetidas
id(id | ids)	Vincula casos existentes (vincular)	Se suman
title(text)	Título del caso que crea el informe	Gana la última
suite(title | titles)	Ruta de suites del caso que crea el informe	Gana la última
comment(text)	Un comentario, al principio de las notas del resultado, antes del error	Gana la última
ignore()	Deja fuera este intento: no se reporta	—
tags(...names)	Etiquetas del caso que crea el informe	Se suman, cada una una vez
fields(record)	Campos del caso que crea el informe: campos de sistema, campos personalizados, description	Se combinan por nombre
parameters(record)	Parámetros del resultado, mostrados con él	Se combinan por nombre
link(url, name?), issue(id)	Enlaces del resultado (enlaces e incidencias)	Se suman
attach({ name, path | body, ... })	Adjunta un archivo (adjuntos)	Cada una adjunta
step(title, body?, options?)	Un paso del resultado, y del caso nuevo (pasos)	Cada una es un paso

Los helpers de metadatos devuelven probara, así que las llamadas se encadenan. Cada uno se aplica solo al intento en curso: un reintento empieza vacío.

Solo casos creados

title, suite, tags, fields y los pasos del caso describen el caso que crea un informe, la primera vez que se reporta una prueba. Un caso existente nunca cambia: Probara conserva lo que la gente escribió ahí. La clave de automatización tampoco cambia (claves), así que un título nuevo sigue asociándose al mismo caso.

cypress/e2e/payments.cy.js

it('pays', () => {
  probara
    .title('Pays with a saved card')
    .suite(['Payments', 'Cards'])
    .tags('smoke', 'payments')
    .fields({
      description: 'A returning customer pays with the card saved in their profile.',
      severity: 'critical',
      priority: 'high',
      'Risk area': 'Checkout',
    });
  cy.get('.pay').click();
});

[
  {
    "automationKey": "cypress/e2e/payments.cy.js > pays",
    "title": "Pays with a saved card",
    "suitePath": ["Payments", "Cards"],
    "case": {
      "description": "A returning customer pays with the card saved in their profile.",
      "tags": ["smoke", "payments"],
      "fields": { "severity": "critical", "priority": "high", "Risk area": "Checkout" }
    }
  }
]

Campos

fields() acepta nombres y valores (los números y los booleanos se convierten en texto):

Nombre	Qué define
description	La descripción del caso
severity, priority, type, layer, behavior, status, is_flaky	Los campos de sistema, por el nombre de una opción (high)
preconditions, postconditions	Los campos de texto de sistema
Cualquier otro nombre, como 'Risk area'	El campo personalizado con ese nombre

Probara resuelve los nombres y las opciones al crear el caso. Un campo o una opción que no conoce se omite y se registra como advertencia; el resultado se registra igualmente. Un campo con un valor vacío se omite sin aviso.

Título y suite

El título de un caso creado es el título de la prueba (sin los IDs de caso), salvo que title() diga otra cosa. Su ruta de suites es el archivo de la spec y los bloques describe que contienen la prueba (cypress/e2e/payments.cy.js › Checkout) o, con keyIncludesFile: false, solo los bloques describe, salvo que suite() indique una: suite('Payments'), o suite(['Payments', 'Cards']) para suites anidadas, que se crean según haga falta bajo suiteUlid.

Comentario

comment() escribe una línea al principio de las notas del resultado, antes del error y su traza:

cypress/e2e/search.cy.js

it('searches the catalog', () => {
  probara.comment('Ran against the staging catalog');
  cy.get('#search').type('boots{enter}');
});

[
  {
    "automationKey": "cypress/e2e/search.cy.js > searches the catalog",
    "notes": "Ran against the staging catalog"
  }
]

Cuando el intento falla, su error sigue al comentario en las mismas notas, sin los colores de la terminal: el comentario nunca oculta el error.

Parámetros

parameters() registra los valores con los que se ejecutó un intento, mostrados con su resultado, como el usuario o el conjunto de datos de una prueba guiada por datos. Nunca forman parte de la clave: la prueba es un solo caso sean cuales sean sus parámetros. Cuando el caso declara un parámetro con el mismo nombre, el resultado se registra en el caso de ejecución con esos valores. Un parámetro que el caso no declara se queda en el resultado solo para mostrarlo.

cypress/e2e/users.cy.js

['admin', 'viewer'].forEach((role) => {
  it(`opens the dashboard as ${role}`, () => {
    probara.parameters({ role, seats: 5 });
    cy.visit('/dashboard');
  });
});

[
  {
    "automationKey": "cypress/e2e/users.cy.js > opens the dashboard as admin",
    "parameters": { "browser": "electron", "role": "admin", "seats": "5" }
  },
  {
    "automationKey": "cypress/e2e/users.cy.js > opens the dashboard as viewer",
    "parameters": { "browser": "electron", "role": "viewer", "seats": "5" }
  }
]

Dos parámetros se añaden solos: browser, el navegador que ejecuta Cypress (browserAsParameter), y attempt, desde el segundo intento de una prueba reintentada. Mantén el valor en el título de una prueba generada, como arriba: las pruebas con el mismo título completo en una spec comparten clave, y lo que dijeron sus helpers se omite.

Ignorar un intento

ignore() deja fuera el intento en curso: se sigue ejecutando, y Cypress lo reporta, pero Probara no lo recibe. El recuento del registro dice cuántos se dejaron fuera.

cypress/e2e/experimental.cy.js

it('tries the new checkout', () => {
  probara.ignore();
  cy.visit('/checkout-beta');
});

$ npx cypress run
[probara] Sending 3 results of 4 tests (3 passed, 0 failed, 0 skipped, 0 blocked); 1 ignored with probara.ignore()

Enlaces e incidencias

Un resultado puede llevar enlaces, mostrados con él en Probara: el build que lo ejecutó, la página que probó, las incidencias de tu gestor a las que se refiere.

probara.link()

probara.link(url, name?) acepta una URL http o https absoluta y un nombre opcional, que se muestra en lugar de la URL:

cypress/e2e/checkout.cy.js

it('pays by card', () => {
  probara.link('https://ci.example.com/build/12', 'Build 12');
  cy.get('.pay').click();
});

probara.issue() e issueUrlTemplate

probara.issue(id) nombra una incidencia de tu gestor por su ID, no por su URL. Con issueUrlTemplate (PROBARA_ISSUE_URL_TEMPLATE), una URL con %s donde va el ID, se convierte en un enlace del resultado, con el ID como nombre:

cypress.config.js

reporterOptions: {
  projectId: 'SHOP',
  issueUrlTemplate: 'https://jira.example.com/browse/%s',
},

cypress/e2e/checkout.cy.js

it('pays by card', () => {
  probara.issue('PAY-7');
  cy.get('.pay').click();
});

{
  "automationKey": "cypress/e2e/checkout.cy.js > pays by card",
  "links": [{ "url": "https://jira.example.com/browse/PAY-7", "name": "PAY-7" }]
}

• El ID entra en la plantilla codificado para URL, en lugar de %s.
• La plantilla es una URL http o https con %s; cualquier otro valor desactiva el envío con un error que nombra issueUrlTemplate.
• Sin plantilla, las incidencias se omiten, y una línea lo dice: el resultado se registra sin ellas.

[probara] Dropped the issues of probara.issue(): no issueUrlTemplate turns their ids into links

Reglas de los enlaces

Regla	Qué pasa
Una URL que no es una URL http/https absoluta	Se omite: probara.link() takes an absolute http(s) URL of at most 2048 characters
Una URL de más de 2048 caracteres	Se omite, con la misma advertencia
Un nombre que no es texto	Se omite: probara.link() takes the name as a string
Un nombre de más de 255 caracteres	Se recorta a 255 caracteres, con una advertencia
Más de 20 enlaces en un resultado	Se envían los 20 primeros, con una advertencia
Un reintento	Empieza sin enlaces: cada intento envía los suyos

Los enlaces pertenecen al resultado, no al caso: un caso existente nunca cambia, y cada resultado conserva los enlaces que añadió su intento. Para vincular el propio caso con una incidencia de Jira, consulta Trazabilidad con Jira.

Dónde llamar a los helpers

Dónde	Qué pasa
El cuerpo de la prueba, beforeEach, afterEach	Se aplica a la prueba para la que se ejecuta el hook
El hook after de un describe	Se aplica a la última prueba de ese describe, que Cypress nombra ahí como la prueba en curso
El hook before de un describe	Se omite, con una advertencia por spec: no ha empezado ningún intento, y la llamada nunca se da a otra prueba
El código de nivel superior de una spec	Se omite: no hay cadena cy con la que enviarla

Un helper nunca hace fallar la prueba. Un argumento incorrecto, o una llamada que no pertenece a ninguna prueba, es una advertencia [probara] en el registro de la ejecución, y la llamada se ignora:

$ npx cypress run
[probara] Left out 1 probara.* call in cypress/e2e/helpers.cy.js: what it said belongs to no attempt that ran (probara.title() of a hook that runs no test) (first seen in cypress/e2e/helpers.cy.js; repeats are logged at debug)

Cómo llega una llamada al informe

El navegador no puede llegar al reporter por sí solo: cada llamada va al plugin con cy.task('probara', …), encolada y esperada como cualquier otro comando de Cypress, así que llega al informe antes de que termine la prueba. Sin el plugin no hay nada que la transporte: cada helper no hace nada, y una línea en la consola del navegador dice por qué. Una advertencia sobre una llamada dentro de una spec se registra cuando termina esa spec, no al final de la ejecución.

Relacionado: Pasos y adjuntos · Vincular · Migrar desde Qase · Fuente: metadata.md, links.md