Skip to content

Testing And Debugging

Jump to bottom
Kevin Cunnane edited this page Nov 23, 2016 · 8 revisions

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:

Extension code

Anything to do with command palette integration, routing, initialization is in the core extension. Start with this before looking in other areas

UI Code

Anything in the UI will likely be the Results View section

Service code

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.

Debugging

Debugging extension-side code

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 Extension and 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

Debugging results view code

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.

Prerequisite: Setting breakpoints

  • For port number, open ssrc/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 provideTextDOcumentContent method and capture the encodedUri value. This value is constant so long as you use the same file for testing.

Debugging results in the browser

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 Sources and even navigate to the Typescript thanks to source mapping
  • Set breakpoints as you would for any application

Making changes while debugging

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 .js file in the out directory, or run gulp html:compile-src to update just the sourcez code.

Launching the extension & capturing the URL

Debugging SQL Tools Service 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.

To debug, you need to:

  • Checkout the project from Git, restore & build it using dotnet restore and dotnet run
  • Copy the resulting code

Testing

Before committing code we require all tests to pass. There are 3 main sections to the MSSQL plugin, all with separate tests.

Command line testing

Testing Extension and UI code

Using gulp test from the command line will run all tests for the extension and the HTML Results View. Note that for VSCode tests to run from a commandline all VSCode instances must be closed.

Testing SQL Tools Service code

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.

Test in VSCode

Testing Extension inside VSCode

  • Build the project
  • Go to the debug section, and choose the Launch Tests option
  • Results are shown in the Debug Console (ctrl+shift+y to view)

Breakpoints inside tests

For some reason, breakpoints inside the product code will only work from tess if you:

  • Add a breakpoint into the relevant test that call product code
  • Step into product code once. After this, it will work for all product code - it seems that it hooks the require command after this but otherwise the source isn't instrumented for breakpoints.

Test failures if breakpoints are used

Tests have a 200ms timeout. Therefore if you add a breakpoint, the test will fail. To verify the test passes again, remove the breakpoint and re-run the test.

Results View / Angular tests

Currently there is no support for running these tests integrated with debugging in VSCode. Mostly the current process is commaneline-based, with some limited support for debugging inside Chrome.

SQL Tools Service Tests

Debugging is supported in VSCode so long as you have the C# extension installed. Usually this is on a per-test basis

Table of Contents

Clone this wiki locally