{"id":10673,"library":"cordova-plugin-test-framework","title":"Cordova Plugin Test Framework","description":"The `cordova-plugin-test-framework` provides a structured approach for Cordova plugin developers to create and run tests directly within their Cordova projects. It establishes an interface where plugins can bundle their tests as nested plugins within a `/tests` directory, using a `plugin.xml` and `package.json` for definition and dependency management. The framework then offers a test harness to execute these tests, utilizing the Jasmine 2.0 format for defining test suites (`describe`, `it`). This allows for rapid iteration between development and testing, ensuring tests run against the exact versions of plugins and platforms in use. The latest published version is 1.1.6. However, the project appears to be largely unmaintained, with its last significant activity on npm and GitHub over seven years ago, suggesting an effectively abandoned status. It differentiates itself by integrating tests directly into the Cordova build lifecycle, rather than relying on external, separate test runners.","status":"abandoned","version":"1.1.6","language":"javascript","source_language":"en","source_url":"https://github.com/apache/cordova-plugin-test-framework","tags":["javascript","cordova","test","ecosystem:cordova"],"install":[{"cmd":"npm install cordova-plugin-test-framework","lang":"bash","label":"npm"},{"cmd":"yarn add cordova-plugin-test-framework","lang":"bash","label":"yarn"},{"cmd":"pnpm add cordova-plugin-test-framework","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { defineAutoTests } from 'my-plugin-tests';","symbol":"defineAutoTests","correct":"exports.defineAutoTests = function() { /* ... */ }"},{"note":"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.","wrong":"import { describe } from 'jasmine';","symbol":"describe","correct":"describe('My Test Suite', function() { /* ... */ });"},{"note":"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.","wrong":"npm install cordova-plugin-test-framework","symbol":"Test Harness","correct":"cordova plugin add cordova-plugin-test-framework"}],"quickstart":{"code":"/* In your plugin's 'tests/tests.js' file */\n\nexports.defineAutoTests = function() {\n  describe('Cordova Test Framework Basic Tests', function() {\n    beforeEach(function() {\n      // Optional: Setup code before each test\n      console.log('Running test setup...');\n    });\n\n    it('should confirm window.cordova exists', function() {\n      expect(window.cordova).toBeDefined();\n      expect(typeof window.cordova).toBe('object');\n    });\n\n    it('should allow adding other plugins for testing', function() {\n      // Example for a hypothetical device plugin\n      // In a real scenario, cordova-plugin-device-tests would be added\n      if (window.cordova && window.cordova.plugins && window.cordova.plugins.device) {\n        expect(window.cordova.plugins.device).toBeDefined();\n        expect(typeof window.cordova.plugins.device.platform).toBe('string');\n      } else {\n        pending('cordova-plugin-device is not available for testing.');\n      }\n    });\n\n    // You can also define manual tests\n    // exports.defineManualTests = function() { /* ... */ };\n  });\n\n  // To run this, you would add your plugin's tests as a sub-plugin:\n  // cordova plugin add https://github.com/apache/cordova-plugin-device.git#:/tests\n  // Then add the test framework:\n  // cordova plugin add cordova-plugin-test-framework\n  // Finally, set your config.xml to load the test harness:\n  // <content src=\"cdvtests/index.html\" />\n};","lang":"javascript","description":"This code snippet demonstrates how to define automated tests for a Cordova plugin using the `cordova-plugin-test-framework` and Jasmine 2.0 syntax."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0 (from when package.json became required for nested plugins)"},{"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.","message":"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).","severity":"gotcha","affected_versions":">=1.1.6 (due to age)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","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.","error":"Plugin doesn't have a package.json"},{"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`.","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.","error":"describe is not defined"},{"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.","cause":"An npm dependency required by your test files (e.g., for mocking or utility functions) has not been installed.","error":"Error: Cannot find module 'my-test-dependency'"}],"ecosystem":"npm"}