Docs: Add javascript config file example

[seanahern]

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 Error running pa11y-ci against a url with basic authentication.  #57, to illustrate purpose of using JavaScript instead of JSON

[josebolos]

Excellent idea, @seanahern!

[kussmaul]

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