Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Issues with the current API

  • Multiple optional positional arguments in the checkA11y() method make it awkward to use and very difficult to extend. We have several open pull requests that are adding a new argument at the end.
  • Requires too much setup to have violations summary either in the terminal or JSON that could be supplied to another too.
  • Doesn’t support Cypress chaining in the checkA11y() method, and uses a custom context argument. This makes the usage less idiomatic and doesn’t allow integration with tools like Cypress Testing Library.
  • No way to define defaults for the checkA11y() method, we have to pass things like violationCallback in every call or create a custom command.

Related issues: #40, #49, #62, #67, #68

New API proposal

  1. Remove the context argument of the checkA11y() method, and rely on the Cypress chaining instead:
cy.checkA11y() // Check the whole document
cy.getByTestId('my-modal').checkA11y() // Check part of the document
  1. Replace the rest of the arguments with an optional object of the following shape:
interface CypressAxeOptions {
  axeOptions?: axe.RunOptions, // This used to be `options` argument
  shouldFail?: (violations: RunResults[], results: RunResults[]) => boolean,  // Replaces `includedImpacts` and `skipFailures`
  reporters?: Reporter[]

type Reporter = (results: RunResults[]) => void

interface RunResults {
  filename: string, // Test file
  label?: string, // Label passed to checkA11y
  results: axe.Result[]

The defaults are going to be:

  axeOptions: undefined,
  shouldFail: (violations) => violations.length > 0,  // Fail on any number of violations
  reporters: [

Reporters are replacing the violationCallback: they are more flexible, have access to both passes and violations, and you could have global reporters that would run after all tests, or pass a reporter for a separate checkA11y() method call. The default reporter is printing an overall summary after all tests.

  1. Add a new optional label to the checkA11y() method:
cy.checkA11y(options?: CypressAxeOptions, label?: string)

Similar to labels describe() or it() methods, to identify results of a particular call.

  1. Add a new method to define defaults:
cy.configureCypressAxe(options: CypressAxeOptions)

It should accept the same object as the checkA11y() method, and set default values that could be overwritten in checkA11y().

I hope this covers all the use cases we have. I’m not sure that all the names are clear, so if you have any feedback, leave a comment 😉

Issue Analytics

  • State:open
  • Created 3 years ago
  • Reactions:7
  • Comments:23 (6 by maintainers)

github_iconTop GitHub Comments

kristina-hagercommented, Nov 17, 2020

Well, I suppose reasonable people may disagree on this matter.

However, all the extra functionality this package wraps may be ignored by the user especially if the following changes can be included:

  • return the ‘results’ object from the function (this object can be filtered w/ the additional, optional features like ‘minImpact’)
  • change the argument skipFailures (optional, defaults to false) to failOnViolations (optional, defaults to false). This way users can opt in to having the assert coded up for them. However, users interested in inspecting the results object themselves and doing their own asserts have an easy path.

In addition, this change would bring this library in line with the majority of other axe-core extensions that do not provide such features and do not do the assert for the user while allowing the additional bells/whistles that some find appealing to remain.

kyrstenkellycommented, Nov 19, 2020

I am a fan of this new API proposal. I agree that returning all results is useful in case someone wants to do something more custom, but I also personally appreciate having a nice default reporter so I don’t have to put in extra effort there.

Read more comments on GitHub >

github_iconTop Results From Across the Web

RFC 2614 - An API for Service Location - IETF Datatracker
RFC 2614 Service Location API June 1999 1. Introduction The Service Location API is designed for standardized access to the Service Location Protocol...
Read more >
RFC 7807: Problem Details for HTTP APIs
RFC 7807 Problem Details March 2016 Table of Contents 1. ... Defining New Problem Types When an HTTP API needs to define a...
Read more >
A collection of standards and specifications, that help make fantastic HTTP/REST APIs. Don't reinvent the wheel, use fantastic wheels, hashed out by experts ......
Read more >
New REST API RFC - Koha Wiki
5 API Protocol Specification; 6 Guidelines/rules for the new API ... (Search for "RFC: /svc/ API"); Copy of initial requests from EBSCO ...
Read more >
RFC 9205 - Building Protocols with HTTP
... to create HTTP-based APIs. This document specifies best practices for writing specifications that use HTTP to define new application protocols.
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Post

No results found

github_iconTop Related Hashnode Post

No results found