Set up the environment outside the testsuite itself

It feels like a better practice. Also provided comments in some places
that needed them.

Author: eliericha

.vscode/launch.json

@@ -49,6 +49,24 @@
             // tests when debugging
             "MOCHA_TIMEOUT": "0"
          },
+         // Below we make the executables of node modules visible to the tests.
+         // In particular, vscode-tmgrammar-snap is used for syntax highlighting
+         // tests.
+         "windows": {
+            "env": {
+               "PATH": "${workspaceFolder}/integration/vscode/ada/node_modules/.bin;${env:PATH}"
+            }
+         },
+         "osx": {
+            "env": {
+               "PATH": "${workspaceFolder}/integration/vscode/ada/node_modules/.bin:${env:PATH}"
+            }
+         },
+         "linux": {
+            "env": {
+               "PATH": "${workspaceFolder}/integration/vscode/ada/node_modules/.bin:${env:PATH}"
+            }
+         },
          "preLaunchTask": "npm: pretest"
       },
       {
@@ -76,6 +94,24 @@
             // integration/vscode/ada/test/suite/highlighting.test.ts
             "MOCHA_ALS_UPDATE": "1"
          },
+         // Below we make the executables of node modules visible to the tests.
+         // In particular, vscode-tmgrammar-snap is used for syntax highlighting
+         // tests.
+         "windows": {
+            "env": {
+               "PATH": "${workspaceFolder}/integration/vscode/ada/node_modules/.bin;${env:PATH}"
+            }
+         },
+         "osx": {
+            "env": {
+               "PATH": "${workspaceFolder}/integration/vscode/ada/node_modules/.bin:${env:PATH}"
+            }
+         },
+         "linux": {
+            "env": {
+               "PATH": "${workspaceFolder}/integration/vscode/ada/node_modules/.bin:${env:PATH}"
+            }
+         },
          "preLaunchTask": "npm: pretest"
       },
       {

integration/vscode/ada/src/extension.ts

@@ -109,7 +109,11 @@ export class ContextClients {
 }
 
 export async function activate(context: vscode.ExtensionContext): Promise<void> {
+    // Create an output channel for the extension. There are dedicated channels
+    // for the Ada and Gpr language servers, and this one is a general channel
+    // for non-LSP features of the extension.
     mainLogChannel = vscode.window.createOutputChannel('Ada Extension');
+
     context.subscriptions.push(
         vscode.commands.registerCommand('ada.showExtensionOutput', () => mainLogChannel.show())
     );

integration/vscode/ada/test/suite/highlighting.test.ts

@@ -168,6 +168,10 @@ async function testSemanticHighlighting(docUri: vscode.Uri) {
     assertEqualToFileContent(actual, expectedUri);
 }
 
+/**
+ * This function queries the VS Code API for the Ada extension and waits until
+ * it is activated.
+ */
 async function activate(): Promise<void> {
     const ext = vscode.extensions.getExtension('AdaCore.ada');
     if (ext !== undefined) {
@@ -177,13 +181,26 @@ async function activate(): Promise<void> {
     }
 }
 
+/**
+ *
+ * @param path - path of a file or directory relative to the TestWorkspace
+ * workspace.
+ * @returns a Uri representing the full path to the given relative workspace
+ * path
+ */
 function getDocUri(path: string): vscode.Uri {
     assert(vscode.workspace.workspaceFolders !== undefined);
     return vscode.Uri.joinPath(vscode.workspace.workspaceFolders[0].uri, path);
 }
 
 const extensionRootPath = path.resolve(__dirname, '../../../');
 
+/**
+ * A type representing the two TextMate grammars available in the repository.
+ * The values match directory names in the extension source directory. The
+ * 'syntaxes' grammar is the one currently in use in the package.json, while the
+ * 'advanced' one is an experimental alternative that is not used in production.
+ */
 type Syntaxes = 'syntaxes' | 'advanced';
 
 /**

integration/vscode/ada/test/suite/index.ts

@@ -4,11 +4,6 @@ import path, { resolve } from 'path';
 import { env } from 'process';
 
 export function run(): Promise<void> {
-    // Make package executables visible
-    const extensionRootPath = path.resolve(__dirname, '../../../');
-    const nodeModulesBin = path.join(extensionRootPath, 'node_modules', '.bin');
-    process.env.PATH = `${nodeModulesBin}${path.delimiter}${process.env.PATH as string}`;
-
     const mochaOptions: MochaOptions = {
         ui: 'tdd',
         color: true,
@@ -30,6 +25,9 @@ export function run(): Promise<void> {
             mocha.addFile(resolve(testsRoot, file));
         }
         try {
+            // This variable is set in the launch configuration (launch.json) of
+            // the VS Code workspace to allow debugging without triggering test
+            // timeouts.
             if (env['MOCHA_TIMEOUT']) {
                 mocha.timeout(env['MOCHA_TIMEOUT']);
             }

integration/vscode/ada/test/suite/utils.ts

@@ -28,7 +28,9 @@ export function assertEqualToFileContent(actual: string, expectedUri: vscode.Uri
 /**
  *
  * @returns true if the testsuite is running in update mode, i.e. the
- * environment variable MOCHA_ALS_UPDATE is set
+ * environment variable MOCHA_ALS_UPDATE is set. For example, the VS Code
+ * workspace of this repository provides a launch configuration with that
+ * environment variable set to allow quickly updating test references.
  */
 export function update(): boolean {
     return process.env.MOCHA_ALS_UPDATE ? true : false;