Using with Cypress

See and use a fully working example in the Alfa examples repository.

Cypress setup requires both the actual test code, and a bit of setup in the Cypress configuration file. This is due to the way Cypress fully runs into a separate Javascript world, but the reporting has to occur in the regular NodeJS world.

Configuration

The following code shows a minimal configuration file. It can be merged with an existing Cypress configuration file by copying the report function to your task event listener.

// file cypress.config.ts
import type { Audit } from "@siteimprove/alfa-test-utils/audit";
import { Logging, SIP } from "@siteimprove/alfa-test-utils/report";

import { defineConfig } from "cypress";

export default defineConfig({
  screenshotOnRunFailure: false,

  e2e: {
    setupNodeEvents(on, config) {
      // implement node event listeners here
      on("task", {
        // Upload audit to Siteimprove Intelligence Platform and log results
        async report(audit: Audit.JSON): Promise<null> {
          const pageReportUrl = await SIP.upload(audit, {
            userName: process.env.SI_USER_EMAIL,
            apiKey: process.env.SI_API_KEY,
          });

          Logging.fromAudit(audit, pageReportUrl).print();

          return null;
        },
      });
    },
    supportFile: false,
    specPattern: "test/**.spec.ts",
  },
});

Test file

The following code sets up a Cypress test and runs an accessibility audit using the Code Checker. The result is logged to the console and the test fails if any issues on the page are found.

// file test/cypress.spec.ts
import { Cypress as AlfaCypress } from "@siteimprove/alfa-cypress";
import { Audit } from "@siteimprove/alfa-test-utils/audit";

it("should be accessible", () => {
  // Navigate to the local web page
  // This suppose that the server is already started. See the demo-site folder.
  // TODO: Replace with your own page
  cy.visit("http://localhost:8080");

  // wait for the page to fully load, here by waiting for a specific selector
  // TODO: Adapt with what is present in your own page
  cy.get(".testimonials-top").should("exist");

  /*
   * Usual Cypress instructions can live here.
   * For example, navigating through the page, opening menus or modals, etc.
   */

  const audit = cy
    // Get the document from the page
    .document()
    // Scrape the page
    .then(AlfaCypress.toPage)
    // Run the audit
    .then(Audit.run)
    // Upload and log the results.
    // Note: this has to happen in NodeJS, not in Cypress browser, hence we use
    // a cy.task call.
    .then(async (alfaResult) => {
      cy.task("report", alfaResult.toJSON());
      return alfaResult;
    });

  // Fail the test if any rule is failing
  // Note: this happens in a separate chain to avoid interfering with the
  // reporting.
  audit.then(async (alfaResult) => {
    const failingRules = alfaResult.resultAggregates.filter(
      (aggregate) => aggregate.failed > 0,
    );

    // Fail the test if any rule failed.
    expect(failingRules.size).to.equal(
      0,
      `The page has ${failingRules.size} failing rules`,
    );
  });
});

          

Previous: UsageNext: Reporting