Este é o primeiro post de uma série de dicas curtas de Cypress: uma ferramenta ou padrão do meu dia a dia por post, pequeno o bastante para ler tomando um café.
Você já abriu uma execução que falhou e ficou rolando por 300 linhas de get, click, should e xhr tentando entender o que o teste estava sequer fazendo quando quebrou? Quem nunca!
O log de comandos é ótimo para dizer no que o Cypress clicou. O que ele não diz é qual passo de negócio do cenário foi pelos ares. A solução que eu uso no trabalho é um pequeno decorator TypeScript em cada método de page object. Tem umas 20 linhas e escala para milhares de métodos sem ninguém precisar encostar em uma spec.
O decorator de 20 linhas
Então vamos direto ao ponto. Coloque isto em cypress/support/step.ts e importe uma única vez a partir de 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;
};
}
Ative "experimentalDecorators": true no tsconfig.json e rotule os métodos dos seus 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;
}
}
A spec não muda nem uma única linha. Agora, toda chamada a applyCoupon() abre com uma linha em negrito marcada com ▶ no log de comandos.
Dois detalhes que fazem isso funcionar
O log passa por cy.then. Métodos de page object rodam de forma síncrona enquanto o corpo do teste ainda está enfileirando comandos. Se você chamar Cypress.log direto, todas as linhas de passo vão parar no topo do log, antes dos comandos que elas descrevem. Dentro de cy.then, o registro entra na fila, então cada rótulo fica exatamente acima dos seus próprios get e click.
O handler de falha anexa os passos ao erro. Qualquer coisa que leia o erro ganha o cenário de graça: o terminal, o arquivo JUnit, a aba de testes do CI, o seu relatório HTML. Sem precisar de nenhum plugin de reporter.

Como eu confiro que está bem amarrado
- Rode qualquer spec no
cypress open. Cada chamada de page object precisa abrir com uma linha▶logo acima dos próprios comandos. Se todas as linhas se amontoarem no topo, a chamada aoCypress.logescapou docy.then. - Quebre uma asserção e rode em modo headless. O erro no terminal tem que terminar com
Steps:e uma lista numerada, recomeçando do 1 em cada teste (é para isso que serve o reset nobeforeEach, incluindo retries). - De tempos em tempos, liste os métodos de page object que estão sem
@step. Algumas linhas com a compiler API do TypeScript resolvem. Trate isso como auditoria, não como bloqueio.
A única pegadinha que vai te morder
Decorators rodam quando a classe é avaliada, ou seja, na hora do import, não quando um teste chama o método. Se step cair dentro de um ciclo de imports, ele ainda pode estar undefined nesse momento, e o arquivo de spec inteiro quebra antes de registrar um único teste. Me pergunte como eu sei 😉. Eu escrevi sobre como essa quebra aparece e como caçar o ciclo.
Juntando tudo em uma spec completa
Aqui vai um page object e uma spec completos usando @step de ponta a ponta:
// 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);
});
});
});
Rode isso e o log de comandos se lê como o cenário: quatro linhas ▶, de cima para baixo, cada uma com seus próprios comandos logo abaixo. Quebre o shouldList e a saída do CI termina com os quatro passos numerados.

Resumo: o que você precisa fazer
- Ative
"experimentalDecorators": truenotsconfig.json. - Adicione o decorator
@step()emcypress/support/step.tse importe-o a partir decypress/support/e2e.ts. - Registre cada passo dentro de
cy.thenpara sair na ordem certa, e zere a lista nobeforeEach. - Anexe os passos ao erro em
Cypress.on('fail')para que todo reporter e aba de CI os exiba. - Decore métodos de page objects (não as specs) e mantenha
step.tsfora de ciclos de imports.
Rotule os passos uma vez nos seus page objects, e todas as specs do repositório ganham um log legível de graça. Como você faz para manter os logs do Cypress legíveis em suítes grandes? Deixe um comentário, eu adoraria saber!
Próximo: jogar esse log de comandos direto na saída do terminal do CI para parar de baixar vídeo a cada erro 500.
