WritingUnitTests.md

Writing Unit Tests for NativeScript Core Modules

Unit tests for NativeScript Modules are written and executed with a custom lightweight test-runner and assertion framework. The purpose of this document is to get you familiar with it so that you can unit-test your contributions to the NativeScript framework.

Run Unit Tests Project

Refer to the development-workflow guide for instructions on how to set up your repo and get it ready for development. After the setup, navigate to the tests project and run it. It will execute all the tests and output the results in the console.

cd tests

tns run android
# or
tns run ios

Test Modules

All unit tests are organized into test modules(bundles). By default, the test app will run all the tests from all registered test modules. This happens in runTests() method in the main page of the test-app. By modifying this method, you can configure the app to:

• Execute only the tests from a specific test module:

function runTests() {
    setTimeout(() => tests.runAll('HTTP'), 10);
}

• Execute single test from a specific test module:

function runTests() {
    setTimeout(() => tests.runAll('HTTP.test_getJSON'), 10);
}

Register Test Module

Test modules are organized in separate files and are registered in the tests/app/testRunner.ts file:

import * as httpTests from "./http/http-tests";
allTests["HTTP"] = httpTests;

Writing Test Module

The test modules are actually TypeScript modules which export unit tests and hooks as functions following this convention:

• All exported functions with a test prefix are unit-tests.
• The setUpModule() hook is called once - before all the tests in the module.
• The setUp() hook is called before each test.
• The tearDown() hook called after each test.
• The tearDownModule() hook is called once - after all the tests in the module.

Asserting

A test will fail if assert is not satisfied or if an error is thrown during execution. There is a large set of asserting functions available in the tests/app/TKUnit.ts module. We recommend using those in your tests.

import * as TKUnit from "../tk-unit";

export function testSomethingWorksFast() {
    let arr = [1, 2, 3];
    
    TKUnit.assertNotNull(arr, "Array should be defined");
    TKUnit.assertTrue(arr[2] > 2, "arr[2] is not big enough")
    TKUnit.assertEqual(arr.length, 3, "Array length should be 3");
}

Async Tests

Unit tests can accept a single argument - a done callback. The test framework will wait for the done() callback to be called (or the test to timeout) before moving on. Passing an Error to the done() callback will cause the test to fail:

export function test_getJSON(done) {
    http.getJSON("https://httpbin.org/get").then(
        (result) => { done(); }, // success
        (error) => { done(error); }); // fail
};

Misc

When looking into the code of the existing tests, you might encounter strange comments looking like this // >> animation-chaining. These are markers for code snippets generated in the docs documentation. They are not related to testing so you don't need to add any of those in your tests.