{"id":15360,"library":"nativescript-unit-test-runner","title":"NativeScript Unit Test Runner","description":"The `nativescript-unit-test-runner` package provides the core infrastructure for executing unit tests within NativeScript applications. It is primarily consumed by the NativeScript CLI (`tns test`) and integrates with standard JavaScript testing frameworks like Karma, Jasmine, and Mocha. The current stable version is `4.0.1`, which includes support for NativeScript 9 and improved ES Module syntax handling. This package acts as the bridge between your test code, the NativeScript runtime, and the underlying test runner environment, facilitating the execution of tests directly on emulators, simulators, or physical devices. It addresses the complexities of running tests in a device-native context, a key differentiator from web-based test runners, and has an active release cadence with major version updates supporting new NativeScript versions.","status":"active","version":"0.7.0","language":"javascript","source_language":"en","source_url":"https://github.com/NativeScript/nativescript-unit-test-runner","tags":["javascript"],"install":[{"cmd":"npm install nativescript-unit-test-runner","lang":"bash","label":"npm"},{"cmd":"yarn add nativescript-unit-test-runner","lang":"bash","label":"yarn"},{"cmd":"pnpm add nativescript-unit-test-runner","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for developing and running NativeScript applications on which tests are executed. Specifically supports NativeScript v9 since `nativescript-unit-test-runner` v4.0.0.","package":"nativescript","optional":false},{"reason":"Commonly used as the test host/runner framework that `nativescript-unit-test-runner` integrates with, although not a direct dependency in its `package.json`, it's a crucial peer dependency in a typical NativeScript test setup.","package":"karma","optional":true},{"reason":"Required for bundling NativeScript applications, and this runner provides specific support for Webpack 5 (since v2.0.0) in the testing environment.","package":"webpack","optional":true}],"imports":[{"note":"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.","wrong":"const NativeScriptTestEnvironment = require('nativescript-unit-test-runner').NativeScriptTestEnvironment;","symbol":"NativeScriptTestEnvironment","correct":"import { NativeScriptTestEnvironment } from 'nativescript-unit-test-runner';"},{"note":"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.","wrong":"import configureNativeScriptTests from 'nativescript-unit-test-runner/config';","symbol":"configureNativeScriptTests","correct":"import { configureNativeScriptTests } from 'nativescript-unit-test-runner';"},{"note":"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.","wrong":"const NativeScriptRunner = require('nativescript-unit-test-runner');","symbol":"* as NativeScriptRunner","correct":"import * as NativeScriptRunner from 'nativescript-unit-test-runner';"}],"quickstart":{"code":"npx create-nativescript-app my-test-app --template @nativescript/template-blank-typescript\ncd my-test-app\ntns test init\n\n# The 'tns test init' command will guide you through setting up Jasmine or Mocha.\n# For example, select Jasmine during the interactive prompt.\n\n# Now, create a simple test file. For instance, add `app/tests/example.ts` with the following content:\n/*\ndescribe('Example Test Suite', () => {\n  it('should verify true is true', () => {\n    expect(true).toBe(true);\n  });\n\n  it('should correctly concatenate strings', () => {\n    const greeting = 'Hello';\n    const name = 'NativeScript';\n    expect(`${greeting} ${name}`).toBe('Hello NativeScript');\n  });\n});\n*/\n\n# To run tests on an Android emulator or connected device:\ntns test android\n\n# To run tests on an iOS simulator or connected device (requires Xcode):\ntns test ios\n\n# For continuous testing that watches for file changes:\ntns test android --watch","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.1"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"Error: Cannot find module 'nativescript-unit-test-runner' or 'module not found'"},{"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`.","cause":"Mismatched major versions between the `nativescript` package in your project and the `nativescript-unit-test-runner` package, leading to API incompatibilities.","error":"NativeScript CLI Error: This version of `@nativescript/core` is not compatible with `nativescript-unit-test-runner@X.Y.Z`."},{"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.","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.","error":"Webpack compilation errors during test run, e.g., 'Can't resolve [module]' or 'Configuration error'"},{"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.","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.","error":"Tests are not running on Android emulator, or 'connection refused' errors appear"}],"ecosystem":"npm"}