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, Logging, SIP } from "@siteimprove/alfa-test-utils";
import { getCommitInformation } from "@siteimprove/alfa-test-utils/git";

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 gitInformation = await getCommitInformation();
        
          const pageReportUrl = await SIP.upload(audit, {
            userName: process.env.SI_USER_NAME,
            apiKey: process.env.SI_API_KEY,
            siteID: "12345",
            commitInformation: gitInformation,
          });

          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 Accessibility 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 page to audit.
  // This supposes that the server is already running.
  // 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