New API RFC
See original GitHub issueIssues 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 customcontext
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 likeviolationCallback
in every call or create a custom command.
Related issues: #40, #49, #62, #67, #68
New API proposal
- Remove the
context
argument of thecheckA11y()
method, and rely on the Cypress chaining instead:
cy.checkA11y() // Check the whole document
cy.getByTestId('my-modal').checkA11y() // Check part of the document
- 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: [
require('cypress-axe/cli-reporter')
]
}
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.
- 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.
- 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:
- Created 3 years ago
- Reactions:7
- Comments:23 (6 by maintainers)
Top 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 >Standards.REST
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 >Top Related Medium Post
No results found
Top Related StackOverflow Question
No results found
Troubleshoot Live Code
Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start FreeTop Related Reddit Thread
No results found
Top Related Hackernoon Post
No results found
Top Related Tweet
No results found
Top Related Dev.to Post
No results found
Top Related Hashnode Post
No results found
Top GitHub Comments
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:
skipFailures (optional, defaults to false)
tofailOnViolations (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.
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.