Using the CI/CD Integrations

Easily kick off a Stark scan anywhere in your pipeline and have reports forwarded up to Stark

With Stark's CI/CD integrations, you can kick off an accessibility scan anywhere you'd like. We support all the major frameworks and there's a multitude of options so you can optimize your setup.

Getting Started

You first need to decide where you want the results of your Stark scans to end up. We'll begin by setting up a project in Stark:

Log into your Stark account
Click Create a Project or select an existing project
Scroll to Import results from your CI/CD workflow
Keep track of the provided token, you'll use it in the integration steps below
Click Save CI/CD integration and go through the steps below for your preferred integration
After you've completed the steps, the results will begin flowing into this project! 🎉

📝

In order to install the necessary packages to run the Stark scans, you'll first need to get an API key. Only team admins can generate API keys currently.

To generate an API key:

Log into your Stark account
Click Team Settings
Scroll to API Keys and click Generate API Key
Follow the instructions in the dialog that pops up for using the API key to install our CI packages.

How to integrate with Puppeteer

Stark's Puppeteer integration is easy to set up; just follow these simple steps:

Install the package: npm install @stark-ci/puppeteer

Use the StarkScan function to scan a Puppeteer frame:

async function StarkScan(
  frame: Frame,
  options?: ScanOptions
): Promise<ResultsSummary>

The results that are returned allow you to pass/fail your tests based on: the number of items that passed; the number of potential issues found; the number of items that failed (violations). Additionally, if you need further control, we also provide those same results broken down by WCAG criteria if you're just wanting to focus on, for example, contrast issues. Here's an example result:
```
{
  "passed": 149,
  "failed": 10,
  "potentials": 6,
  "resultsByCriteria": {
    "1.1": {
      "passed": 15,
      "failed": 2,
      "potentials": 0
    },
    "1.2": ...,
  }
}
```

Options
You can pass in the following (optional) properties:

wcagVersion: The WCAG version for which you want to retrieve results. (Values: "2.0", "2.1", "2.2" - Default: "2.2")
conformanceLevel: The WCAG level you are targeting. (Values: "A", "AA", "AAA" - Default: "AA")
elementSelector: If provided, will restrict scanning to a specific element in the frame.
scanDepth: When combined with elementSelector, specifies how deep to scan for issues. (Values: "surface" - just the element, "shallow" - the element and its direct children, "deep" - the element and all of its children. - Default: "surface").
sendResults: Send scan results to Stark for analysis. If sending results is enabled, token and name must also be set. If set to "errorOnFailure" a test failure will be generated if results failed to send; otherwise they'll flow up to Stark as expected. (Values: true, false, "errorOnFailure" - Default: false).
token: API token that authorizes sending results to your project. Retrieve this token from the Stark web app.
name: A name that describes what was scanned. (ex: "File upload error dialog shown"). Names must be unique within a single project as they are how the results are segmented within Stark.

Example Usage
Here's an example of sending scan results to a Stark project so you can view the report within Stark's Reports & Insights.

const puppeteer = require('puppeteer');
const { StarkScan } = require('@stark-ci/puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://teamsync-stark.webflow.io/');

  const results = await StarkScan(page.mainFrame(), {
    wcagVersion: '2.1',
    sendResults: true,
    name: 'TeamSync main page',
    token: 'stark_11111111222233334444555555555555',
  });

  console.log('Accessibility Scan Results:', results);

  await browser.close();
})();

How to integrate with Playwright

Begin testing with Playwright by following just a few simple steps.

Install the package: npm install @stark-ci/playwright

Use the StarkScan function to scan a Playwright frame:

async function StarkScan(
  frame: Frame,
  options?: ScanOptions
): Promise<ResultsSummary>

The results that are returned allow you to pass/fail your tests based on: the number of items that passed; the number of potential issues found; the number of items that failed (violations). Additionally, if you need further control, we also provide those same results broken down by WCAG criteria if you're just wanting to focus on, for example, contrast issues. Here's an example result:
```
{
  "passed": 149,
  "failed": 10,
  "potentials": 6,
  "resultsByCriteria": {
    "1.1": {
      "passed": 15,
      "failed": 2,
      "potentials": 0
    },
    "1.2": ...,
  }
}
```

Options
You can pass in the following (optional) properties:

wcagVersion: The WCAG version for which you want to retrieve results. (Values: "2.0", "2.1", "2.2" - Default: "2.2")
conformanceLevel: The WCAG level you are targeting. (Values: "A", "AA", "AAA" - Default: "AA")
elementSelector: If provided, will restrict scanning to a specific element in the frame.
scanDepth: When combined with elementSelector, specifies how deep to scan for issues. (Values: "surface" - just the element, "shallow" - the element and its direct children, "deep" - the element and all of its children. - Default: "surface").
sendResults: Send scan results to Stark for analysis. If sending results is enabled, token and name must also be set. If set to "errorOnFailure" a test failure will be generated if results failed to send; otherwise they'll flow up to Stark as expected. (Values: true, false, "errorOnFailure" - Default: false).
token: API token that authorizes sending results to your project. Retrieve this token from the Stark web app.
name: A name that describes what was scanned. (ex: "File upload error dialog shown"). Names must be unique within a single project as they are how the results are segmented within Stark.

Example Usage
Here's an example of sending scan results to a Stark project so you can view the report within Stark's Reports & Insights.

const { test, expect } = require('@playwright/test');
const { StarkScan } = require('@stark-ci/playwright');

test('get started link', async ({ page }) => {
  await page.goto('https://teamsync-stark.webflow.io/');

  const results = await StarkScan(page.mainFrame(), {
    wcagVersion: '2.1',
    sendResults: true,
    name: 'TeamSync main page',
    token: 'stark_11111111222233334444555555555555',
  });

  console.log('Accessibility Scan Results:', results);

  expect(results.failed < 10).toBeFalsy();
});

How to integrate with Cypress

Stark's Cypress integration requires just a few steps to get started.

Install the package: npm install @stark-ci/cypress
Extend the Cypress cy object with our scan command by adding the following to your cypress/support/e2e.js file: import '@stark-ci/cypress';
Use the starkScan function on your cy object to begin a scan:
```
cy.starkScan(
  options?: ScanOptions
)
```
This returns a Cypress Chainable results summary. The results that are returned allow you to pass/fail your tests based on: the number of items that passed; the number of potential issues found; the number of items that failed (violations). Additionally, if you need further control, we also provide those same results broken down by WCAG criteria if you're just wanting to focus on, for example, contrast issues. Here's an example result:
```
{
  "passed": 149,
  "failed": 10,
  "potentials": 6,
  "resultsByCriteria": {
    "1.1": {
      "passed": 15,
      "failed": 2,
      "potentials": 0
    },
    "1.2": ...,
  }
}
```

If you are using Typescript, make sure to add @stark-ci/cypress to your project's tsconfig.json so you get type definitions for the starkScan command:

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["es6", "dom"],
    "types": ["node", "cypress", "@stark-ci/cypress"]
  },
  "include": ["**/*.ts"]
}

Options
You can pass in the following (optional) properties:

wcagVersion: The WCAG version for which you want to retrieve results. (Values: "2.0", "2.1", "2.2" - Default: "2.2")
conformanceLevel: The WCAG level you are targeting. (Values: "A", "AA", "AAA" - Default: "AA")
elementSelector: If provided, will restrict scanning to a specific element in the frame.
scanDepth: When combined with elementSelector, specifies how deep to scan for issues. (Values: "surface" - just the element, "shallow" - the element and its direct children, "deep" - the element and all of its children. - Default: "surface").
sendResults: Send scan results to Stark for analysis. If sending results is enabled, token and name must also be set. If set to "errorOnFailure" a test failure will be generated if results failed to send; otherwise they'll flow up to Stark as expected. (Values: true, false, "errorOnFailure" - Default: false).
token: API token that authorizes sending results to your project. Retrieve this token from the Stark web app.
name: A name that describes what was scanned. (ex: "File upload error dialog shown"). Names must be unique within a single project as they are how the results are segmented within Stark.

Example Usage
Here's an example of sending scan results to a Stark project so you can view the report within Stark's Reports & Insights.

describe('TeamSync Web Site', () => {
  it('has no accessibility issues', () => {
    cy.visit('https://teamsync-stark.webflow.io/');
    cy.starkScan({
      wcagVersion: '2.2',
      sendResults: true,
      name: 'TeamSync main page',
      token: 'stark_11111111222233334444555555555555',
    }).then((results) => {
      expect(results.failed).to.equal(0);
    });
  });
});

Have any questions about using Stark's developer tools? Don’t hesitate to reach out to us at support@getstark.co.

Go back to articles