diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000000..e189436e98 --- /dev/null +++ b/.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}/*" + } + } + ] +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d692677a24..b2461d4800 100644 --- a/CONTRIBUTING.md +++ b/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:*`: diff --git a/doc/developer-guide.md b/doc/developer-guide.md index 5b3233770f..a4eff80582 100644 --- a/doc/developer-guide.md +++ b/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: diff --git a/package.json b/package.json index 9983caddec..0dda5cb33b 100644 --- a/package.json +++ b/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", diff --git a/test/integration/rules/README.md b/test/integration/rules/README.md index d9a6e54f48..5543d275db 100644 --- a/test/integration/rules/README.md +++ b/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. diff --git a/test/karma.conf.js b/test/karma.conf.js index b4036b908b..ff0f2ebf7b 100644 --- a/test/karma.conf.js +++ b/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] + } } }); };