Cordova Plugin Test Framework

Common errors

• Plugin doesn't have a package.json

  cause The nested test plugin within your main plugin's `/tests` directory is missing a `package.json` file, which is now required by Cordova tooling.
  fix Create a `package.json` file inside your plugin's `/tests` directory. This file should define the test plugin's ID (e.g., `plugin-id-tests`) and any necessary `devDependencies`.

• describe is not defined

  cause The Jasmine test runner, which provides the `describe`, `it`, and `expect` functions, has not been correctly initialized or the test environment is not properly set up by the `cordova-plugin-test-framework`. This could happen if the test harness isn't loaded.
  fix Ensure `cordova-plugin-test-framework` is added to your project and that your app's `config.xml` is configured to load `cdvtests/index.html` as its start page. Also, verify your test file is correctly exported via a `<js-module>` in the nested `tests/plugin.xml`.

• Error: Cannot find module 'my-test-dependency'

  cause An npm dependency required by your test files (e.g., for mocking or utility functions) has not been installed.
  fix Add the missing dependency to the `devDependencies` section of the `package.json` located within your plugin's `/tests` directory, and then run `npm install` inside that `/tests` directory.

Warnings

• breaking Older versions of Cordova plugins' test structures might not include a `package.json` file within their `/tests` directory. Modern Cordova tooling, and specifically this framework, now requires a nested `package.json` for test plugins to manage their own npm dependencies.
  Fix: Ensure a `package.json` file is present in your plugin's `/tests` directory, defining the test plugin's metadata and any npm dependencies for the tests themselves. Run `npm install` within the `/tests` directory if it has dependencies.
• gotcha This plugin appears to be unmaintained. Its last significant update was over seven years ago (version 1.1.6 published 8 years ago), indicating potential incompatibility with newer Cordova versions, platforms, or modern JavaScript features (e.g., ESM).
  Fix: Consider alternative testing strategies for Cordova, such as `cordova-paramedic` for more active maintenance and broader compatibility, or integrate standard JavaScript testing frameworks (like Jest or Mocha) with custom Cordova mocking for unit tests.
• gotcha The framework relies on making Jasmine 2.0 globals (`describe`, `it`, `expect`) available in the test execution context. This global pollution might conflict with other testing setups or lead to unexpected behavior if not managed carefully.
  Fix: Be aware that Jasmine functions are globally available. Avoid re-declaring them or introducing other test runners that also rely on global scope within the same test context.
• gotcha To run tests, you must manually configure your Cordova app's `config.xml` to point its start page to `cdvtests/index.html`. Forgetting this step will prevent the test harness from loading and displaying test results.
  Fix: After installing the test framework, open your `config.xml` file and change the `<content src="index.html" />` tag to `<content src="cdvtests/index.html" />` or navigate to `cdvtests/index.html` from within your app after launch.

Install

• npm install cordova-plugin-test-framework npm
• yarn add cordova-plugin-test-framework yarn
• pnpm add cordova-plugin-test-framework pnpm

Imports

• defineAutoTests
  wrong:

  import { defineAutoTests } from 'my-plugin-tests';

  correct:

  exports.defineAutoTests = function() { /* ... */ }

  Tests are defined as CommonJS exports within a nested `tests.js` file, which the framework automatically discovers. No direct import statement is typically used by the developer for the framework itself, rather the tests are exported.
• describe
  wrong:

  import { describe } from 'jasmine';

  correct:

  describe('My Test Suite', function() { /* ... */ });

  The framework makes Jasmine 2.0 globals (`describe`, `it`, `expect`, `beforeEach`, etc.) available in the scope where `defineAutoTests` is executed. Explicitly importing Jasmine functions is not required.
• Test Harness
  wrong:

  npm install cordova-plugin-test-framework

  correct:

  cordova plugin add cordova-plugin-test-framework

  The framework itself is integrated as a Cordova plugin, not directly through npm `require` or `import` in application code. The primary interaction for enabling the test harness is via the Cordova CLI.

Quickstart

This code snippet demonstrates how to define automated tests for a Cordova plugin using the `cordova-plugin-test-framework` and Jasmine 2.0 syntax.

/* In your plugin's 'tests/tests.js' file */

exports.defineAutoTests = function() {
  describe('Cordova Test Framework Basic Tests', function() {
    beforeEach(function() {
      // Optional: Setup code before each test
      console.log('Running test setup...');
    });

    it('should confirm window.cordova exists', function() {
      expect(window.cordova).toBeDefined();
      expect(typeof window.cordova).toBe('object');
    });

    it('should allow adding other plugins for testing', function() {
      // Example for a hypothetical device plugin
      // In a real scenario, cordova-plugin-device-tests would be added
      if (window.cordova && window.cordova.plugins && window.cordova.plugins.device) {
        expect(window.cordova.plugins.device).toBeDefined();
        expect(typeof window.cordova.plugins.device.platform).toBe('string');
      } else {
        pending('cordova-plugin-device is not available for testing.');
      }
    });

    // You can also define manual tests
    // exports.defineManualTests = function() { /* ... */ };
  });

  // To run this, you would add your plugin's tests as a sub-plugin:
  // cordova plugin add https://github.com/apache/cordova-plugin-device.git#:/tests
  // Then add the test framework:
  // cordova plugin add cordova-plugin-test-framework
  // Finally, set your config.xml to load the test harness:
  // <content src="cdvtests/index.html" />
};