docs: update docs on running tests (#3556)

* docs: update docs on running tests

* Update doc/developer-guide.md

Co-authored-by: Dan Bowling <[email protected]>

* suggestion

* non-headless

* readmes

* typo

* better link

* typo

* update

* typo

* wording

* major typo

Co-authored-by: Dan Bowling <[email protected]>

doc/developer-guide.md

@@ -7,6 +7,7 @@ Axe 3.0 supports open Shadow DOM: see our virtual DOM APIs and test utilities fo
 1. [Getting Started](#getting-started)
    1. [Environment Pre-requisites](#environment-pre-requisites)
    1. [Building axe.js](#building-axejs)
+   1. [Watching for Changes](#watching-for-changes)
    1. [Running Tests](#running-tests)
    1. [API Reference](#api-reference)
    1. [Supported CSS Selectors](#supported-css-selectors)
@@ -37,18 +38,56 @@ Axe 3.0 supports open Shadow DOM: see our virtual DOM APIs and test utilities fo
 
 To build axe.js, simply run `npm run build` in the root folder of the axe-core repository. axe.js and axe.min.js are placed into the root folder.
 
+## Watching for Changes
+
+You can watch for changes and automatically build axe and run relevant tests using `npm run develop`. Once run, any changes to files inside the [lib directory](../lib) will rebuild axe. After axe is built, it will try to run the relevant tests for the files changed. If you change a file inside the [test directory](../test) it will run the tests for the file changed.
+
+Changes to files in the [full integration test directory](../test/integration/full) will not run the tests. This is because these tests require the browser to navigate to the page directly, which is something Mocha / Karma does not support.
+
+**Note:** We are still working on knowing which tests are relevant to the changed file so this may not correctly run tests every time. In these cases you should run the tests manually. If you encounter a test that does not run when a relevant file is changed, please [open an issue](https://github.com/dequelabs/axe-core/issues).
+
 ### Running Tests
 
-To run all tests from the command line you can run `npm test`, which will run all unit and integration tests using headless chrome and Selenium Webdriver.
+To run all tests from the command line you can run `npm test`, which will run all unit and integration tests using headless Chrome. Having axe built and up-to-date is required in order to run tests. If you update files inside the [lib directory](../lib) you will need to rebuild axe before running tests.
+
+You can scope which set of tests to run through various npm scripts: 
+
+- `npm run test:unit:core` - Run only [core tests](../test/core/)
+- `npm run test:unit:commons` - Run only [commons tests](../test/commons/)
+- `npm run test:unit:checks` - Run only [check tests](../test/checks/)
+- `npm run test:unit:rule-matches` - Run only [rule matches](../test/rule-matches/)
+- `npm run test:unit:integration` - Run only [rule integration tests](../test/integration/rules/)
+- `npm run test:unit:virtual-rules` - Run only [virtual rule tests](../test/integration/virtual-rules)
+- `npm run test:unit:api` - Run only [api tests](../test/integration/api)
+
+There are also a set of tests that are not considered unit tests that you can run through various npm scripts:
+
+- `npm run test:act` - Run the [act tests](../test/act-mapping)
+- `npm run test:apg` - Run the [aria-practices tests](../test/aria-practices)
+- `npm run test:examples` - Run the [example tests](../doc/examples)
+- `npm run test:locales` - Run the [local tests](../test/test-locales.js)
+- `npm run test:node` - Run the [node tests](../test/node)
+- `npm run test:tsc` - Run the [typescript tests](../typeings/axe-core)
+
+Additionally, you can [watch for changes](#watching-for-changes) to files and automatically run the relevant tests.
+
+If you need to debug a test in a non-headless browser, you can run `npm run test:debug` which will run the Karma tests in non-headless Chrome. You can also navigate to the newly opened page using any supported browser. 
+
+You can scope which set of tests to debug by passing the `testDirs` argument. Supported values are:
+
+- `core`
+- `commons`
+- `checks`
+- `rule-matches`
+- `integration`
+- `virtual-rules`
+- `api`
+
+Example:
 
-You can also load tests in any supported browser, which is helpful for debugging. Tests require a local server to run, you must first start a local server to serve files. You can use Grunt to start one by running `npm start`. Once your local server is running you can load the following pages in any browser to run tests:
+- `npm run test:debug -- testDirs=core`
 
-1. [Core Tests](../test/core/)
-2. [Commons Tests](../test/commons/)
-3. [Check Tests](../test/checks/)
-4. [Rule Matches](../test/rule-matches/)
-5. [Integration Tests](../test/integration/rules/)
-6. There are additional tests located in [test/integration/full/](../test/integration/full/) for tests that need to be run against their own document.
+Lastly, you can run the [full integration tests](../test/integration/full) by starting a local server by running `npm start`. Once started, you can open any supported browser and navigate to any test in the full integration tests directory.
 
 ### API Reference
 

test/act-mapping/README.md

@@ -0,0 +1,11 @@
+# ACT Mapping
+
+Contains information on how to run axe-core rules against the [ACT-Rules](https://act-rules.github.io/). Each ACT rule suite is its own JSON file (named after the axe-core rule to run) which contains the following information:
+
+- `id` - string(required). The ACT Rule Id
+- `title` - string(required). The title of the test taken from the ACT rule name. Used in the `describe` block of the test suite.
+- `axeRules` - array(required). List of axe-core rules to run
+
+When the tests are run using `npm run test:act`, each JSON file is converted into a test suite file using [Karmas preprocessor](https://karma-runner.github.io/latest/config/preprocessors.html) and [runner.js](./runner.js) as the test suite template. 
+
+You can run and debug the tests in a non-headless browser by running `npm run test:act:debug`.

test/aria-practices/README.md

@@ -0,0 +1,5 @@
+# ARIA Practices
+
+Runs axe-core on the examples provided in the [ARIA Practices](https://www.w3.org/WAI/ARIA/apg/). To run the tests, run `npm run test:apg`. 
+
+If certain axe-core rules should not be run on certain pages, you can disable those rules using the `disabledRules` object in [apg.spec.js](./apg.spec.js). Please be sure to add a comment as to why the rule should not be run. If applicable, please open an issue in either axe-core or [aria-practices](https://github.com/w3c/aria-practices) and link to the issue in the code so that we can track the issue and know when we can run the rule again.

test/integration/full/README.md

@@ -0,0 +1,13 @@
+# Full Integration Tests
+
+Full Integration tests are tests that require a complete HTML page rather than testing content inside of a fixture element. Full integration tests are run using a non-headless browser and requires a page navigation to the relevant HTML test file.
+
+To run the full integration tests, run `npm run test:integration`. Different browsers can be used using various npm scripts:
+
+- `npm run test:integration:chrome` - Run the tests using Chrome (default when using `test:integration`)
+- `npm run test:integration:firefox` - Run the tests using Firefox
+- `npm run test:integration:ie` - Run the tests using Internet Explorer (requires running on Windows machine)
+
+Because the full integration tests are not run using Mocha, Mocha styles and scripts, Chai, axe-core, [testutils.js](../../tesstutils.js), and the [adapter.js](../adapter.js) file will need to be loaded on the page.
+
+If the Mocha output would interfere with the axe-core results, you can load the [no-ui-reporter.js](../no-ui-reporter.js) to hide the Mocha test output in the browser UI and instead report the results in the browsers devtools console.

test/integration/rules/README.md

@@ -0,0 +1,17 @@
+# Rule Integration Tests
+
+Rule Integration tests take an HTML snippet file and runs an axe-core rule against it. The results for the run are then compared against the companion JSON file to ensure that every node returns as the expected result (passes, violation, incomplete, inapplicable).
+
+To run the rule integration tests, run `npm run test:unit:integration`. You can run and debug the tests in a non-headless browser by running `npm run test:debug -- testDirs=integration`.
+
+When the tests are run, each JSON file is converted into a test suite file using [Karmas preprocessor](https://karma-runner.github.io/latest/config/preprocessors.html) and [runner.js](./runner.js) as the test suite template. 
+
+The JSON file for a rule integration test contains the following information:
+
+- `description` - string(required). The title of the test. Used in the `describe` block of the test suite
+- `rule` - string(required) The axe-core rule to run
+- `violations` array(optional). List of axe-core selectors of nodes that should return as Violations
+- `passes` array(optional). List of axe-core selectors of nodes that should return as Passes
+- `incomplete` array(optional). List of axe-core selectors of nodes that should return as Needs Review
+
+The JSON file should have at least one of the `violations`, `passes`, or `incomplete` arrays. Inapplicable results are not listed as the test will fail if any node is found in one of the 3 arrays that is not explicitly listed.