Unit tests

.NET Unit Testing

To run .NET backend unit tests, from the repo (repository) root

dotnet test

.NET backend unit tests can also be run using the .NET Test Explorer area of the Test sidebar, or by clicking "Run Test" above a test in a code window. Clicking "Debug Test" will allow debugging.

See documentation for running tests and writing tests.

Node Unit Testing

To run Node backend unit tests, from the repo root

cd src/RealtimeServer
npm test

Jest is the test framework for the Node backend.

Debugging Unit Tests

Unit tests can be debugged easily in VS Code using the Jest extension. After installing the exension, start the Jest test runner by executing the Jest: Start Runner command in the VS Code command palette. The runner will automatically run all of the Node unit tests and display a green or red circle next to each unit test indicating whether the unit test passed. If the unit test failed, a Debug code lens command will appear above the test. Set a breakpoint and click on the command.

Angular Unit Testing

Tests are run by Karma in a browser. Help Karma find Chromium by setting CHROME_BIN. Set it persistently with

tee -a ~/.pam_environment <<< "CHROME_BIN=chromium-browser"

and then log back in to your desktop, or set it temporarily with

export CHROME_BIN=chromium-browser

CHROME_BIN is already set in the vagrant.

Run all the front-end unit tests, automatically re-running when you change a file:

cd src/SIL.XForge.Scripture/ClientApp
npm test

Run tests only in a specific spec file, or only in all spec files in a directory, with the following, where PATH is a relative path to a file or directory. PATH must be relative to ClientApp/src; for example app/sync/sync.component.spec.ts or app/sync.

cd src/SIL.XForge.Scripture/ClientApp/src
npm test -- --include PATH

npm test will monitor and run tests in a Chromium browser window. You can also monitor and run tests headlessly from the command line by running

src/SIL.XForge.Scripture/ClientApp/monitor-test-headless.sh

Or just run tests once without monitoring with

src/SIL.XForge.Scripture/ClientApp/test-headless.sh

You can filter the tests to compile and run by passing spec file names as arguments. For example,

src/SIL.XForge.Scripture/ClientApp/monitor-test-headless.sh some.component.spec.ts another.component.spec.ts

Headless Unit Tests

The unit tests for the Angular frontend can be run headlessly on Windows or Linux:

cd src/SIL.XForge.Scripture/ClientApp
npm run test:gha

NOTE: Windows users may need to set the CHROMIUM_BIN environment variable first:

set CHROMIUM_BIN=c:\Program Files\Google\Chrome\Application\chrome.exe

Debugging Unit Tests

The best way to debug Angular unit tests is with Chrome/Chromium.

• Run npm test (which will include source maps, ng test does not)
• When the Chrome/Chromium window appears, press F12
• Click the Sources tab
• Files might show up under webpack:// or context/localhost:dddd/src or elsewhere, but you can always press Ctrl+P and type the name of a file to get there faster.

This video has a live demo of the process.

It is also possible to debug Angular unit tests in VS Code.

• Open the spec file that you want to debug in VS Code.
• Set a breakpoint.
• Navigate to the Run and Debug view.
• Select Launch Chromium and run and debug current spec from the debug dropdown.
• Click the Start Debugging button.

This will run ng test on the active spec file, open Chrome, and attach the VS Code debugger. You can refresh the page by clicking the Restart button in the Debug toolbar.

Filtering Unit Tests

To run (or not to run) specific tests or fixtures, you can use the prefixes focus and exclude, as in fdescribe or fit to run only the specified functions, or xdescribe and xit to skip running the specified functions (but all functions will still be built). To skip building extra tests, use the --include option when running ng test. See the Angular CLI docs for more info.

See documentation for running tests and writing tests.

Finding a test that is freezing your web browser

Some web browsers, notably Safari, may freeze completely when executing a test. To find what that test is, list each test name that is executing by pasting this code into the top level of one of the *.spec.ts files:

jasmine.getEnv().addReporter({
  specStarted: function(result) {
    console.log('Running test: ' + result.fullName);
  }
});