Skip to content

Accessibility Testing with attest

Dave edited this page Nov 14, 2018 · 4 revisions

Attest Setup in a polymer web component at D2L:

Installation

The attest package is available through the D2L artifactory repo.

Install NPM package

You can install the package via npm. First you will need to login

>npm login --registry=https://d2lartifacts.artifactoryonline.com/d2lartifacts/api/npm/attest/

Note that the trailing slash is important to have.

Once you are logged in you can install attest

>npm install attest --registry=https://d2lartifacts.artifactoryonline.com/d2lartifacts/api/npm/attest/

Creating a test

Assuming that you already have tests setup, you just need to import the attest.js file by adding a script call to the each html definition for your tests

<script src="../../node_modules/attest/attest.js"></script>

Once you have done that you can create a test in your .js file as you usually would. To actually run the scanner just call attest.run() - See an example test below.

Promises

I found it worked best to use promises in the attest calls. If you return a promise to Mocha it will automatically handle it without you needing to do any extra work. This results in a command that looks like this:

return attest.run().then(
	function(results){
		expect(results.violations.length).to.equal(0);
	})

Any failures in expect will be passed up to the test and will appropriately fail the test.

Rules

The attest.run() function takes in a few options. You can filter it down to only scan a particular element and you can also pass in some modification to the rules that it will check for. I found that I needed to ignore a few rules that applied to full pages. Since a component is meant to be included as a part of a page we don't need to ensure that we have a heading one in them for example.

I created some rules options to ignore rules we didn't need to check like this:

var rules_options = {
	"rules":{
		'html-has-lang':{enabled:false},
		'landmark-one-main':{enabled:false},
		'page-has-heading-one':{enabled:false},
		'region':{enabled:false}
	}
}

And then gave those rules to the attest runner:

return attest.run(rules_options)

One other thing I added into my test was some debug output if they failed. This way you can more easily figure out what you need to do to address the failures. I did this by chaining a .catch onto the then and console logging the violations in the case of the test failing.

So putting it all together a test for me looked this this:

function(){
	//disable a few rules that don't apply to our component
	var rules_options = {
		"rules":{
			'html-has-lang':{enabled:false},
			'landmark-one-main':{enabled:false},
			'page-has-heading-one':{enabled:false},
			'region':{enabled:false}
		}
	}
	let my_res = '_UNSET';
	return attest.run(rules_options).then(
		function(results){
			my_res = results;
			expect(results.violations.length).to.equal(0);
		})
		.catch(
			function (err){
				var i;
				for (i=0; i < my_res.violations.length; i++) {
					console.log(JSON.stringify(my_res.violations[i]));
				}
				throw err
			}
		)};

Running the tests

Since we setup the tests inside the test framework we were already using to run our existing unit tests, we could just run them the same way we would run all your other polymer tests.

Debugging

If you set the test up with a debugging catch the way I did you should see information that looks something like this in the console log. Note that in order to see this you will need to make sure you are not running your tests in headless mode and you will also want to add the -p option to the test runner so that it will not close down the browser when the tests are done

>polymer test -p

debug

The debug output shows you what error(s) there were and what you might need to do to fix it. It also has a link to the dequeuniversity that explains what rule has failed and gives you further information that may be helpful in understanding accessibility failures

Running on Travis

The attest package comes from deque, but we have been able to host it as a remote repo in the D2L artifactory. However, it has not been setup with the @D2L scope and so there are some important things to note.

  1. You cannot have attest in your package file (i.e. you need to make sure you don't commit with attest added to your dependencies in the project.json file). If you have it in there, npm install will attempt to install it from the npm public repo and the build will fail since it is not there
  2. as a corollary to this, you will need to 'manually' call the install of attest.

Setting up Travis

Many of our components are in public repos, so I would suggest using environment variables for the artifactory api keys or passwords. You can easily do this by going to the Travis settings and entering a name and value in the Environment Variables section. Be sure to leave the display value in build log toggle off. This will create a variable you can use in your build scripts, but will not allow others without settings access to see what your actual token is.

For all of this, or course, you will need access to an account for artifactory that you can use on travis. I think most teams have one already, but if not you will have to follow up with release engineering to get one.

.travis.yml

Once you have your password set up as an environment variable on Travis, you need to create a script to use it. I edited the .travis.yml file in our component to include this line

- curl -umango-readonly:${MANGO_READONLY_PWD} https://d2lartifacts.artifactoryonline.com/d2lartifacts/api/npm/attest/auth/attest > .npmrc

in the before_script: section. This will create a .npmrc file with your authentication settings in it. You would of course need to modify the curl command here to include the user name of the build user you have, and replace the password env var with the one you setup for your build.

The only thing left to do is to call the install command for attest. I did that by adding this line (also in the before_script section) to the .travis.yml file.

- npm install attest --registry=https://d2lartifacts.artifactoryonline.com/d2lartifacts/api/npm/attest/

Don't forget that if you installed attest locally it will probably have been added to the dependencies section of your package.json file. You will want to remove it from there so that travis doesn't try to install it as a project dependency since that will fail.

You can’t perform that action at this time.