You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by ja...@apache.org on 2018/11/27 18:02:09 UTC
[cordova-paramedic] 01/04: Improve readme (WIP)
This is an automated email from the ASF dual-hosted git repository.
janpio pushed a commit to branch janpio-readme
in repository https://gitbox.apache.org/repos/asf/cordova-paramedic.git
commit 0be186698ec34fe4054d908f7f0b6bfc56498e01
Author: Jan Piotrowski <pi...@gmail.com>
AuthorDate: Sat Nov 24 18:37:22 2018 +0100
Improve readme (WIP)
---
README.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++---------------
1 file changed, 74 insertions(+), 23 deletions(-)
diff --git a/README.md b/README.md
index 50b522b..e251c0f 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,90 @@
-# cordova-paramedic
+[](https://travis-ci.org/apache/cordova-paramedic)
+[](https://ci.appveyor.com/project/ApacheSoftwareFoundation/cordova-paramedic)
> Paramedic • _noun_ provides advanced levels of care at the point of illness or injury, including out of hospital treatment, and diagnostic services
-[](https://travis-ci.org/apache/cordova-paramedic)
-[](https://ci.appveyor.com/project/ApacheSoftwareFoundation/cordova-paramedic)
-Runs cordova medic/buildbot tests locally.
+# Cordova Paramedic (Test Automation)
+
+`cordova-paramedic` is a tool to automate testing of Cordova plugins.
+
+You can use Paramedic to build and run a Cordova app with tests, run these tests on local and remote emulators (currently supported providers: [Sauce Labs](https://saucelabs.com/)) and report the results. It can be used on a local or on a Continuous Integration environment.
+
+It is currently used to automatically run all plugin tests on CI.
See this [workshop instructions for more explanation](https://kerrishotts.github.io/pgday/workshops/2017/campp/testing.html#cordova-paramedic).
+TODO paramedic server!?
+
## Supported Cordova Platforms
- Android
- iOS
-- Windows (Windows 8.1, Windows 10 UWP phone,tablet,desktop)
+- Windows Phone 8
+- Windows (Windows 8.1, Windows Phone 8.1, Windows 10 Tablet/PC)
- Browser
- OSX
-# Installation
+## What?
+
+A typical Paramedic run will:
+
+1. Create a temporary Cordova project with `cordova create`
+1. Install various plugins with `cordova plugin add ...`:
+ - the plugin to be tested (e.g. `cordova-plugin-inappbrowser`)
+ - the tests of this plugin (e.g. `cordova-plugin-inappbrowser\tests`)
+ - `cordova-plugin-test-framework` (from npm)
+ - local `paramedic-plugin`
+1. Update the app start page to the test page at `cdvtests/index.html` (provided by `cordova-plugin-test-framework` and the plugin tests)
+1. Add the platform to be tested with `cordova platform add ...`
+1. Confirm the requirements for that platform are met with `cordova requirements ...`
+1. Start a local "medic" server
+1. Start a local Android emulator or use a running one (`--target` param)
+1.
+
+
+If running for Sauce Labs:
+- Step 7 is skipped, remote emulators will be used
+-
+
+```
+$ cordova create C:\Users\Jan\AppData\Local\Temp\tmp-50936Js2WU3pm4Qn6 --no-telemetry --no-update-notifier
+$ cordova plugin add C:\Users\Jan\AppData\Local\Temp\tmp-50936Js2WU3pm4Qn6\plugins\cordova-plugin-inappbrowser\tests --no-telemetry --no-update-notifier
+$ cordova plugins --no-telemetry --no-update-notifier
+cordova-paramedic: installing cordova-plugin-test-framework --no-telemetry --no-update-notifier
+$ cordova plugin add cordova-plugin-test-framework --no-telemetry --no-update-notifier
+$ cordova platform add android --no-telemetry --no-update-notifier
+
+
+local-server: scanning ports from 7008 to 7208
+local-server: port 7030 is available
+local-server: starting local medic server
+cordova-paramedic: writing medic log url to project http://10.0.2.2:7030
+Start running tests at 5:33:13 PM
+cordova-paramedic: Choosing Target for Android
+cordova-paramedic: Starting an Android emulator
-``` $npm install cordova-paramedic ```
-# Usage
-Paramedic parameters could be passed via command line arguments or via separate configuration file:
+## Installation
+
+```
+npm install -g cordova-paramedic
+// or
+git clone https://github.com/apache/cordova-paramedic
+// when cloning, you have to replace all `cordova-paramedic` occurencey below with `cordova-paramedic/main.js`
+```
+
+## Usage
+
+Paramedic parameters can be passed via command line arguments or via separate configuration file:
```
cordova-paramedic --platform PLATFORM --plugin PATH <other parameters>
cordova-paramedic --config ./sample-config/.paramedic.config.js
```
-## Command Line Interface
+### Command Line Interface
#### `--platform` (required)
@@ -45,7 +99,7 @@ cordova-paramedic --platform ios@https://github.com/apache/cordova-ios.git#4.1.0
#### `--plugin` (required)
-Specifies 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.
+Specifies 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.
If the plugin requires variables to install, you can specify them along with its name.
```
@@ -55,6 +109,7 @@ cordova-paramedic --platform ios --plugin https://github.com/apache/cordova-plug
// several plugins
cordova-paramedic --platform ios --plugin cordova-plugin-inappbrowser --plugin cordova-plugin-contacts
```
+
#### `--justbuild` (optional)
Just builds the project, without running the tests.
@@ -153,14 +208,6 @@ iOS only parameter. The path to the sample TCC DB file, with permissions, to be
cordova-paramedic --platform ios --plugin cordova-plugin-contacts --tccDbPath tcc.db
```
-#### `--target` (optional)
-
-Android only parameter. The device ID (from `adb devices`) of a device the tests should be run on.
-
-```
-cordova-paramedic --platform android --plugin cordova-plugin-contacts --target 02e7f7e9215da7f8
-```
-
### Sauce-only arguments
#### `--shouldUseSauce` (optional)
@@ -202,11 +249,14 @@ cordova-paramedic --platform ios --plugin cordova-plugin-contacts --shouldUseSau
## Configuration file
Configuration file is used when no parameters are passed to `cordova-paramedic` call or explicitly specified via `--config` parameter:
+
```
-cordova-paramedic <- paramedic will attempt to find .paramedic.config.js in working directory
+cordova-paramedic <- paramedic will attempt to find .paramedic.config.js in working directory
cordova-paramedic --config ./sample-config/.paramedic.config.js
```
+
Example configuration file is showed below.
+
```
module.exports = {
// "externalServerUrl": "http://10.0.8.254",
@@ -219,6 +269,7 @@ module.exports = {
"args": "--archs=x64 -- --appx=uap"
}
```
+
More configuration file examples could be found in `sample-config` folder.
## Windows quirks
@@ -227,9 +278,9 @@ For paramedic to work correctly on Windows you'll need to allow the loopback for
## API Interface
-You can also use cordova-paramedic as a module directly :
+You can also use cordova-paramedic as a module directly:
```
- var paramedic = require('cordova-paramedic');
- paramedic.run(config);
+var paramedic = require('cordova-paramedic');
+paramedic.run(config);
```
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org