Este es el primer post de una serie de tips cortos de Cypress: una herramienta o patrón de mi día a día por post, lo bastante breve para leerlo con un café.
¿Alguna vez has abierto una ejecución fallida y has hecho scroll por 300 líneas de get, click, should y xhr intentando averiguar qué estaba haciendo siquiera el test cuando se rompió? ¡A todos nos ha pasado!
El log de comandos es genial para decirte dónde hizo clic Cypress. Lo que no te dice es qué paso de negocio del escenario explotó. El arreglo que uso en el trabajo es un pequeño decorador de TypeScript en cada método de page object. Son unas 20 líneas y escala a miles de métodos sin que nadie tenga que tocar un solo spec.
El decorador de 20 líneas
Así que vamos al grano. Pon esto en cypress/support/step.ts e impórtalo una vez desde cypress/support/e2e.ts:
const steps: string[] = [];
beforeEach(() => {
steps.length = 0;
});
Cypress.on('fail', (error) => {
error.message += `\n\nSteps:\n${steps.map((label, i) => `${i + 1}. ${label}`).join('\n')}`;
throw error;
});
export function step(label: string) {
return function (_target: object, _key: string, descriptor: PropertyDescriptor) {
const original = descriptor.value;
descriptor.value = function (...args: unknown[]) {
cy.then(() => {
steps.push(label);
Cypress.log({ name: 'step', displayName: '▶', message: `**${label}**` });
});
return original.apply(this, args);
};
return descriptor;
};
}
Activa "experimentalDecorators": true en tsconfig.json y etiqueta los métodos de tus page objects:
export class CartPage {
@step('Apply a coupon')
applyCoupon(code: string): this {
cy.get('[data-cy="coupon"]').type(code);
cy.get('[data-cy="apply-coupon"]').click();
return this;
}
}
El spec no cambia ni una sola línea. Ahora cada llamada a applyCoupon() abre con una fila ▶ en negrita en el log de comandos.
Dos detalles que hacen que funcione
El log pasa por cy.then. Los métodos de page object se ejecutan de forma síncrona mientras el cuerpo del test todavía está encolando comandos. Si llamas a Cypress.log directamente, todas las filas de pasos acaban arriba del todo, antes de los comandos que describen. Dentro de cy.then entra en la cola, así que cada etiqueta queda justo encima de sus propios get y click.
El handler de fallo añade los pasos al error. Cualquier cosa que lea el error recibe el escenario gratis: el terminal, el archivo JUnit, la pestaña de tests de CI, tu informe HTML. Sin necesidad de ningún plugin de reporter.

Cómo compruebo que está bien conectado
- Lanza cualquier spec en
cypress open. Cada llamada a un page object debería abrir con una fila▶, justo encima de sus propios comandos. Si todas las filas se amontonan arriba, la llamada aCypress.logse ha escapado decy.then. - Rompe una aserción y lánzalo en headless. El error en el terminal debería acabar con
Steps:y una lista numerada, empezando por 1 en cada test (para eso está el reinicio enbeforeEach, reintentos incluidos). - De vez en cuando, lista los métodos de page object sin
@step. Unas pocas líneas con la API del compilador de TypeScript bastan. Trátalo como una auditoría, no como un bloqueo.
La única trampa que te va a morder
Los decoradores se ejecutan cuando se evalúa la clase, es decir, en el momento del import, no cuando un test llama al método. Si step queda dentro de un ciclo de imports, todavía puede ser undefined en ese instante y el archivo de spec entero revienta antes de registrar un solo test. Pregúntame cómo lo sé 😉. Escribí sobre cómo se ve ese fallo y cómo cazar el ciclo.
Poniéndolo todo junto en un spec completo
Aquí tienes un page object y un spec completos usando @step de principio a fin:
// cypress/pages/orders-page.ts
import { step } from '../support/step';
export class OrdersPage {
@step('Open the orders page')
visit(): this {
cy.visit('/orders');
return this;
}
@step('Start a new order')
startOrder(): this {
cy.get('[data-cy="new-order"]').click();
return this;
}
@step('Add a product to the order')
addProduct(name: string): this {
cy.get('[data-cy="product-search"]').clear().type(name);
cy.contains('[data-cy="product-row"]', name).find('[data-cy="add"]').click();
return this;
}
@step('Check the order is listed')
shouldList(orderId: string): this {
cy.contains('[data-cy="order-row"]', orderId).should('be.visible');
return this;
}
}
// cypress/e2e/orders.cy.ts
import { OrdersPage } from '../pages/orders-page';
const orders = new OrdersPage();
describe('Orders', () => {
beforeEach(() => {
cy.intercept('POST', '/api/orders').as('createOrder');
});
it('creates an order and lists it', () => {
orders.visit().startOrder().addProduct('Trail shoes');
cy.wait('@createOrder').then(({ response }) => {
expect(response?.statusCode).to.eq(201);
orders.shouldList(response?.body.id);
});
});
});
Lánzalo y el log de comandos se lee como el escenario: cuatro filas ▶, de arriba abajo, cada una con sus propios comandos debajo. Rompe shouldList y la salida de CI termina con los cuatro pasos numerados.

Resumen: qué tienes que hacer
- Activa
"experimentalDecorators": trueentsconfig.json. - Añade el decorador
@step()encypress/support/step.tse impórtalo desdecypress/support/e2e.ts. - Registra cada paso dentro de
cy.thenpara que salga en orden y vacía la lista enbeforeEach. - Añade los pasos al error en
Cypress.on('fail')para que cualquier reporter y pestaña de CI los muestre. - Decora métodos de page objects (no specs) y mantén
step.tsfuera de ciclos de imports.
Etiqueta los pasos una sola vez en tus page objects y cada spec del repositorio consigue un log legible gratis. ¿Cómo mantienes legibles tus logs de Cypress en suites grandes? Déjame un comentario, ¡me encantaría saberlo!
Siguiente: llevar ese log de comandos directo a la salida del terminal de CI para dejar de descargar vídeos por cada error 500.
