feat(cypress): command log steps rework

[delatrie]

Context

Allure Cypress automatically converts commands into Allure steps. It does so by listening command:start and command:end,

The PR reworks this mechanism to be based on the command log instead. It aligns with our general attitude to represent things as they are reported by the framework itself: the command log is the main reporting mechanism that Cypress provides to users in interactive mode.

Note

The Cypress command log supports events, e.g., the fetch events, which allow tracking HTTP requests made with the fetch API. Events like this are not the subject of this PR. The implementation currently doesn't create steps from them. We may support such events in the future.

Features

Child commands and assertions

Previously, Allure Cypress didn't include child commands, e.g., assertions. Now, it includes them as substeps of their parent command.

Example

it("assertions", () => {
  cy.wrap(1 + 1)
    .should("eq", 2)
    .and((v) => {
      expect(v).lessThan(3);
      return v + 1;
    })
    .and("eq", 3);
});

The Comman log

Allure Report before

Allure Report after

Properties of command log entries

Previously, Allure Cypress used to create step parameters from the attributes.args list of a command object. Now it uses the attributes.consoleProps function of a command log entry. This is the function Cypress uses to print the properties in the console when a user clicks on an entry in interactive mode.

The main difference is that consoleProps provides key-value pairs instead of a list of values, which allows as to use the actual names instead of syntetic ones. Additionally, many Cypress commands include extra useful data in such props.

Example

it("properties", () => {
  cy.visit("/");
  cy.get("input[type=text]")
    .should("have.attr", "placeholder")
    .and("eq", "Search without being tracked");
});

The Comman log and the console

Allure Report before

Allure Report after

Custom command log entries

Cypress allow users to add extra entries to the command log with Cypress.log. Allure Cypress now correctly converts them into steps. Child entries (type: "child") are included as substeps of the nearest running parent step (if any).

Example

it("custom log", () => {
  Cypress.log({ name: "start", message: "asserting", type: "parent" });
  cy.wrap(1 + 1).should((v) => {
    expect(v).eq(2);
    Cypress.log({ name: "done", message: "asserting", type: "child" });
  });
});

The Comman log

Allure Report

Hidden commands and log entries

Some commands take the { log: true } option. Cypress precludes such commands from the command log. Allure Cypress doesn't convert them to steps as well.

Example

it("hidden logs", () => {
  cy.wrap(1 + 1, { log: false }).should("eq", 2);
  cy.wrap(1 + 2, { log: false }).should("eq", 3);
});

The Comman log

Allure Report

Command log groups

Command log entries can be grouped by providing the { groupStart: true } option to Cypress.log. Allure Cypress converts such entries to steps. Every step created until log.endGroup is called becomes a substep. This applies to steps from the command log as well as to steps created with allure.step.

Example

it("log group", () => {
  const group = Cypress.log({
    name: "asserting",
    message: "the result of 1 + 1",
    type: "parent",
    groupStart: true,
  });
  cy.wrap(1 + 1).should("eq", 2).then(() => {
    group.endGroup();
  });
});

The Comman log

Allure Report

Note

Since @badeball/cypress-cucumber-preprocessor uses the Cypress.log API to group command log entries of a cucumber step, such grouping is automatically preserved by Allure Cypress. This wasn't the case earlier (see #1059).

Screenshots

Allure Cypress now uses the attachment step feature to report screenshots created with cy.screenshot or created by Cypress automatically when a test fails.

Example

it("screenshot", () => {
  cy.visit("/");
  cy.get(".is-not-mobile-device")
    .screenshot()
    .find("input[type=text]")
    .screenshot("the input");
});

Allure Report before

Allure Report after

Other changes

• serialize (in allure-js-commons/sdk/utils) now supports a new replacer option. A value must be a function with the following signature (this: unknown, key: string, value: unknown) => unknown. If provided, it's used by serialize to pre-process object property values.
• Allure Cypress now works better with other listeners of Cypress.on("fail", ...), which are created by a user or a 3rd party plugin. The exception is throws only if there are no subsequent listeners. Otherwise, it passes the responsibility of throwing to the next listener.

Checklist

• Sign Allure CLA
• Provide unit tests

Closes #1059.