{"id":22308767,"url":"https://github.com/ratson/cordova-testbed","last_synced_at":"2025-03-26T01:28:55.136Z","repository":{"id":57209310,"uuid":"136504573","full_name":"ratson/cordova-testbed","owner":"ratson","description":null,"archived":false,"fork":false,"pushed_at":"2019-05-12T15:45:40.000Z","size":658,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-30T22:51:28.419Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ratson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-07T16:33:53.000Z","updated_at":"2019-05-12T15:45:42.000Z","dependencies_parsed_at":"2022-09-18T01:46:38.878Z","dependency_job_id":null,"html_url":"https://github.com/ratson/cordova-testbed","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ratson%2Fcordova-testbed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ratson%2Fcordova-testbed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ratson%2Fcordova-testbed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ratson%2Fcordova-testbed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ratson","download_url":"https://codeload.github.com/ratson/cordova-testbed/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245571263,"owners_count":20637311,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-03T20:15:13.030Z","updated_at":"2025-03-26T01:28:55.109Z","avatar_url":"https://github.com/ratson.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/apache/cordova-paramedic.svg?branch=master)](https://travis-ci.org/apache/cordova-paramedic)\n[![Build status](https://ci.appveyor.com/api/projects/status/iufmfjo0j0dd4c1w?svg=true)](https://ci.appveyor.com/project/ApacheSoftwareFoundation/cordova-paramedic)\n\n\u003e Paramedic • _noun_ provides advanced levels of care at the point of illness or injury, including out of hospital treatment, and diagnostic services\n\n# Cordova Paramedic (Test Automation)\n\n`cordova-paramedic` is a tool to automate execution of Cordova plugins tests (via [`cordova-plugin-test-framework`](https://github.com/apache/cordova-plugin-test-framework)).\n\nYou can use Paramedic to build and run a Cordova app with plugin tests, run these tests on local and remote emulators on [Sauce Labs](https://saucelabs.com/), and report the results. It can be used on a local or Continuous Integration environment.\n\nCordova Paramedic is currently used to automatically run all plugin tests on CI.\n\n(See this [workshop instructions for some additional explanation](https://kerrishotts.github.io/pgday/workshops/2017/campp/testing.html#cordova-paramedic).)\n\n## Table of Contents\n\n- [Supported Cordova Platforms](#supported-cordova-platforms)\n- [What does it do?](#what-does-it-do)\n- [Installation](#installation)\n- [Usage](#usage)\n  * [Common usages](#common-usages)\n- [Command Line Interface](#command-line-interface)\n  * [What to build and test](#what-to-build-and-test)\n  * [Emulator/Device to use for tests](#emulatordevice-to-use-for-tests)\n  * [Test Result Server](#test-result-server)\n  * [Test Configuration](#test-configuration)\n  * [Sauce Labs](#sauce-labs)\n- [Configuration file](#configuration-file)\n- [API Interface](#api-interface)\n- [Quirks](#quirks)\n  * [Windows](#windows)\n\n\u003c!--\u003csmall\u003e\u003ci\u003e\u003ca href='http://ecotrust-canada.github.io/markdown-toc/'\u003eTable of contents generated with markdown-toc\u003c/a\u003e\u003c/i\u003e\u003c/small\u003e--\u003e\n\n## Supported Cordova Platforms\n\n- Android\n- iOS\n- Windows\n- Browser\n\n## What does it do?\n\nA full Paramedic run will:\n\n1. \u003cdetails\u003e\n    \u003csummary\u003eCreate and prepare the app\u003c/summary\u003e\n\n    1. Create a temporary Cordova project with `cordova create`\n    1. Install various plugins with `cordova plugin add %local_path%` (e.g. `cordova plugin add ../cordova-plugin-inappbrowser`):\n        - the plugin to be tested (e.g. `../cordova-plugin-inappbrowser`)\n        - the tests of this plugin (e.g. `../cordova-plugin-inappbrowser/tests`)\n        - `cordova-plugin-test-framework` (from npm)\n        - local `paramedic-plugin`\n    1. Update the app start page to the test page at `cdvtests/index.html` (provided by `cordova-plugin-test-framework` and the plugin tests)\n    1. Add the platform to be tested with `cordova platform add ...`\n    1. Confirm the requirements for that platform are met with `cordova requirements ...`\n    1. Start a local socket server for communication between the app running on a device/emulator and paramedic\n    1. Make the server address known to the app\n    \u003c/details\u003e\n1. Run the tests \u003c!-- 2-99 --\u003e\n    - \u003cdetails\u003e\n      \u003csummary\u003eEither run the main tests locally...  \u003c!-- 5-316 --\u003e\u003c/summary\u003e\n\n        1. Skip main tests if option set (platform != android) \u003c!-- 5-322 --\u003e\n        1. Start a file transfer server if required\n        1. Get the test command for the platform\n        1. Manipulate permissions on iOS\n        1. Run the app (open in browser, start emulator, run on device or emulator) and start the tests by doing so\n        1. Skip main tests if option set \u003c!-- 6-350 --\u003e\n        1. Skip tests if action = run|emulate (= build) \u003c!-- 6-356 --\u003e\n        1. Wait for device to connect to server before timeout \u003c!-- 6-359 --\u003e\n        1. Wait for the tests results \u003c!-- 6-361--\u003e\n            1. Time out if \"connection takes to long\" TODO (failure) \u003c!-- 8-479--\u003e\n            1. Receive and handle \"tests are done\" (success) and \"device disconnected\" (failure) events \u003c!-- 8-485--\u003e\n        1. (browser) Close the running browser \u003c!-- 6-368 --\u003e\n        1. Run the Appium tests (with sauce = false) \u003c!-- 7-465 --\u003e\n        \u003c/details\u003e\n    - \u003cdetails\u003e\n      \u003csummary\u003e... or on Sauce Labs\u003c/summary\u003e\n\n        1. Build, package and upload the app to Sauce Labs or (platform = browser) open the app in a browser\n        1. (platform = browser) Connect to Sauce Connect (Proxy)\n        1. Connect to Web Driver on Sauce Labs\n        1. Navigate Web Driver to correct page (browser) or webview (apps)\n        1. Click \"Auto Tests\" if a plugin `*wkwebview*` is installed\n        1. Find out if the \"permission buster\" should be skipped (plugins splashscreen or inappbrowser, browser): `skipBuster`\n        1. Start polling in the background for events using the Web Driver (submitting `skipBuster` as well) every 2.5 seconds\n        1. Wait for the tests results\n            1. Time out if \"connection takes to long\" TODO (failure)  \u003c!-- 8-479--\u003e\n            1. Receive and handle \"tests are done\" (success) and \"device disconnected\" (failure) events\u003c!-- 8-485--\u003e\n        1. Log success or failure\n        1. Quit Web Driver\n        1. (platform = browser) Close the open browser \u003c!-- 16-1056 --\u003e\n        1. Close connection to Sauce Connect (Proxy)\n        1. Run the Appium tests on Sauce Labs (with sauce = true) \u003c!-- 7-454 --\u003e\n        \u003c/details\u003e\n    - \u003cdetails\u003e\n      \u003csummary\u003eRun the Appium tests \u003c!-- 6-379 --\u003e\u003c/summary\u003e\n\n        1. Skip if action = build \u003c!-- 6-384 --\u003e\n        1. Skip is Appium should be skipped \u003c!-- 6-388 --\u003e\n        1. Skip if platform != android or ios \u003c!-- 6-392 --\u003e\n        1. !sauce: Error when no targetObj TODO \u003c!-- 6-397 --\u003e\n        1. Create Appium options \u003c!-- 7-403 --\u003e\n        1. Create AppiumRunner with options \u003c!-- 7-426 --\u003e\n            1. Prepare the submitted options \u003c!-- AppiumRunner 151 --\u003e\n            1. Create screenshot directory \u003c!-- AppiumRunner 147 --\u003e\n            1. Find the tests in plugin paths \u003c!-- AppiumRunner 307 --\u003e\n            1. Set globals for the tests \u003c!-- AppiumRunner 334 --\u003e\n        1. Skip if no Appium tests were found \u003c!-- 7-427 --\u003e  \n        1. Prepare App in AppiumRunner \u003c!-- 7-433 --\u003e\n            1. Remove server address from app\n            2. Reconfigure app (modify preferences + CSP, add plugin) \u003c!-- 367, 375, 385 -- \u003e\n            3. Build app\n        1. (sauce) Package and Upload the App to Sauce Labs \u003c!-- 7-436 --\u003e\n        1. Run tests via AppiumRunner \u003c!-- 7-442 --\u003e\n            1. (!sauce) Start iOS Proxy (`ios_webkit_debug_proxy`) \u003c!-- AppiumRunner 231 --\u003e\n            1. (!sauce) Install (`npm install appium`) \u003c!-- AppiumRunner 231 --\u003e and start Appium server \u003c!-- AppiumRunner 252 --\u003e\n            1. Start to run the Appium tests \u003c!-- AppiumRunner 170 --\u003e\n            1. Handle eventual exceptions, return the result\n      \u003c/details\u003e\n1. \u003cdetails\u003e\n    \u003csummary\u003eClean up\u003c/summary\u003e\n\n    1. (!sauce) \u003c!-- 2-107 --\u003e\n        1. Handle timeouts of test execution above\n        1. Collect Device Logs\n        1. Uninstall App\n        1. Kill Emulator Process\n    1. (sauce) Display Sauce run details \u003c!-- 2-118 --\u003e\n    1. Clean up Project \u003c!-- 2-121 --\u003e\n    \u003c/details\u003e\n\n## Installation\n\n```\nnpm install -g cordova-paramedic\n\n# or\n\ngit clone https://github.com/apache/cordova-paramedic\n# when cloning, you have to run `npm link` inside the checkout\n# or replace all occurences of `cordova-paramedic` in commands with `cordova-paramedic/main.js`\n# or `node cordova-paramedic/main.js` (on Windows)\n```\n\n## Usage\n\nParamedic parameters can be passed via command line arguments or via separate configuration file:\n\n```\ncordova-paramedic --platform PLATFORM --plugin PATH \u003cother parameters\u003e\ncordova-paramedic --config ./sample-config/.paramedic.config.js\n```\n\n### Common usages\n\nSome common use cases of Paramedic:\n\n```\n# Run without any parameters to get a list of supported parameters\ncordova-paramedic\n\n# Test your current plugin on an Android emulator\ncordova-paramedic --platform android --plugin ./\n\n# Test your current plugin on a specific Android device (ID via `adb devices -l`)\ncordova-paramedic --platform android --plugin ./ --target 02e7f7e9215da7f8 --useTunnel\n\n# Test your current plugin on an Android 7.0 emulator on Sauce Labs\ncordova-paramedic --config conf/pr/android-7.0 --plugin ./\n```\n\n## Command Line Interface\n\n### What to build and test\n\n#### `--platform` (required)\n\nSpecifies target Cordova platform (could refer to local directory, npm or git)\n\n```\ncordova-paramedic --platform ios --plugin cordova-plugin-inappbrowser\ncordova-paramedic --platform ios@4.0 --plugin cordova-plugin-inappbrowser\ncordova-paramedic --platform ios@../cordova-ios --plugin cordova-plugin-inappbrowser\ncordova-paramedic --platform ios@https://github.com/apache/cordova-ios.git#4.1.0 --plugin cordova-plugin-inappbrowser\n```\n\n#### `--plugin` (required)\n\nSpecifies test plugin, you may specify multiple `--plugin` flags and they will all be installed and tested together. You can refer to absolute path, npm registry or git repo.\nIf the plugin requires variables to install, you can specify them along with its name.\n\n```\ncordova-paramedic --platform ios --plugin cordova-plugin-inappbrowser\ncordova-paramedic --platform ios --plugin 'azure-mobile-engagement-cordova --variable AZME_IOS_CONNECTION_STRING=Endpoint=0;AppId=0;SdkKey=0'\ncordova-paramedic --platform ios --plugin https://github.com/apache/cordova-plugin-inappbrowser\n// several plugins\ncordova-paramedic --platform ios --plugin cordova-plugin-inappbrowser --plugin cordova-plugin-contacts\n```\n\n#### `--verbose` (optional)\n\nVerbose mode. Display more information output\n\n```\ncordova-paramedic --platform ios --plugin cordova-plugin-inappbrowser --verbose\n```\n\n#### `--cli` (optional)\n\nA path to Cordova CLI. Useful when you're testing against locally installed Cordova version.\n\n```\ncordova-paramedic --platform android --plugin cordova-plugin-device --cli ./cordova-cli/bin/cordova\n```\n\n#### `--justbuild` (optional)\n\nJust builds the project, without running the tests.\n\n```\ncordova-paramedic --platform ios --plugin cordova-plugin-inappbrowser --justbuild\n```\n\n### Emulator/Device to use for tests\n\n#### `--target` (optional)\n\nFor Android: The device ID (from `adb devices -l`) of a device the tests should be run on.  \n\n```\ncordova-paramedic --platform android --plugin cordova-plugin-contacts --target 02e7f7e9215da7f8\n```\n\nFor iOS: A string that is used to pick the device (from the `cordova run --list --emulator` output) the tests should be run on.\n\n```\ncordova-paramedic --platform ios --plugin cordova-plugin-contacts --target \"iPhone-8\"\n```\n\n\n### Test Result Server\n\n#### `--useTunnel` (optional)\n\nUse a tunnel (via [`localtunnel`](https://www.npmjs.com/package/localtunnel)) instead of local address (default is false).\nUseful when testing on real devices and don't want to specify external IP address (see `--externalServerUrl` below) of paramedic server.\n\n```\ncordova-paramedic --platform ios --plugin cordova-plugin-inappbrowser --useTunnel\n```\n\n#### `--externalServerUrl` (optional)\n\nUseful when testing on real device (`--device` parameter) so that tests results from device could be posted back to paramedic server.\n\n```\ncordova-paramedic --platform ios --plugin cordova-plugin-inappbrowser --externalServerUrl http://10.0.8.254\n```\n\n#### `--port` (optional)\n\nPort to use for posting results from emulator back to paramedic server (default is from `8008`). You can also specify a range using `--startport` and `endport` and paramedic will select the first available.\n\n```\ncordova-paramedic --platform ios --plugin cordova-plugin-inappbrowser --port 8010\ncordova-paramedic --platform ios --plugin cordova-plugin-inappbrowser --startport 8000 endport 8020\n```\n\n### Test configuration\n\n#### `--timeout` (optional)\n\nTime in millisecs to wait for tests to pass|fail (defaults to 10 minutes).\n\n```\ncordova-paramedic --platform ios --plugin cordova-plugin-inappbrowser --timeout 30000\n```\n\n#### `--outputDir` (optional)\n\nDirectory location to store test results in junit format and the device logs\n\n```\ncordova-paramedic --platform ios --plugin cordova-plugin-inappbrowser --outputDir /Users/sampleuser/testresults\n```\n\n#### `--cleanUpAfterRun` (optional)\n\nFlag to indicate the sample application folder must be deleted.\n\n```\ncordova-paramedic --platform ios --plugin cordova-plugin-inappbrowser --cleanUpAfterRun\n```\n\n#### `--logMins` (optional)\n\nWindows only parameter to indicate the duration for which the device logs to be fetched.\n\n```\ncordova-paramedic --platform windows --plugin cordova-plugin-inappbrowser --logMins 15\n```\n\n#### `--tccDb` (optional)\n\niOS only parameter. The path to the sample TCC DB file, with permissions, to be copied to the simulator.\n\n```\ncordova-paramedic --platform ios --plugin cordova-plugin-contacts --tccDbPath tcc.db\n```\n\n#### `--args` (optional)\n\nAdd additional parameters to the `cordova build` and `cordova run` commands.\n\n```\ncordova-paramedic --platform ios --plugin cordova-plugin-contacts --args=--buildFlag='-UseModernBuildSystem=0'\n```\n\n### Sauce Labs\n\n#### `--shouldUseSauce` (optional)\n\nRun tests on [Sauce Labs](https://saucelabs.com/). You'll need to specify Sauce Labs username and access key using either `--sauceUser` and `--sauceKey` arguments or `SAUCE_USERNAME` and `SAUCE_ACCESS_KEY` environment variables.\n\n#### `--sauceUser` (optional)\n\nSauce Labs username. Alternatively set via the `SAUCE_USERNAME` environment variable.\n\n#### `--sauceKey` (optional)\n\nSauce Labs access key. Alternatively set via the `SAUCE_ACCESS_KEY` environment variable.\n\n```\ncordova-paramedic --platform ios --plugin cordova-plugin-contacts --shouldUseSauce --sauceUser ***** --sauceKey ***** --buildName \"paramedic-test-01\"\n```\n\n#### `--buildName` (optional)\n\nBuild name to show on Sauce Labs dashboard. If omitted, will use \"Paramedic sauce test\" and a timestamp.\n\n#### `--sauceDeviceName` (optional)\n\nName of the Sauce Labs emulator or browser. For example, \"iPhone Simulator\" or \"firefox\". Please refer to the [Sauce Labs platforms list](https://saucelabs.com/platforms) to see available device names.\n\n#### `--saucePlatformVersion` (optional)\n\nPlatform version of the Sauce Labs emulator OS, or version of the browser (if testing `browser` platform). For example, \"9.3\" or \"54.0\". Please refer to the [Sauce Labs platforms list](https://saucelabs.com/platforms) to see available platform versions.\n\n#### `--sauceAppiumVersion` (optional)\n\nAppium version to use when running on Sauce Labs. For example, \"1.5.3\".\n\n```\ncordova-paramedic --platform ios --plugin cordova-plugin-contacts --shouldUseSauce --sauceUser ***** --sauceKey ***** --sauceDeviceName 'iPad Simulator\" --saucePlatformVersion 9.1 --appiumVersion 1.5.2\n```\n\n## Configuration file\n\nConfiguration file is used when no parameters are passed to `cordova-paramedic` call or explicitly specified via `--config` parameter:\n\n```\ncordova-paramedic           \u003c- paramedic will attempt to find .paramedic.config.js in working directory\ncordova-paramedic --config ./sample-config/.paramedic.config.js\n```\n\nExample configuration file is showed below.\n\n```\nmodule.exports = {\n    // \"externalServerUrl\": \"http://10.0.8.254\",\n    \"useTunnel\": true,\n    \"plugins\": [\n        \"https://github.com/apache/cordova-plugin-inappbrowser\"\n    ],\n    \"platform\": \"windows\",\n    \"action\": \"run\",\n    \"args\": \"--archs=x64 -- --appx=uap\"\n}\n```\n\nMore configuration file examples could be found in `sample-config` folder.\n\n## API Interface\n\nYou can also use `cordova-paramedic` as a module directly:\n\n```javascript\nvar paramedic = require('cordova-paramedic');\nparamedic.run(config);\n```\n\n## Quirks\n\n### Windows\n\nFor Paramedic to work correctly for Windows apps you'll need to allow the loopback for \"HelloCordova\" app using [Windows Loopback Exemption Manager](https://github.com/tiagonmas/Windows-Loopback-Exemption-Manager) ([download](https://github.com/piksel/Windows-Loopback-Exemption-Manager/releases/tag/v1.0.0.1)).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fratson%2Fcordova-testbed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fratson%2Fcordova-testbed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fratson%2Fcordova-testbed/lists"}