Improve debugging experience (#933)

* Enable source maps for easier debugging

* Add VS Code config for debugging execution tests

* Enable debugging comparison tests

* Update docs

* Fix webpack execution tests

.gitignore

@@ -7,7 +7,6 @@
 bundle.js
 npm-debug.log
 /.test/
-/.vscode/
 /test/execution-tests/**/typings
 !/test/**/expectedOutput-*/**
 /**/node_modules

.npmignore

@@ -13,3 +13,4 @@ CONTRIBUTING.md
 Dockerfile
 HISTORY.md
 RELEASING.md
+*.js.map

.vscode/launch.json

@@ -0,0 +1,40 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Run open execution test",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": [
+        "run",
+        "execution-tests",
+        "--",
+        "--single-test",
+        "${fileDirname}",
+        "--debug"
+      ],
+      "console": "integratedTerminal",
+      "port": 5858
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Run open comparison test",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": [
+        "run",
+        "comparison-tests",
+        "--",
+        "--single-test",
+        "${fileDirname}",
+        "--debug"
+      ],
+      "console": "integratedTerminal",
+      "port": 5858
+    }
+  ]
+}

CONTRIBUTING.md

@@ -37,10 +37,27 @@ To read about the execution test pack take a look [here](test/execution-tests/RE
 
 ## Debugging
 
-To debug ts-loader itself:
+### Debugging tests
 
-```
+If you’re using VS Code, set breakpoints anywhere in `src`. Open any file inside the comparison test or execution test you want to debug, then, in the debug pane, select “Run open comparison test” or “Run open execution test.”
+
+If you’re not using VS Code, simply adding `--debug` to either a `yarn run comparison-tests` or `yarn run execution-tests` will pause before each test (this is best combined with `--single-test`), allowing you to attach to the node process on port 5858 with your favorite debugger.
+
+### Debugging ts-loader installed from npm in your own Webpack project
+
+```sh
 node --inspect-brk node_modules/webpack/bin/webpack.js --config webpack.dev.js # Obviously configure this depending upon your project setup
 ```
 
-Then put a breakpoint in `node_modules/ts-loader/dist/index.js`, and debug in VS Code with "Attach to Node Process". The dist is JS compiled from TS, but it’s still pretty readable.
+Then put a breakpoint in `node_modules/ts-loader/dist/index.js`, and debug in VS Code with "Attach to Node Process". The dist is JS compiled from TS, but it’s still pretty readable.
+
+### Debugging a local, cloned copy of ts-loader in your own Webpack project
+
+Just like the steps above, except substituting a local copy of ts-loader for the one in node_modules:
+
+1. In `ts-loader`, run `yarn build`
+2. Still in `ts-loader`, run `npm link`
+3. In your own Webpack project directory, run `npm link ts-loader`. There’s now a chain of symlinks from `node_modules/ts-loader` to your cloned copy built from source.
+4. Repeat the steps above in “Debugging ts-loader installed from npm...” except now, you can take advantage of source maps, so you can set breakpoints in `ts-loader/src` instead of `ts-loader/dist`.
+5. If you want to try making changes to `ts-loader`, make changes and then repeat steps 1 and 4—no need to re-run the `npm link` steps.
+6. Run `npm unlink ts-loader` in your own project directory to remove the symlink when you’re done.

src/tsconfig.json

@@ -10,6 +10,7 @@
     "moduleResolution": "node",
     "declaration": true,
     "outDir": "../dist",
-    "declarationDir": "../dist/types"
+    "declarationDir": "../dist/types",
+    "sourceMap": true
   }
 }

test/comparison-tests/README.md

@@ -74,4 +74,8 @@ patch0 is applied:
 
 ## Flaky tests
 
-Some of the tests in the pack are flaky.  For the most part the failures they occasionally experience are not significant.  If you want a test to be allowed to fail without failing the overall build whilst still seeing the output then place a file with the name `_FLAKY_` in the root of that particular test.
+Some of the tests in the pack are flaky.  For the most part the failures they occasionally experience are not significant.  If you want a test to be allowed to fail without failing the overall build whilst still seeing the output then place a file with the name `_FLAKY_` in the root of that particular test.
+
+## Debugging
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md#debugging).

test/comparison-tests/run-tests.js

@@ -41,7 +41,7 @@ function runTests() {
   const testDir = __dirname;
 
   if (singleTestToRun) {
-    if (runTestAsChildProcess(singleTestToRun)) {
+    if (runTestAsChildProcess(getTestNameFromPath(singleTestToRun))) {
       passingTests.push(singleTestToRun);
     } else {
       failingTests.push(singleTestToRun);
@@ -107,15 +107,33 @@ function runTests() {
   }
 }
 
+/** @param {string} testNameOrPath */
+function getTestNameFromPath (testNameOrPath) {
+  var tsLoaderPath = path.resolve(__dirname, '../..');
+  var tsLoaderBasename = path.basename(tsLoaderPath);
+  var comparisonTestsRelativeRoot = path.relative(tsLoaderPath, __dirname);
+  var comparisonTestsAbsoluteRoot = path.join(tsLoaderPath, comparisonTestsRelativeRoot);
+  // It wasn’t a path in comparison-tests; assume it was a test name
+  if (testNameOrPath.indexOf(path.join(tsLoaderBasename, comparisonTestsRelativeRoot)) === -1) {
+      return testNameOrPath;
+  }
+  // E.g. projectReferences/lib/index.ts
+  var testPathRelativeToComparisonTests = path.relative(comparisonTestsAbsoluteRoot, testNameOrPath);
+  return testPathRelativeToComparisonTests.split(path.sep)[0];
+}
+
 /**
  * Run test isolated in a child process
  *
  * @param {string} testName
  */
 function runTestAsChildProcess(testName) {
   const testToRun = ' --test-to-run ' + testName;
+  const debug = process.argv.indexOf('--debug') > -1;
   const testCommand =
-    'mocha --reporter spec test/comparison-tests/create-and-execute-test.js ' +
+    'mocha --reporter spec ' +
+    (debug ? '--inspect-brk=5858 ' : '') +
+    'test/comparison-tests/create-and-execute-test.js ' +
     testToRun;
 
   try {

test/execution-tests/README.md

@@ -58,3 +58,5 @@ It's pretty handy to be able to debug tests; for that reason you can run a singl
 `yarn run execution-tests -- --single-test nameOfTest --watch`
 
 Then you can fire up http://localhost:9876/ and the world's your oyster.
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md#debugging) for more information on debugging.

test/execution-tests/run-tests.js

@@ -90,7 +90,22 @@ function isNotBabelTest (testName) {
     return true;
 }
 
+function getTestNameFromPath (testNameOrPath) {
+    var tsLoaderPath = path.resolve(__dirname, '../..');
+    var tsLoaderBasename = path.basename(tsLoaderPath);
+    var executionTestsRelativeRoot = path.relative(tsLoaderPath, __dirname);
+    var executionTestsAbsoluteRoot = path.join(tsLoaderPath, executionTestsRelativeRoot);
+    // It wasn’t a path in execution-tests; assume it was a test name
+    if (testNameOrPath.indexOf(path.join(tsLoaderBasename, executionTestsRelativeRoot)) === -1) {
+        return testNameOrPath;
+    }
+    // E.g. 3.0.1_projectReferences/lib/index.ts
+    var testPathRelativeToExecutionTests = path.relative(executionTestsAbsoluteRoot, testNameOrPath);
+    return testPathRelativeToExecutionTests.split(path.sep)[0];
+}
+
 function runTests(testName) {
+    testName = getTestNameFromPath(testName);
     console.log('\n-------------------------------------------------------------------------\n');
     console.log('RUNNING THIS TEST SUITE: ' + testName +'\n\n');
 
@@ -103,6 +118,7 @@ function runTests(testName) {
     }
 
     var karmaConfPath = path.join(testPath, 'karma.conf.js');
+    var debug = process.argv.indexOf('--debug') > -1;
 
     if (pathExists(path.join(testPath, 'shrinkwrap.yaml'))) {
         console.log('npx pnpm install into ' + testPath);
@@ -113,14 +129,18 @@ function runTests(testName) {
     }
 
     try {
-        if (pathExists(path.join(testPath, 'karma.conf.js'))) {
+        if (pathExists(karmaConfPath)) {
+            var karmaPath = path.resolve(__dirname, '../../node_modules/karma/bin/karma');
             var singleRunOrWatch = watch ? '' : ' --single-run';
-            execSync('karma start --reporters mocha' + singleRunOrWatch + ' --browsers ChromeHeadlessNoSandbox', { cwd: testPath, stdio: 'inherit' });
+            var program = debug ? 'node --inspect-brk=5858 ' + karmaPath : 'karma';
+            execSync(program + ' start --reporters mocha' + singleRunOrWatch + ' --browsers ChromeHeadlessNoSandbox', { cwd: testPath, stdio: 'inherit' });
 
             passingTests.push(testName);
         } else {
             console.log('running webpack compilation');
-            execSync('webpack --bail', { cwd: testPath, stdio: 'inherit' });
+            var webpackPath = path.resolve(__dirname, '../../node_modules/webpack/bin/webpack.js');
+            var program = debug ? 'node --inspect-brk=5858 ' + webpackPath : 'webpack';
+            execSync(webpackPath + ' --bail', { cwd: testPath, stdio: 'inherit' });
             passingTests.push(testName);
         }
     }