Merge pull request #1797 from github/jest-migration/docs

Add documentation for running a single test

Author: koesie10

.vscode/extensions.json

@@ -6,6 +6,7 @@
     "amodio.tsl-problem-matcher",
     "dbaeumer.vscode-eslint",
     "esbenp.prettier-vscode",
+    "firsttris.vscode-jest-runner",
     "Orta.vscode-jest",
   ],
   // List of extensions recommended by VS Code that should not be recommended for users of this workspace.

.vscode/settings.json

@@ -42,6 +42,13 @@
     "LANG": "en-US",
     "TZ": "UTC"
   },
+  // Uncomment to debug integration tests
+  // "jestrunner.debugOptions": {
+  //   "attachSimplePort": 9223,
+  //   "env": {
+  //     "VSCODE_WAIT_FOR_DEBUGGER": "true",
+  //   }
+  // },
   "[typescript]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode",
     "editor.formatOnSave": true,

CONTRIBUTING.md

@@ -150,6 +150,32 @@ The CLI integration tests require the CodeQL standard libraries in order to run
 
 3. Run the VSCode task from the "Run and Debug" view called _Launch Integration Tests - With CLI_.
 
+#### Running a single test
+
+##### 1. From the terminal
+
+The easiest way to run a single test is to change the `it` of the test to `it.only` and then run the test command with some additional options
+to only run tests for this specific file. For example, to run the test `src/vscode-tests/cli-integration/run-queries.test.ts`:
+
+```shell
+npm run cli-integration -- --runTestsByPath src/vscode-tests/cli-integration/run-queries.test.ts
+```
+
+You can also use the `--testNamePattern` option to run a specific test within a file. For example, to run the test `src/vscode-tests/cli-integration/run-queries.test.ts`:
+
+```shell
+npm run cli-integration -- --runTestsByPath src/vscode-tests/cli-integration/run-queries.test.ts --testNamePattern "should create a QueryEvaluationInfo"
+```
+
+##### 2. From VSCode
+
+Alternatively, you can run a single test inside VSCode. To do so, install the [Jest Runner](https://marketplace.visualstudio.com/items?itemName=firsttris.vscode-jest-runner) extension. Then,
+you will have quicklinks to run a single test from within test files. To run a single unit or integration test, click the "Run" button. Debugging a single test is currently only supported
+for unit tests by default. To debug integration tests, open the `.vscode/settings.json` file and uncomment the `jestrunner.debugOptions` lines. This will allow you to debug integration tests.
+Please make sure to revert this change before committing; with this setting enabled, it is not possible to debug unit tests.
+
+Without the Jest Runner extension, you can also use the "Launch Selected Unit Test (vscode-codeql)" launch configuration to run a single unit test.
+
 #### Using a mock GitHub API server
 
 Multi-Repo Variant Analyses (MRVA) rely on the GitHub API. In order to make development and testing easy, we have functionality that allows us to intercept requests to the GitHub API and provide mock responses.

extensions/ql-vscode/src/vscode-tests/jest-runner-vscode.config.base.js

@@ -17,7 +17,11 @@ const config = {
 };
 
 if (process.env.VSCODE_INSPECTOR_OPTIONS) {
-  config.launchArgs?.push("--inspect-extensions", "9223");
+  if (process.env.VSCODE_WAIT_FOR_DEBUGGER === "true") {
+    config.launchArgs?.push("--inspect-brk-extensions", "9223");
+  } else {
+    config.launchArgs?.push("--inspect-extensions", "9223");
+  }
 }
 
 module.exports = {