Docs: Add javascript config file example
seanahern opened this issue · comments
Following the contribution guide, opening a discussion https://pa11y.org/contributing/developers/#requesting-features
Hi — Thanks for this great tool! It helps us automate a lot of this tracking using the CI tool. For this issue, I wanted to recommend adding a simple code example to the config section of the README, for JavaScript exports syntax.
Obvious to some but there are no spec or standard references when mentioning JavaScript as a config option to be passed in as a CLI param.
JS loading issue: #39
Basic auth issue: #57
Simple approach
Notes
- Noticed that most of the configuration detail docs reference the function call to use as reference instead of a config file
- JavaScript snippet could include more relevant content in the sample code, like the Basic auth example in #57, to illustrate purpose of using JavaScript instead of JSON
Excellent idea, @seanahern!
Here is a partial example:
//*** local variables used in exports
var site = 'http://localhost:4200';
var username = 'Pa11y Author';
var password = 'Pa11y Password';
var ignoreDefault = [
"WCAG2AAA.Principle1.Guideline1_4.1_4_3_F24.F24.FGColour", // check for inherited BG color to complement inline FG color
"WCAG2AAA.Principle1.Guideline1_4.1_4_6.G17.Fail", // insufficient contrast: 7:1
"WCAG2AAA.Principle1.Guideline1_4.1_4_6.G18.Fail", // insufficient contrast: 4.5:1
// mostly for menus with cdk-overlay-container, cdk-global-overlay
"WCAG2AAA.Principle1.Guideline1_4.1_4_10.C32,C31,C33,C38,SCR34,G206", // element has 'position: fixed'
];
var ignoreNotForm = [ ... ignoreDefault,
"WCAG2AAA.Principle1.Guideline1_3.1_3_1.H44.NotFormControl" // 'for' should point to form control (mat-select without control)
];
/**
* Configuration for Pa11y-ci.
*/
module.exports = {
// NOTE: defaults are OVERRIDDEN not extended
defaults : {
// chromeLaunchConfig executable path & arguments (use separate cache)
chromeLaunchConfig : {
executablePath : "/usr/lib64/chromium-browser/chromium-browser",
args : [ "--enable-logging=stderr", "--v=1" ],
},
// concurrency=1 so urls are sequential, with login first (if browser context is preserved)
concurrency : 1,
// hide elements (e.g., embedded ads) "#ads .sr-only [aria-role='presentation']"
// hideElements : [],
// ignore types (error, warning, notice) or rules: https://github.com/pa11y/pa11y/wiki/HTML-CodeSniffer-Rules
// - must be repeated in urls that override ignore
ignore : ignoreDefault,
// true to include non-actionable notices (false by default)
includeNotices : false,
// true to include non-actionable warnings (false by default)
includeWarnings : true,
// e.g., error, warning, or notice
level : "warning",
reporters : [ "cli", [ "json", { "fileName": ".pa11y/results.json" } ] ],
// rules (only used by htmlcs runner)
// rules : [],
// e.g., WCAG2A, WCAG2AA, WCAG2AAA (low to high), Section508 (deprecated)
standard : "WCAG2AAA",
// timeout (in msec) for an entire test run
timeout : 10000,
// false to preserve browser context
useIncognitoBrowserContext : false,
},
urls : [
// NOTE: /login should always be FIRST (if browser context is preserved)
{ url : `${site}/login`,
actions : [
"wait for element #login to be visible", "screen capture .pa11y/login0.png",
`set field #username to ${username}`,
`set field #password to ${password}`,
"click element #login",
"wait for element #appMenu to be visible", "screen capture .pa11y/login1.png",
],
},
{ ignore : ignoreNotForm,
url : `${site}/user-list`,
actions : [
"wait for element .mat-card-actions to be visible", "screen capture .pa11y/user-list0.png",
// IDEA: test button or other page element
],
},
{ ignore : ignoreNotForm,
url : `${site}/user-make`,
actions : [
"wait for element .mat-card-actions to be visible", "screen capture .pa11y/user-make0.png",
// edit, save, & delete user
"set field #username to Pa11y Username",
"set field #password to Pally Password",
"set field #reenter to Pally Password", "screen capture .pa11y/user-make1.png",
"click element #save",
"wait for path to not be /user-make", "screen capture .pa11y/user-make2.png",
"click element #delete",
"wait for element mat-dialog-actions button:first-child to be visible",
"click element mat-dialog-actions button:first-child",
"wait for path to be /user-list", "screen capture .pa11y/user-make3.png",
// return to /user-make since pa11y reports final url
`navigate to ${site}/user-make`,
"wait for element .mat-card-actions to be visible", "screen capture .pa11y/user-make4.png",
],
},
{ ignore : ignoreNotForm,
url : `${site}/user-edit/60a4e8bdd4f4370c310884f1`,
actions : [
"wait for element .mat-card-actions to be visible", "screen capture .pa11y/user-edit0.png",
// edit & cancel
"set field #username to Pa11y Username New",
"set field #password to Pally Password New",
"set field #reenter to Pally Password New", "screen capture .pa11y/user-edit1.png",
"click element #cancel",
"wait for path to be /user-list", "screen capture .pa11y/user-edit2.png",
// return to /user-edit since pa11y reports final url
`navigate to ${site}/user-edit/60a4e8bdd4f4370c310884f1`,
"wait for element .mat-card-actions to be visible", "screen capture .pa11y/user-edit3.png",
],
},
],
}; // end module.exports