Testing And Debugging
How to debug the extension and its components is covered below. This doc is a work-in-progress, please update as needed.
As discussed in Architecture, the extension is split into a few separate parts (core extension, backing service, and UI front end). Right now this means that debugging and testing instructions vary for each section. We've covered each below, but in summary:
Anything to do with command palette integration, routing, initialization is in the core extension. Start with this before looking in other areas
- Code paths: https://github.com/Microsoft/vscode-mssql, the src folder excluding src/views/htmlcontent
Anything in the UI will likely be the Results View section
- Code paths: https://github.com/Microsoft/vscode-mssql, the src/views/htmlcontent folder
- The grid implementation used is SlickGrid. We use a fork of a slightly old version located at https://github.com/microsoft/angular2-slickgrid. This may be updated in the future, but for now any pure grid-based issues can be fixed there.
When you need to dig into complex behavior (e.g. why is there an issue in Connectivity, Intellisense, Query Execution) this code is all in the service layer.
- Code paths: https://github.com/Microsoft/sqltoolsservice.
Debugging our extension code is fairly straightforward:
- Follow the Contributing steps to set up the project, restore dependencies and build.
- Once this is working, in VSCode navigate to the Debug tab. Choose
Launch Extensionand it will open a new VSCode instance with the extension available. You can set breakpoints and capture events easily.- A good place to start is src/controllers/mainController.ts. The
activate()function sets up all command routing so you can find relevant entry points to the code from there
- A good place to start is src/controllers/mainController.ts. The
The results view actually runs as a WebView component, meaning it's basically hosted in its own web page. Debugging requires use of a browser such as Chrome, or potentially the Chrome Debugger extension for VSCode (not yet explored).
You'll need the URL for our WebView to attach and debug. This is in the format localhost:{port}/root?uri={uri}. Right now, setting
breakpoints is the only supported way to break in and debug.
- For port number, open s
src/controllers/localWebService.ts, add breakpoint to the start() method and note the port. This value will change each time you launch the extension - For uri, open src/models/SqlOutputContentProvider.ts. Add breakpoint to the
provideTextDOcumentContentmethod and capture theencodedUrivalue. This value is constant so long as you use the same file for testing.
To step through, you need to:
- Launch the extension in debug mode as mentioned above
- Open a .sql file, connect and execute a query using
ctrl+shift+e. - You should hit the breakpoints you set to capture the port and URI.
- Combine these in the format
localhost:{port}/root?uri={uri}, and paste this address into your browser - Open the developer tools in the browser, and you can see your
Sourcesand even navigate to the Typescript thanks to source mapping - Set breakpoints as you would for any application
Changes can be make inside the browser or in VS Code. To see the changes, reload the web page and interact with the view
- You can even change the backing source code and reload to see changes for a quick debug loop. Do remember that you'll be debugging
TypeScript so you might need to change the contents in a
.jsfile in theoutdirectory, or rungulp html:compile-srcto update just the source code.
The SQL Tools Service is the backing application use to handle most requests (e.g. Connection, Intellisense, Query Execution & Results processing). For anything more than simple extension-side changes, you may need to start testing this project. We recommend you primarily debug this by launching relevant unit tests and stepping through the code from them, since this is by far the simplest method. If it's an integration issue you might need to debug both the mssql extension and the sqltoolsservice at once - the instructions below cover this scenario, but please consider just writing a unit test for your new scenarios.
To debug, you need to
-
Build your own service and copy to the extension:
- Follow the instructions at https://github.com/Microsoft/sqltoolsservice/wiki to build the source code for the extension.
- Follow the instructions at https://github.com/microsoft/vscode-mssql/blob/main/DEVELOPMENT.md
-
Launch the mssql extension in debug mode, then attach to the backing service
- You should have 1 VSCode open with the vscode-mssql extension code ready for launch, and another VSCode or Visual Studio instance with the sqltoolsservice code ready to be debugged. We will first launch the extension, then attach the sqltoolsservice instance to the backing executable.
- Go to the debug tab in VSCode and click
Launch Extensionto launch an instance of VSCode with the extension ready for use - Launch and activate the extension by opening a SQL file. This will in turn launch our Microsoft.SqlTools.ServiceLayer.exe application
- Find the PID of the process by opening Task Manager (Windows), Activity Monitor (macOS), etc. and
- In the other VSCode/Visual Studio instance with the sqltoolsservice code, Go to
Debug -> Attach to Processand select the application, or for VSCode choose PID for theMicrosoft.SqlTools.ServiceLayer.exeapplication - Set breakpoints as desired, and run VSCode scenarios. You should see your breakpoints getting hit as usual
Before committing code we require all tests to pass. There are 3 main sections to the MSSQL plugin, all with separate tests.
Using gulp test from the command line will run all tests for the extension and the HTML Results View.
Notes:
- For VSCode tests to run from a commandline all VSCode instances must be closed.
- There is a problem at times when running the html tests can fail if you have a chrome session open. If you have problems with the karma tests close any chrome sessions you have open.
- If you continue to have problems with the html tests you can change the single run variable in the karma conf to false, comment out the browsers field and from
gulp html:test. This will launch the karma server but not launch the browser to run the tests. Then open a chrome session and navigate to the url karma prints in console. This will run the tests.
The majority of our code is actually in the SQL Tools Service service application.
This is a .Net Core-based application running on each platform. It has a full set of xUnit tests runnable using dotnet test against
that repository. Check out instructions in that repository for full information.
- Build the project
- Install the recommended testing extensions from
extensions.json. Namely, you'll need:-
ms-vscode.extension-test-runnerfor the unit tests (mostly written in Mocha) -
ms-playwright.playwrightfor the end-to-end/UX tests
-
- You'll know you've done the first two steps correctly if VS Code's Test Explorer is discovering both sets of tests:
4. Right-click on a test (or collection of tests) to either run or debug it. If you select debug, this should successfully hit breakpoints both in the tests and the product code.
Some tests have timeouts, which can result in failures if you're debugging using breakpoints. Disable timeouts on the test to give yourself time to debug with breakpoints, but remember to revert the timeout and breakpoints and verify that the test still passes.
Currently, there is no support for running these tests integrated with debugging in VSCode. Mostly the current process is command-line-based, with some limited support for debugging inside Chrome.
Debugging is supported in VSCode so long as you have the C# extension installed. Usually, this is on a per-test basis
Further information can be found here.