Skip to content
Permalink
Browse files
Clean up and rewrite READMEs (#154)
- Remove JIRA mentions
- Extract Running a Local File-Transfer Server (see apache/cordova-labs#14 where the content ends up)
- Delete super old performance testing results
- Rewrite all the instructions
  • Loading branch information
janpio committed Nov 29, 2018
1 parent 9685002 commit e152aa56ba9b02a28e97a21cd7446d99b950bcd0
Showing 5 changed files with 73 additions and 95 deletions.
Binary file not shown.
@@ -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!
@@ -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)
@@ -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.

@@ -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>)

0 comments on commit e152aa5

Please sign in to comment.