JSUnitTests.md

Debugging/Running JavaScript Unit Tests

We use Jest as our JavaScript testing framework. We also use 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).

Building the library before running tests

You need to build the libraries any time you make a change, before you can run the tests. Do this by running the following command from the clients/ts folder:

> npm run build

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:

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!