Merge #1446

1446: Initial Visual Studio Code unit tests r=matklad a=etaoins

As promised in #1439 this is an initial attempt at unit testing the VSCode extension. There are two separate parts to this: getting the test framework working and unit testing the code in #1439.

The test framework nearly intact from the VSCode extension generator. The main thing missing was `test/index.ts` which acts as an entry point for Mocha. This was simply copied back in. I also needed to open the test VSCode instance inside a workspace as our file URI generation depends on a workspace being open.

There are two ways to run the test framework:

1. Opening the extension's source in VSCode, pressing F5 and selecting the "Extensions Test" debug target.

2. Closing all copies of VSCode and running `npm test`. This is started from the command line but actually opens a temporary VSCode window to host the tests.

This doesn't attempt to wire this up to CI. That requires running a headless X11 server which is a bit daunting. I'll assess the difficulty of that in a follow-up branch. This PR is at least helpful for local development without having to induce errors on a Rust project.

For the actual tests this uses snapshots of `rustc` output from [a real Rust project](https://github.com/etaoins/arret) captured from the command line. Except for extracting the
`message` object and reformatting they're copied verbatim into fixture JSON files.

Only four different types of diagnostics are tested but they represent the main combinations of code actions and related information possible. They can be considered the happy path tests; as we encounter corner-cases we can introduce new tests fixtures.

Co-authored-by: Ryan Cumming <[email protected]>

1 files changed, 19 insertions, 0 deletions

diff --git a/docs/dev/README.md b/docs/dev/README.md
index 3dc37e86e..0a148ed32 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -97,6 +97,25 @@ To work on the VS Code extension, launch code inside `editors/code` and use `F5`
 to launch/debug. To automatically apply formatter and linter suggestions, use
 `npm run fix`.
 
+Tests are located inside `src/test` and are named `*.test.ts`. They use the
+[Mocha](https://mochajs.org) test framework and the builtin Node
+[assert](https://nodejs.org/api/assert.html) module. Unlike normal Node tests
+they must be hosted inside a VS Code instance. This can be done in one of two
+ways:
+
+1. When `F5` debugging in VS Code select the `Extension Tests` configuration
+   from the drop-down at the top of the Debug View. This will launch a temporary
+   instance of VS Code. The test results will appear in the "Debug Console" tab
+   of the primary VS Code instance.
+
+2. Run `npm test` from the command line. Although this is initiated from the
+   command line it is not headless; it will also launch a temporary instance of
+   VS Code. 
+
+Due to the requirements of running the tests inside VS Code they are **not run
+on CI**. When making changes to the extension please ensure the tests are not
+broken locally before opening a Pull Request.
+
 # Logging
 
 Logging is done by both rust-analyzer and VS Code, so it might be tricky to