Configuring reports

This page shows some common setups for configuring what is uploaded to the Siteimprove Intelligence Platform and how the results are shown in the page report. All options described here can be combined in the same call.

Mandatory options

The userName, apiKey, and siteID options are mandatory. If any of these are missing, SIP.upload will fail and return an error message (wrapped in an Err object).

userName and apiKey are credentials to connect to the Siteimprove Intelligence Platform. They should be treated as any credentials. Do not write them in plain text. Instead use environment variables or CI/CD secrets to inject them.

siteId is the site ID associated with the page in the Siteimprove Intelligence Platform. It is mandatory and helps connect the runs of Accessibility Code Checker with actual sites. However, the runs of Accessibility Code Checker and regular crawls do not impact each other. Notably, running the Accessibility Code Checker does not affect the DCI score of the site.

Including commit information

You can upload basic information about the latest commit in the repository (origin URL, branch name, and latest commit hash, author, message). If you are using git, we also provide a helper to retrieve that information automatically.

import { getCommitInformation } from "@siteimprove/alfa-test-utils/git";
            
// If using git, commit information can be retrieved automatically.
const gitInformation = await getCommitInformation(); 
            
SIP.upload(alfaResult, {
  userName: process.env.SI_USER_NAME,
  apiKey: process.env.SI_API_KEY,
  siteID: "12345",
  commitInformation: gitInformation,
});

SIP.upload(alfaResult, {
  userName: process.env.SI_USER_NAME,
  apiKey: process.env.SI_API_KEY,
  siteID: "12345",
  commitInformation: { BranchName: "my-feature-branch" }, // If not using git, it must be provided manually
});

Siteimprove recommends that you provide at least the BranchName.

Including a page title

The Siteimprove Intelligence Platform will group runs of the Code Checker by page title. This defaults to the first <title> element of the audited page (if any). In some cases, such a title does not exist and should be provided manually (for example, while unit testing components):

const pageReportURL = Audit.run(alfaPage, {
  rules: { include: Rules.componentFilter },
}).then((alfaResult) => {
  SIP.upload(alfaResult, {
    userName: process.env.SI_USER_NAME,
    apiKey: process.env.SI_API_KEY,
    siteID: "12345",
    pageTitle: "Paginated table component",
  });
});

Providing a page URL

If provided with a known page URL, the Siteimprove Intelligence Platform can use it to retrieve information about the page, such as which page group it belongs to. The URL defaults to the one used during scraping, but this is not always relevant, typically in case of localhost URLs.

// auditing a page at http://localhost:8080/about-us.html from the "contact" repository
          
const pageReportURL = Audit.run(alfaPage).then((alfaResult) => {
  SIP.upload(alfaResult, {
    userName: process.env.SI_USER_NAME,
    apiKey: process.env.SI_API_KEY,
    siteID: "12345",
    pageURL: "http://example.com/contact/about-us.html",
  });
});

Including a test name

The SIP.upload function accepts a test name. This will be displayed in the header of the page report and can be used to separate tests:

const pageReportURL = Audit.run(alfaPage, {
  rules: { include: Rules.aaFilter },
}).then((alfaResult) => {
  SIP.upload(alfaResult, {
    userName: process.env.SI_USER_NAME,
    apiKey: process.env.SI_API_KEY,
    siteID: "12345",
    testName: "WCAG 2.2 Level AA conformance test",
  });
});

Previous: Advanced audit configuration Next: Advanced reporting