UserWay CI/CD works great in combination with e2e testing frameworks such as Selenium. But if your web project does not currently have existing e2e test suites, there is an option of using UserWay managed scan. You will have to configure userway.config.js with the connection to your running website and all page paths you want to scan and we will collect accessibility insights by executing analysis completely on UserWay infrastructure.

1. Install @userway/cicd-cli npm package

Install the @userway/cicd-cli package in the root of your e2e testing project. This is a command line interface tool which collects all necessary information about your workflow environment (such as branch name, recent commit hash etc.), and communicates with UserWay CI/CD backend in order trigger accessibility analysis.

npm install --save-dev @userway/cicd-cli

Note: latest version can be found on npmjs

2. Configure file userway.config.js with the website connection

Once you have installed the @userway/cicd-cli package, you must create a configuration file to specify a connection to your running website. The website connection configuration depends on the type of deployment. There are two options:

• The website is deployed into a publicly accessible endpoint, such as a QA or staging environment. This website is accessible from the Internet to any user.
• The website is running on localhost (dev machine or DevOps pipeline instance) and is not visible to the outside world.

Connection config depends on the deployment option you use:

a. Connection for a website accessible from the Internet

Connection config for a publicly accessible website is just a website URL, including protocol, hostname, and port. Default ports 80 and 443 can be omitted. E.g., connection: “http://qa.website.com:8080”

import type { Config } from '@userway/cicd-core'
 
export default {
  organization: 'userway',
  project: 'continuous-accessibility',
  token: process.env.USERWAY_TOKEN,
  connection: 'https://qa.website.com:8080',
} satisfies Config

b. Connection for a website accessible on a localhost

To configure a connection for a website running on localhost within your CI/CD infrastructure, you can utilize HTTP tunneling services like ngrok or localtunnel. These tools create secure tunnels to your local server, enabling external services to access your application during development and testing.

Using ngrok

Ngrok is a popular tool that establishes secure tunnels to localhost. To integrate ngrok into your configuration, you’ll need an ngrok authtoken, which can be obtained by signing up at ngrok.com. To get started, add the userway ngrok package to your project:

npm install --save-dev @userway/cicd-ngrok

Here’s an example configuration using ngrok:

import type { Config } from '@userway/cicd-core'
import { ngrokConnection } from '@userway/cicd-ngrok'
 
export default {
  organization: 'userway',
  project: 'continuous-accessibility',
  token: process.env.USERWAY_TOKEN,
  connection: ngrokConnection({
    addr: 8080,
    authtoken: process.env.NGROK_AUTHTOKEN,
  }),
  pages: [{ url: '/about.html' }],
} satisfies Config

For more options and detailed information, refer to the ngrok JavaScript SDK documentation.

Using localtunnel

Alternatively, you can use localtunnel, an open-source project that provides similar functionality without requiring an authtoken. To get started, add the userway localtunnel package to your project:

npm install --save-dev @userway/cicd-localtunnel

Here’s how to set up localtunnel in your configuration:

import type { Config } from '@userway/cicd-core'
import { localtunnelConnection } from '@userway/cicd-localtunnel'
 
export default {
  organization: 'userway',
  project: 'continuous-accessibility',
  token: process.env.USERWAY_TOKEN,
  connection: localtunnelConnection({
    port: 8080,
  }),
  pages: [{ url: '/about.html' }],
} satisfies Config

For more information on localtunnel, visit the localtunnel npm package page.

Custom Tunneling Script

If you prefer to implement a custom tunneling solution, you can write your own script to establish a tunnel to localhost. Ensure that your script verifies the local server’s availability before creating the tunnel.

Here’s an example configuration using a custom tunneling function:

import type { Config } from '@userway/cicd-core'
 
export default {
  organization: 'userway',
  project: 'continuous-accessibility',
  token: process.env.USERWAY_TOKEN,
  connection: async ({ logger, tcpPing }) => {
    const host = 'localhost'
    const port = 3000
 
    logger.debug(`Checking ${host}:${port}`)
    const isLocalhostRunning = await tcpPing(host, port)
 
    if (!isLocalhostRunning) {
      throw new Error('Localhost is not running')
    }
 
    return yourCustomTunnel(host, port)
  },
  pages: [{ url: '/about.html' }],
} satisfies Config

For a working example of a managed scan configuration via userway.config.js, visit the sample project repository.

3. Configure userway.config.js with pages

Now, you must update the userway.config.js file with the pages you wish to scan. Pages config is a list of objects, each with fields like url and devices. Assuming that we have selected option a. in the previous section, final userway.config.js can look like this one:

import type { Config } from '@userway/cicd-core'
export default {
   connection: 'https://qa.website.com:8080',
   pages: [
    { url: '/contacts/', devices: mobile, ... },
    { url: '/about-us/' },
    { url: '/blog/' }
   ]
} satisfies Config

4. Verify configuration

It is always a good idea to validate changes in the steps above before committing them to the repository. To verify if your managed scan configuration is correct - there are a few steps that can be performed on the local developer environment:

• Make all necessary changes described above
• Run scan locally:

export USERWAY_TOKEN=<YOUR-PROJECT-TOKEN>
npx userway

Make sure there are no errors and scan pass successfully

For more information about troubleshooting of @userway/cicd-cli tool refer to the documentation: https://docs.cicd.dev.userway.dev/get-started/troubleshooting

Prerequisites

• Node.js v16.20.2 or higher

Managed scan pricing

Please note, that UserWay-hosted scan requires activation of corresponding subscription.