Registry /
testing / cordova-plugin-test-framework
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
defineAutoTests
✓ exports.defineAutoTests = function() { /* ... */ }
✗ import { defineAutoTests } from 'my-plugin-tests';
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
✓ describe('My Test Suite', function() { /* ... */ });
✗ import { describe } from 'jasmine';
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
✓ cordova plugin add cordova-plugin-test-framework
✗ npm install 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.
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" />
};
Debug
Known issues
breakingOlder 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.fixEnsure 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.
affects: >=1.0.0 (from when package.json became required for nested plugins)
gotchaThis 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).fixConsider 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.
affects: >=1.1.6 (due to age)
gotchaThe 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.fixBe 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.
affects: *
gotchaTo 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.fixAfter 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.
affects: *
Errors
Common errors & fixes
Plugin doesn't have a package.json
The nested test plugin within your main plugin's `/tests` directory is missing a `package.json` file, which is now required by Cordova tooling.
fixCreate 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
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.
fixEnsure `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'
An npm dependency required by your test files (e.g., for mocking or utility functions) has not been installed.
fixAdd 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.
Audit
Dependencies
No dependency data recorded yet.