Configuring the 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 together in the same call.

Mandatory Options

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

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

siteId is the site ID where the tested page belongs in the Siteimprove Intelligence Platform. It is mandatory, and helps connecting the Accessibility Code Checker runs with actual sites. However, Accessibility Code Checker runs and regular crawls do not impact each other. Notably, the Accessibility Code Checker runs do 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 using git, we also provide an 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 case, such a title does not exist (e.g. while unit testing components) and should be provided manually:

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 in which page group it belongs to. The URL defaults to the one that was 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