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/12/05 15:25:22 UTC
[cordova-plugin-test-framework] branch master updated: Clean up and
improve README (#29)
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-plugin-test-framework.git
The following commit(s) were added to refs/heads/master by this push:
new 7520926 Clean up and improve README (#29)
7520926 is described below
commit 7520926d69d05cfc0075501eaf403c197ef10545
Author: Jan Piotrowski <pi...@gmail.com>
AuthorDate: Wed Dec 5 16:25:18 2018 +0100
Clean up and improve README (#29)
* Clean up README
* introduction
---
README.md | 58 ++++++++++++++++++++++++++++++++++------------------------
1 file changed, 34 insertions(+), 24 deletions(-)
diff --git a/README.md b/README.md
index 4bedaec..4cc81cd 100644
--- a/README.md
+++ b/README.md
@@ -23,26 +23,30 @@
# Cordova Plugin Test Framework
-The `cordova-plugin-test-framework` plugin does two things:
+The `cordova-plugin-test-framework` plugin allows plugin authors to add tests (manual and automated) to their plugins. To achieve this it
-1. [Defines the interface for cordova plugins to write tests](#interface)
-2. [Provides a test harness for actually running those tests](#harness)
+1. [defines the interface for Cordova plugins to write tests](#interface) and
+2. [provides a test harness for actually running those tests](#harness)
-Tests run directly inside existing cordova projects, so you can rapidly switch between testing and development. You can also be sure that your test suite is testing the exact versions of plugins and platforms that your app is using.
+Tests run directly inside existing Cordova projects, so you can rapidly switch between testing and development. You can also be sure that your test suite is testing the exact versions of plugins and platforms that your app is using.
# TLDR; Try it
-1. Use your existing cordova app, or create a new one.
-2. Plugins bundle their tests using a nested plugin in a `/tests` directory. To make this interesting, add some of these plugins and their respective tests. Here are a few examples:
+1. Use your existing Cordova app, or create a new one.
+2. Plugins bundle their tests using a nested plugin in a `/tests` directory. Here are a few examples how install both:
- cordova plugin add http://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git
- cordova plugin add http://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git#:/tests
-
- cordova plugin add http://git-wip-us.apache.org/repos/asf/cordova-plugin-device-motion.git
- cordova plugin add http://git-wip-us.apache.org/repos/asf/cordova-plugin-device-motion.git#:/tests
-
- cordova plugin add http://git-wip-us.apache.org/repos/asf/cordova-plugin-geolocation.git
- cordova plugin add http://git-wip-us.apache.org/repos/asf/cordova-plugin-geolocation#:/tests
+ ```shell
+ cordova plugin add cordova-plugin-device
+ cordova plugin add plugins/cordova-plugin-device/tests
+
+ cordova plugin add cordova-plugin-device-motion
+ cordova plugin add plugins/cordova-plugin-device-motion/tests
+
+ cordova plugin add cordova-plugin-geolocation
+ cordova plugin add plugins/cordova-plugin-geolocation/tests
+ ```
+
+ To install the plugin from `master` on GitHub instead of npm, replace e.g. `cordova-plugin-device` with `https://github.com/apache/cordova-plugin-device.git`
3. Follow the docs for [Setting up the test harness](#harness).
@@ -53,7 +57,7 @@ Tests run directly inside existing cordova projects, so you can rapidly switch b
### Where do tests live?
-Add a directory named `tests` to the root of your plugin. Within this directory, create a nested `plugin.xml` for the tests plugin. It should have a plugin id with the form `plugin-id-tests` (e.g. the `cordova-plugin-device` plugin has the nested id `cordova-plugin-device-tests`) and should contain a `<js-module>` named `tests`. E.g:
+Add a directory named `tests` to the root of your plugin. Within this directory, create a nested `plugin.xml` for the tests plugin. It should have a plugin id with the form `pluginid-tests` (e.g. the `cordova-plugin-device` plugin has the nested id `cordova-plugin-device-tests`) and should contain a `<js-module>` named `tests`. E.g:
```
<js-module src="tests/tests.js" name="tests">
@@ -64,13 +68,13 @@ For example, the `cordova-plugin-device` plugin has this nested [`plugin.xml`](h
Create a `package.json` inside your project's `tests/` folder. Plugins require a `package.json` now and tests are considered their own plugins. The latest version of the tools ensure to run `npm install` on any plugin added to a project and pull in any dependencies. Therefore, plugin authors can now put npm dependencies around their tests into the `package.json` file.
-For example,the `cordova-plugin-device` plugin contains a [`package.json`](https://github.com/apache/cordova-plugin-device/blob/master/tests/package.json).
+For example, the `cordova-plugin-device` plugin contains a [`package.json`](https://github.com/apache/cordova-plugin-device/blob/master/tests/package.json).
The `cordova-plugin-test-framework` plugin will automatically find all `tests` modules across all plugins for which the nested tests plugin is installed.
### Defining Auto Tests
-Simply export a function named `defineAutoTests`, which (gasp!) defines your auto-tests when run. Use the [`jasmine-2.0`](http://jasmine.github.io/2.0/introduction.html) format. E.g.:
+Export a function named `defineAutoTests`, which defines your auto-tests when run. Use the [`jasmine-2.0`](http://jasmine.github.io/2.0/introduction.html) format. E.g.:
```
exports.defineAutoTests = function() {
@@ -102,7 +106,7 @@ Note: Your tests will automatically be labeled with your plugin id, so do not pr
### Defining Manual Tests
-Simply export a function named `defineManualTests`, which (gasp!) defines your manual-tests when run. Manual tests do *not* use jasmine-2.0, and success/failure results are not officially reported in any standard way. Instead, create buttons to run arbitrary javascript when clicked, and display output to user using `console` or by manipulating a provided DOM element. E.g.:
+Export a function named `defineManualTests`, which defines your manual-tests when run. Manual tests do *not* any test runner, and success/failure results are not officially reported in any standard way. Instead, create buttons to run arbitrary javascript when clicked, and display output to user using `console` or by manipulating a provided DOM element. E.g.:
```
exports.defineManualTests = function(contentEl, createActionButton) {
@@ -118,6 +122,8 @@ exports.defineManualTests = function(contentEl, createActionButton) {
};
```
+Make sure to document the expected outcome.
+
Note: Your tests will automatically be labeled with your plugin id, so do not prefix your test descriptions.
@@ -131,22 +137,26 @@ See: [`cordova-plugin-device` tests](https://github.com/apache/cordova-plugin-de
## Running Plugin Tests
-1. Use your existing cordova app, or create a new one.
+1. Use your existing Cordova app, or create a new one.
2. Add this plugin:
- cordova plugin add http://git-wip-us.apache.org/repos/asf/cordova-plugin-test-framework.git
+ ```
+ cordova plugin add cordova-plugin-test-framework
+ // or
+ cordova plugin add https://github.com/apache/cordova-plugin-test-framework.git
+ ```
-3. Change the start page in `config.xml` with `<content src="cdvtests/index.html" />` or navigate to `cdvtests/index.html` from within your app.
+3. Change the start page in `config.xml` with `<content src="cdvtests/index.html" />` or add a link to `cdvtests/index.html` from within your app.
4. Thats it!
## FAQ
* Q: Should I add `cordova-plugin-test-framework` as a `<dependency>` of my plugin?
- * A: No. The end-user should decide if they want to install the test framework, not your plugin (most users won't).
+ * A: No. The end-user should decide if they want to install the test framework, not your plugin (most users won't).
* Q: What do I do if my plugin tests must have very large assets?
- * A: Don't bundle those assets with your plugin. If you can, have your tests fail gracefully if those assets don't don't exist (perhaps log a warning, perhaps fail a single asset-checking test, and skip the rest). Then, ideally download those assets automatically into local storage the first time tests run. Or create a manual test step to download and install assets. As a final alternative, split those test assets into a separate plugin, and instruct users to install that plugin to [...]
+ * A: Don't bundle those assets with your plugin. If you can, have your tests fail gracefully if those assets don't don't exist (perhaps log a warning, perhaps fail a single asset-checking test, and skip the rest). Then, ideally download those assets automatically into local storage the first time tests run. Or create a manual test step to download and install assets. As a final alternative, split those test assets into a separate plugin, and instruct users to install that plugin to run [...]
* Q: Should I ship my app with the test framework plugin installed?
- * A: Not likely. If you want, you can. Then your app could even embed a link to the test page (`cdvtests/index.html`) from a help section of your app, to give end users a way to run your test suite out in the feild. That may help diagnose causes of issues within your app. Maybe.
+ * A: Not likely. If you want, you can. Then your app could even embed a link to the test page (`cdvtests/index.html`) from a help section of your app, to give end users a way to run your test suite out in the feild. That may help diagnose causes of issues within your app. Maybe.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org