Pular para o conteúdo
Voltar aos Artigos Publicados
Cypress

Um decorator @step de 20 linhas que deixa o log do Cypress legível

O Cypress registra cada get, click e should, e você não consegue ver qual passo de negócio falhou. Um pequeno decorator TypeScript coloca um passo rotulado em cada método de page object.

Um decorator @step de 20 linhas que deixa o log do Cypress legível
Conteúdo 100% autoral: Todos os artigos, desafios práticos e soluções em código foram escritos por Marcelo Costa sem qualquer uso de IA na redação. A inteligência artificial foi utilizada exclusivamente no auxílio à tradução para múltiplos idiomas.

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.

O mesmo teste que falhou visto no log de comandos completo e na mensagem de falha do CI com os passos numerados anexados

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 ao Cypress.log escapou do cy.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 no beforeEach, 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.

Como o @step flui: o decorator enfileira uma linha rotulada com cy.then, o log de comandos exibe e o handler de falha anexa os passos ao erro

Resumo: o que você precisa fazer

  • Ative "experimentalDecorators": true no tsconfig.json.
  • Adicione o decorator @step() em cypress/support/step.ts e importe-o a partir de cypress/support/e2e.ts.
  • Registre cada passo dentro de cy.then para sair na ordem certa, e zere a lista no beforeEach.
  • 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.ts fora 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.