From b493f01b35a9810b7b0893cdf5719121ab5389c9 Mon Sep 17 00:00:00 2001 From: Andrew Stanton-Nurse Date: Thu, 17 May 2018 17:09:45 -0700 Subject: [PATCH] Fix #2291 by documenting how to debug TS tests (#2306) --- .vscode/launch.json | 33 ++++++++----- clients/ts/DebuggingTests.md | 94 ++++++++++++++++++++++++++++++++++++ 2 files changed, 115 insertions(+), 12 deletions(-) create mode 100644 clients/ts/DebuggingTests.md diff --git a/.vscode/launch.json b/.vscode/launch.json index 313c0a9d9e..3b06498267 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -3,20 +3,29 @@ "configurations": [ { "type": "node", - "request": "launch", - "name": "Launch Program", - "program": "${workspaceRoot}/client-ts/node_modules/jasmine/bin/jasmine.js", - "args": ["JASMINE_CONFIG_PATH=${workspaceRoot}/client-ts/Microsoft.AspNetCore.SignalR.Client.TS.Tests/jasmine.json"], - "cwd": "${workspaceRoot}/client-ts", - "outFiles": [] + "request": "attach", + "name": "Node - Attach by Process ID", + "processId": "${command:PickProcess}" }, { "type": "node", - "request": "attach", - "name": "Attach to Port", - "address": "localhost", - "port": 5858, - "outFiles": [] - } + "request": "launch", + "name": "Jest - All", + "program": "${workspaceFolder}/clients/ts/node_modules/jest/bin/jest", + "cwd": "${workspaceFolder}/clients/ts", + "args": ["--runInBand"], + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen" + }, + { + "type": "node", + "request": "launch", + "name": "Jest - Current File", + "program": "${workspaceFolder}/clients/ts/node_modules/jest/bin/jest", + "cwd": "${workspaceFolder}/clients/ts", + "args": ["${relativeFile}"], + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen" + } ] } \ No newline at end of file diff --git a/clients/ts/DebuggingTests.md b/clients/ts/DebuggingTests.md new file mode 100644 index 0000000000..66adbd9c09 --- /dev/null +++ b/clients/ts/DebuggingTests.md @@ -0,0 +1,94 @@ +# Debugging/Running Jest Tests + +We use [Jest](https://facebook.github.io/jest/) as our JavaScript testing framework. We also use [ts-jest](https://github.com/kulshekhar/ts-jest) which builds TypeScript automatically. + +Prerequisites: NodeJS, have run `./build.cmd /t:Restore` at least once since cleaning. + +All commands must be run from this directory (the `clients/ts` directory). + +## Running all tests + +``` +> npm test +``` + +## Running all tests in a specific file + +``` +> npm test -- FileName +``` + +`FileName` can be a substring of the path, it will run all test files containing that **substring** in the path. + +For example (use `/` for paths even on Windows, since Node is interpreting them): + +* `npm test -- signalr/tests` will run all tests in `clients\ts\signalr\tests` +* `npm test -- signalr-protocol-msgpack/tests` will run all tests in `clients\ts\signalr-protocol-msgpack\tests` +* `npm test -- signalr/tests/` will run all tests in `clients\ts\signalr\tests` +* `npm test -- signalr/tests/JsonHubProtocol` will run all tests in `signalr/tests/JsonHubProtocol.test.ts` +* `npm test -- JsonHubProtocol` will **also** run all tests in `signalr/tests/JsonHubProtocol.test.ts` because it's the only test file matching that pattern + +## Running a single test + +The simplest way to run a single test is to use `.only`. Marking a test with `.only` will ensure that **only** that test is run when running tests from that file. If you are running multiple files (i.e. `npm test` with no arguments, it will still run all the tests in the other files). + +To use `.only`, just add `.only` to the end of the call to `it`: + +```typescript +describe("A suite of tests", () => { + describe("A sub-suite of tests", () => { + it.only("will run", () => { + + }); + + it("will not run", () => { + + }); + }); + + describe("Another sub-suite of tests", () => { + it("will not run either", () => { + + }); + }); +}); +``` + +Just make sure you remove `.only` when you finish running that test! + +You can also use the `-t` parameter to jest. That parameter takes a substring pattern to match against all tests to see if they should run. To improve the speed of the run, you should pair this up with the argument that takes a file path to filter on. For example, given these tests + +``` +describe("AbortSignal", () => { + describe("aborted", () => { + it("is false on initialization", () => { + // ... + }); + + it("is true when aborted", () => { + // ... + }); + }); + + describe("onabort", () => { + it("is called when abort is called", () => { + // ... + }); + }); +}); +``` + +These commands will each run the following sets of tests: + +* `npm test -- AbortSignal -t "AbortSignal aborted"` will run `AbortSignal aborted is false on initialization` and `AbortSignal aborted is true when aborted`. +* `npm test -- AbortSignal -t "is called when abort is called"` will run `AbortSignal onabort is called when abort is called`. + +## Debugging All Tests + +You can launch all tests under the debugger in Visual Studio Code by clicking on the "Debug" tab on the left side, selecting "Jest - All" in the dropdown at the top and clicking the play button, or pressing F5. + +## Debugging All Tests in a single file + +You can launch all tests **in the currently open file** under the debugger in Visual Studio Code by clicking on the "Debug" tab on the left side, selecting "Jest - Current File" in the dropdown at the top and clicking the play button, or pressing F5. + +**NOTE**: Pair this with `.only` to easily debug a single test! \ No newline at end of file