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/29 14:31:55 UTC
[cordova-mobile-spec] branch master updated: Clean up and rewrite
READMEs (#154)
This is an automated email from the ASF dual-hosted git repository.
janpio pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-mobile-spec.git
The following commit(s) were added to refs/heads/master by this push:
new e152aa5 Clean up and rewrite READMEs (#154)
e152aa5 is described below
commit e152aa56ba9b02a28e97a21cd7446d99b950bcd0
Author: Jan Piotrowski <pi...@gmail.com>
AuthorDate: Thu Nov 29 15:31:50 2018 +0100
Clean up and rewrite READMEs (#154)
- Remove JIRA mentions
- Extract Running a Local File-Transfer Server (see https://github.com/apache/cordova-labs/pull/14 where the content ends up)
- Delete super old performance testing results
- Rewrite all the instructions
---
AndroidBridgePerformance_300.pdf | Bin 611523 -> 0 bytes
CONTRIBUTING.md | 5 --
README.md | 65 ++++++++------------------
cordova-plugin-echo/README.md | 1 -
createmobilespec/README.md | 97 ++++++++++++++++++++++-----------------
5 files changed, 73 insertions(+), 95 deletions(-)
diff --git a/AndroidBridgePerformance_300.pdf b/AndroidBridgePerformance_300.pdf
deleted file mode 100644
index 36f28fb..0000000
Binary files a/AndroidBridgePerformance_300.pdf and /dev/null differ
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4c8e6a5..fdbfbe8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -29,9 +29,4 @@ contribute code.
For instructions on this, start with the
[contribution overview](http://cordova.apache.org/contribute/).
-The details are explained there, but the important items are:
- - Sign and submit an Apache ICLA (Contributor License Agreement).
- - Have a Jira issue open that corresponds to your contribution.
- - Run the tests so your patch doesn't break existing functionality.
-
We look forward to your contributions!
diff --git a/README.md b/README.md
index f1f0de9..42c4118 100644
--- a/README.md
+++ b/README.md
@@ -18,63 +18,34 @@
# under the License.
#
-->
-## Mobile Spec Suite ##
+# Cordova Mobile Spec Suite
-This project is a set of automated & manual tests that test
-Cordova core functionality.
+This `cordova-mobile-spec` repository can be used to create a Cordova app that provides a set of manual tests to verify Cordova core functionality. It is currently used in the [release processes of platforms, plugins and tools](https://github.com/apache/cordova-coho/tree/master/docs#release-processes).
-To set up the project, use
-`cordova-mobile-spec/createmobilespec/createmobilespec.js`.
-See the [README.md](createmobilespec/README.md) in that directory.
+It also provides access to [manual and automated tests of the installed plugins (via `cordova-plugin-test-framework`)](https://github.com/apache/cordova-plugin-test-framework).
-### Requirements ###
+(History: A very long time ago this repository also _included_ all the manual and automated plugin tests before those were extracted and moved into the plugins themselves.)
-Repositories required:
+## Overview
-- **cordova-cli**
- (Install pre-requisites by running `npm install` inside of cordova-cli).
-- **cordova-js**
-- All **plugins**.
-- **Platforms** to test
- (e.g., cordova-android, cordova-ios, cordova-blackberry,
- cordova-wp8, or cordova-windows).
-- **cordova-mobile-spec**
- (Install pre-requisites by running `npm install` inside of
- [createmobilespec](createmobilespec)).
-- All repositories must be checked out as peers to each other.
+This repository has 3 parts:
-### Performance ###
+1. This main folder is a Cordova app "template" (`config.xml` and `www`) that includes implementations of various functionalities that Cordova supports (battery, events, keyboard, lazyloadjs, splashscreens, sql, storage, misc) that can manually be tested, some benchmarks, and a link to the automated and manual tests installed plugins offer (`cdvtests/index.html`).
-For reference purposes, the document
-[AndroidBridgePerformance_300.pdf](AndroidBridgePerformance_300.pdf)
-in this directory outlines the Android bridge performance using
-`cordova-mobile-spec` and the manual bridge test.
-The tests were performed with **Cordova 3.0.0**.
+2. There are 4 plugins as well: [`cordova-plugin-echo`](cordova-plugin-echo) ("plugin implementation of the Echo function to test the bridge"), [`cordova-plugin-mobilespec-tests`](cordova-plugin-mobilespec-tests) ("Cordova Non Plugin Auto Tests"), [`cordova-plugin-thirdparty-tests`](cordova-plugin-thirdparty-tests) ("Tests for popular third-party plugins") and [`cordova-plugin-whitelist`](cordova-plugin-whitelist) (TODO).
-## Running a Local File-Transfer Server
+3. The `createmobilespec` folder contains a script/CLI to create a Cordova app
-The `cordova-vm` file-transfer server could be offline for the `cordova-plugin-file-transfer` tests.
+ 1. using the locally installed Cordova CLI, the currently up to date (published on npm) platforms and plugins (including their tests!), and the 4 local plugins from 2) (mode `--global`) or
+ 2. using local checkouts (via `cordova-coho`) of all these (CLI, tools, platforms, plugins...) or
+ 3. with several other modes (to e.g. use plugman and /bin/create instead of the CLI)
-The server to run is at:
-https://github.com/apache/cordova-labs/tree/cordova-filetransfer
+The end result is a folder `../mobilespec` with a Cordova app that can be installed on devices. It can be used for some manual testing with the functionality offered by 1) or run the [tests additionally provided by the plugins via `cordova-plugin-test-framework`](https://github.com/apache/cordova-plugin-test-framework).
-And you would override this variable for this test plugin:
-https://github.com/apache/cordova-plugin-file-transfer/blob/9b322dec6790f6d273b8f707bc07976d778c4cf6/tests/plugin.xml#L33
-```
-## in your mobilespec test project, run...
-cordova plugin rm cordova-plugin-file-transfer-tests
-cordova plugin add path/to/cordova-plugin-file-transfer/tests --variable FILETRANSFER_SERVER_ADDRESS="http://yourlocal-IPAddressHere:5000"
-```
+## Usage
-Run the server:
-```
-git clone https://github.com/apache/cordova-labs.git
-cd cordova-labs
-git checkout cordova-filetransfer
-node server.js
-```
+See the [`README.md` in `/createmobilespec`](createmobilespec/README.md) for usage instruction on how to create the "mobilespec" app.
-Get your local ip by running:
-```
-ifconfig
-```
+### Cordova Plugin File-Transfer Tests
+
+Tests of Cordova Plugin File-Transfer require a test server. [Follow these instructions to install and run the server and configure the plugin.](https://github.com/apache/cordova-labs/tree/cordova-filetransfer)
diff --git a/cordova-plugin-echo/README.md b/cordova-plugin-echo/README.md
index 519387a..0b0e8f9 100644
--- a/cordova-plugin-echo/README.md
+++ b/cordova-plugin-echo/README.md
@@ -23,4 +23,3 @@ cordova-plugin-echo
------------------------
This is a plugin implementation of the Echo function to test the bridge. It is currently used by Mobile Spec to test and benchmark the bridge.
-
diff --git a/createmobilespec/README.md b/createmobilespec/README.md
index c3c22d2..29a1ecb 100644
--- a/createmobilespec/README.md
+++ b/createmobilespec/README.md
@@ -19,20 +19,15 @@
#
-->
-## Creating the mobile-spec app
+# Creating the mobile-spec app
`createmobilespec.js` is a script for creating a test app that has:
- * the **mobile-spec** code from the local `cordova-mobile-spec` git repo
- * a `cordova.js` file that is freshly built from the local `cordova-js`
- git repo
- * the platform (e.g., **Android**) from the local platform git repo (e.g.,
- `cordova-android`)
- * all the plugins from the local plugin repos (e.g., cordova-plugin-device)
- * it was built using the local `cordova-cli` and `cordova-plugman` git repos
-
- Many places in this document that say *git repo*
- may also mean *npm repository*.
+* local `cordova-mobile-spec`
+* a `cordova.js` file that is freshly built from the local `cordova-js` folder
+* the platform (e.g. Android) from the local platform folder (e.g. `cordova-android`)
+* all the plugins from the local plugin folders (e.g. `cordova-plugin-device`)
+* it was built using the local `cordova-cli` and `cordova-plugman` folders
In other words, it is a great way to test your local development efforts.
@@ -41,47 +36,65 @@ globally-installed npm module, a way to use the platform's `cordova.js` file
instead of building it from the local `cordova-js` git repo,
and a way to use the platform-centered workflow instead of the CLI.
-### Requirements
+## Requirements and Preparation
+
+1. Your Cordova projects have to be checked out and set up in a very specific way: All checkouts have to be siblings (= same parent folder) and the common Cordova libraries have to be npm-linked.
+
+ The easiest and quickest way to achieve this is by using `cordova-coho`:
+
+ ```shell
+ # Create a new folder, e.g. `cordova` and `cd cordova` into it.
+ git clone https://github.com/apache/cordova-coho.git
+ cd cordova-coho & npm install & cd ..
+ node cordova-coho/coho repo-clone -r mobile-spec -r tools -r plugins -r active-platforms
+ node cordova-coho/coho npm-link
+ ```
+
+ After this you should have 30+ folders in your `cordova` folder.
+
+2. As `cordova-mobile-spec` has a special structure, you have to install dependencies in `createmobilespec` manually:
+ ```shell
+ cd cordova-mobile-spec/createmobilespec & npm install & cd ../..
+ ```
+3. You are now ready to use `createmobilespec.js` with the commands below.
+
+## Usage
+
+The `createmobilespec.js` script also needs to be invoked from the "main" folder you created before (`cordova`):
+
+ cordova-mobile-spec/createmobilespec/createmobilespec.js
+
+On Windows, prefix all commands with `node`:
+
+ node cordova-mobile-spec/createmobilespec/createmobilespec.js
+
+To see the options available in the script, run it with the `-h` option to print the online help.
+
+ (node) cordova-mobile-spec/createmobilespec/createmobilespec.js -h
-See the [README.md](../README.md) in the parent directory
-[cordova-mobile-spec](..).
+If anything is going wrong and the existing output does not help, add the `--debug` parameter:
-Each git repo should be checked out to the state or edited with the content
-that you want to test. Be **aware** that it **will** **download** missing plugin content from the
-[plugin registry](http://plugins.cordova.io)
-nor does it fetch platforms from the npm repository.
+ (node) cordova-mobile-spec/createmobilespec/createmobilespec.js --debug
- Except, I think it does...
+### Create the App
-Before running `createmobilespec.js` for the first time, run `npm install`
-from within the [createmobilespec](.) directory to install the requisite
-third-party **Node** modules. This should be a one-time activity,
-unless there is a change in the pre-reqs.
+Caution: If the generated `mobilespec` project already exists, it is recommended
+to delete the project before proceeding.
-### Running
+To for example create the app for the Android platform, run:
-The `createmobilespec.js` script needs to be invoked from a specific
-current working directory:
-the one where you have all the git repos cloned.
-So if you were to do an `ls` in that directory,
-you should see all the git repos including `cordova-mobile-spec`.
-Thus an invocation should look like:
+ (node) cordova-mobile-spec/createmobilespec/createmobilespec.js --android
- cordova-mobile-spec/createmobilespec/createmobilespec.js
+### Run the App
-To see the options available in the script,
-run it with the `-h` option to print the online help.
+After the script successfully finished and created the app, you can run the app on a device or simulator, using the standard method for that platform(s). For example on **Android**:
-After you have run the script to create the app,
-then you can run the app on a device or simulator,
-using the standard method for that platform(s).
-For example on **Android**:
+ cd mobilespec
+ ./cordova run android
- cd mobilespec
- ./cordova run android
+## Potential Quirks and Issues
Some known quirks and issues:
-* `npm install` inside `cordova-js` is needed to resolve a local grunt issue
-* A Gradle file in `platforms/android` subdirectory tries to read non-existing debug keys. Workaround is to comment the lines out of the Gradle file.
-* It may be required to uninstall the `cordova-plugin-compat` plugin due to multiple "BuildHelper" classes defined in dex files (<https://stackoverflow.com/questions/46562289/multiple-dex-files-define-lorg-apache-cordova-buildhelper/46562523#46562523>)
+* [`npm install` inside `cordova-js` is needed to resolve a local grunt issue](https://github.com/apache/cordova-mobile-spec/issues/150)
+* [It may be required to uninstall the `cordova-plugin-compat` plugin due to multiple "BuildHelper" classes defined in dex files](https://github.com/apache/cordova-mobile-spec/issues/151)(<https://stackoverflow.com/questions/46562289/multiple-dex-files-define-lorg-apache-cordova-buildhelper/46562523#46562523>)
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org