chore: set up vscode config to attach to test:debug (#4430)

This updates the existing `test:debug` run script to pass
`--remote-debugging-port` to chrome, and then sets up a vscode launch
profile to connect to that port.

No QA required.

.vscode/launch.json

@@ -0,0 +1,18 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "chrome",
+      "request": "attach",
+      "name": "Attach to Karma test:debug",
+      "address": "localhost",
+      "port": 9765, // keep in sync with debugPort in karma.conf.js
+      "webRoot": "${workspaceFolder}",
+      "sourceMaps": true,
+      "sourceMapPathOverrides": {
+        "*": "${webRoot}/*",
+        "base/*": "${webRoot}/*"
+      }
+    }
+  ]
+}

CONTRIBUTING.md

@@ -162,7 +162,7 @@ If you need to debug the unit tests in a browser, you can run:
 npm run test:debug
 ```
 
-This will start the Karma server and open up the Chrome browser. Click the `Debug` button to start debugging the tests. You can also navigate to the listed URL in your browser of choice to debug tests using that browser.
+This will start the Karma server and open up the Chrome browser. Click the `Debug` button to start debugging the tests. You can either use that browser's debugger or attach an external debugger on port 9765; [a VS Code launch profile](./.vscode/launch.json) is provided. You can also navigate to the listed URL in your browser of choice to debug tests using that browser.
 
 Because the amount of tests is so large, it's recommended to debug only a specific set of unit tests rather than the whole test suite. You can use the `testDirs` argument when using the debug command and pass a specific test directory. The test directory names are the same as those used for `test:unit:*`:
 

doc/developer-guide.md

@@ -71,7 +71,7 @@ There are also a set of tests that are not considered unit tests that you can ru
 
 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.
+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 either use that browser's debugger or attach an external debugger on port 9765; [a VS Code launch profile](../.vscode/launch.json) is provided. 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:
 

package.json

@@ -80,7 +80,7 @@
     "test": "npm run test:tsc && run-s \"test:unit:* -- {@}\" --",
     "test:tsc": "tsc",
     "test:unit": "karma start test/karma.conf.js",
-    "test:debug": "npm run test:unit -- --no-single-run --browsers=Chrome",
+    "test:debug": "npm run test:unit -- --no-single-run --browsers=ChromeDebugging",
     "test:unit:core": "npm run test:unit -- testDirs=core",
     "test:unit:commons": "npm run test:unit -- testDirs=commons",
     "test:unit:rule-matches": "npm run test:unit -- testDirs=rule-matches",

test/integration/rules/README.md

@@ -2,7 +2,7 @@
 
 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`.
+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`. You can either use that browser's debugger or attach an external debugger on port 9765; [a VS Code launch profile](../../../.vscode/launch.json) is provided.
 
 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.
 

test/karma.conf.js

@@ -11,6 +11,7 @@ var testDirs = [
   'virtual-rules'
 ];
 var testFiles = [];
+var debugPort = 9765; // arbitrary, sync with .vscode/launch.json
 var args = process.argv.slice(2);
 
 args.forEach(function (arg) {
@@ -23,6 +24,10 @@ args.forEach(function (arg) {
   else if (parts[0] === 'testFiles') {
     testFiles = parts[1].split(',');
   }
+  // pattern: debugPort=1234
+  else if (parts[0] === 'debugPort') {
+    debugPort = parseInt(parts[1], 10);
+  }
 });
 
 var testPaths = [];
@@ -108,6 +113,12 @@ module.exports = function (config) {
         timeout: 4000,
         reporter: 'html'
       }
+    },
+    customLaunchers: {
+      ChromeDebugging: {
+        base: 'Chrome',
+        flags: ['--remote-debugging-port=' + debugPort]
+      }
     }
   });
 };