NativeScript Unit Test Runner

Common errors

• Error: Cannot find module 'nativescript-unit-test-runner' or 'module not found'

  cause Attempting to use CommonJS `require()` syntax for a package expecting ES Modules (since v4.0.1), or incorrect module resolution in your build setup.
  fix For versions `4.0.1` and above, ensure you are using ES Module `import` syntax. Verify your `tsconfig.json` (if TypeScript) and build configuration (e.g., Webpack) are set up for proper module resolution.

• NativeScript CLI Error: This version of `@nativescript/core` is not compatible with `nativescript-unit-test-runner@X.Y.Z`.

  cause Mismatched major versions between the `nativescript` package in your project and the `nativescript-unit-test-runner` package, leading to API incompatibilities.
  fix Upgrade `nativescript-unit-test-runner` to a version compatible with your project's NativeScript core. For NativeScript v9, use `nativescript-unit-test-runner@4.x.x`.

• Webpack compilation errors during test run, e.g., 'Can't resolve [module]' or 'Configuration error'

  cause Incompatible Webpack configuration after upgrading to `nativescript-unit-test-runner` versions that support Webpack 5 (>=v2.0.0), or issues with `@nativescript/webpack` setup.
  fix Update your `webpack.config.js` to be compatible with Webpack 5. Refer to the `@nativescript/webpack` documentation and NativeScript CLI documentation for Webpack 5 specific configurations, and ensure your `@nativescript/webpack` package is up-to-date.

• Tests are not running on Android emulator, or 'connection refused' errors appear

  cause Issues with network connectivity between the test runner and the Android emulator, possibly due to IP address changes handled by the runner in versions >=3.0.0, or emulator configuration problems.
  fix Verify your Android emulator's network configuration and ensure it is properly configured to allow connections. Try restarting the emulator or ensuring it has a proper IP address. Check for firewall rules that might block communication between your host machine and the emulator.

Warnings

• breaking Version 4.0.1 introduced proper ES Module (ESM) syntax support. Projects that were relying on CommonJS `require()` syntax or incompatible module resolution for this package might experience import errors after upgrading. This is a crucial change for modern JavaScript environments.
  Fix: Ensure your project's `tsconfig.json` (if TypeScript) and build configuration (e.g., `webpack.config.js`) are configured for ES Modules. Update any `require()` statements targeting `nativescript-unit-test-runner` to `import` statements.
• breaking Version 4.0.0 introduced support for NativeScript v9. Using `nativescript-unit-test-runner@4.x.x` with older versions of NativeScript (e.g., v8 or earlier) is likely to cause compatibility issues and build failures. Conversely, using older versions of the runner with NativeScript v9 is also not supported.
  Fix: Align the `nativescript-unit-test-runner` version with your `nativescript` project version. For NativeScript v9, use `nativescript-unit-test-runner@4.x.x`. Upgrade both packages simultaneously if necessary.
• breaking Version 2.0.0 brought Webpack 5 support and NativeScript 8.0 compatibility. Upgrading from versions prior to 2.0.0 to 2.0.0 or later may require significant changes to your `webpack.config.js` and general build setup to accommodate Webpack 5's new configuration paradigms.
  Fix: Review NativeScript's documentation for Webpack 5 integration and update your `webpack.config.js` accordingly. Ensure `@nativescript/webpack` is updated to a compatible version.
• gotcha Since v3.0.2, the runner defaults to disabling AOT (Ahead-Of-Time) compilation for Angular projects, preferring JIT (Just-In-Time) compilation during test runs. While often beneficial for faster test cycles, this might lead to subtle differences if your production build uses AOT, potentially masking AOT-specific issues.
  Fix: Be aware of the AOT/JIT difference in test vs. production builds. If AOT-specific issues are suspected, consider configuring your test app with AOT explicitly or running full AOT builds outside the test runner for comprehensive validation.
• gotcha Version 3.0.0 included a fix for the default IP address used for Android emulators. If you are experiencing connectivity issues with your Android emulator during test runs after upgrading from pre-3.0.0 versions, this might be the cause for certain network configurations.
  Fix: Ensure your Android emulator is properly configured and reachable on the network. Try restarting the emulator or verifying its network settings. Consult NativeScript documentation for specific emulator networking configurations or update your Android SDK tools.

Install

• npm install nativescript-unit-test-runner npm
• yarn add nativescript-unit-test-runner yarn
• pnpm add nativescript-unit-test-runner pnpm

Imports

• NativeScriptTestEnvironment
  wrong:

  const NativeScriptTestEnvironment = require('nativescript-unit-test-runner').NativeScriptTestEnvironment;

  correct:

  import { NativeScriptTestEnvironment } from 'nativescript-unit-test-runner';

  While direct imports for symbols like `NativeScriptTestEnvironment` are less common for end-user applications and more for advanced tooling or plugin development, the package primarily serves as a backend runner. Since v4.0.1, proper ES Module syntax is expected. Older versions might have required a different import style or internal usage.
• configureNativeScriptTests
  wrong:

  import configureNativeScriptTests from 'nativescript-unit-test-runner/config';

  correct:

  import { configureNativeScriptTests } from 'nativescript-unit-test-runner';

  This hypothetical function represents a programmatic way to set up the test environment for advanced use cases, rather than the typical CLI-driven setup. Ensure correct named import syntax since v4.0.1 for ESM compatibility.
• * as NativeScriptRunner
  wrong:

  const NativeScriptRunner = require('nativescript-unit-test-runner');

  correct:

  import * as NativeScriptRunner from 'nativescript-unit-test-runner';

  For scenarios where the entire module (e.g., for side effects like Karma framework registration) is needed programmatically, an aggregated namespace import is the ESM standard. CommonJS `require` should be avoided since v4.0.1 due to improved ES Module syntax.

Quickstart

Demonstrates initializing a new NativeScript project, setting up the unit test runner with `tns test init`, and executing example tests on Android or iOS devices/simulators.

npx create-nativescript-app my-test-app --template @nativescript/template-blank-typescript
cd my-test-app
tns test init

# The 'tns test init' command will guide you through setting up Jasmine or Mocha.
# For example, select Jasmine during the interactive prompt.

# Now, create a simple test file. For instance, add `app/tests/example.ts` with the following content:
/*
describe('Example Test Suite', () => {
  it('should verify true is true', () => {
    expect(true).toBe(true);
  });

  it('should correctly concatenate strings', () => {
    const greeting = 'Hello';
    const name = 'NativeScript';
    expect(`${greeting} ${name}`).toBe('Hello NativeScript');
  });
});
*/

# To run tests on an Android emulator or connected device:
tns test android

# To run tests on an iOS simulator or connected device (requires Xcode):
tns test ios

# For continuous testing that watches for file changes:
tns test android --watch