Skip to content

Latest commit

 

History

History
237 lines (132 loc) · 8.44 KB

TESTING.md

File metadata and controls

237 lines (132 loc) · 8.44 KB
Raw

Running PouchDB Tests

The PouchDB test suite expects an instance of CouchDB running in Admin Party on http://127.0.0.1:5984, you can configure this by sending the COUCH_HOST env var.

  • PouchDB has been primarily developed on Linux and OSX, if you are using Windows then these instructions will have problems, we would love your help fixing them though.

Node Tests

Given that you have installed a CouchDB server.

Run all tests with:

$ npm test

Browser Tests

Browser tests can be run automatically with:

$ CLIENT=selenium:firefox npm test

or you can run:

$ npm run dev

and open http://127.0.0.1:8000/tests/test.html in your browser of choice. The performance tests are located @ http://localhost:8000/tests/performance/test.html.

Test Options

Subset of tests:

$ GREP=test.replication.js npm test

or append ?grep=test.replication.js if you opened the tests in a browser manually.

Test Coverage

$ COVERAGE=1 npm test

Test alternative server

$ COUCH_HOST=http://user:[email protected] npm run dev

or

$ COUCH_HOST=http://user:[email protected] npm test

Test with ES5 shims

Some older browsers require es5 shims. Enable them with:

$ ES5_SHIM=true npm run dev

or e.g.:

$ ES5_SHIM=true CLIENT=selenium:phantomjs npm test

or you can append it as ?es5shim=true if you manually opened a browser window.

Cordova tests

You may need to install ant in order for the Android tests to run (e.g. brew install ant). You'll also need the Android SDK, and to make sure your $ANDROID_HOME is set.

Run the tests against an iOS simulator:

$ CLIENT=ios npm run cordova

Run the tests against a connected Android device, using the given COUCH_HOST

$ CLIENT=android DEVICE=true COUCH_HOST=http://example.com:5984

Run the tests against the FirefoxOS simulator:

$ CLIENT=firefoxos npm run cordova

Run the tests against a BlackBerry 10 device:

$ CLIENT=blackberry10 DEVICE=true npm run cordova

Use a custom Couch host:

$ COUCH_HOST=http://myurl:5984 npm run cordova

Grep some tests:

$ GREP=basics npm run cordova

Test against the SQLite Plugin:

$ SQLITE_PLUGIN=true ADAPTERS=websql npm run cordova

Notes:

  • CLIENT=ios will run on iOS, default is CLIENT=android
  • DEVICE=true will run on a device connected via USB, else on an emulator (default is the emulator)
  • SQLITE_PLUGIN=true will install and use the SQLite Plugin.
  • ADAPTERS=websql should be used if you want to skip using IndexedDB on Android 4.4+ or if you want to force the SQLite Plugin.
  • COUCH_HOST should be the full URL; you can only omit this is in the Android emulator due to the magic 10.0.2.2 route to localhost.
  • ES5_SHIM=true should be used on devices that don't support ES5 (e.g. Android 2.x).

WEINRE debugging:

You can also debug with Weinre by doing:

$ npm install -g weinre
$ weinre --boundHost=0.0.0.0

Then run the tests with:

$ WEINRE_HOST=http://route.to.my.weinre:8080 npm run cordova

Testing against PouchDB server

pouchdb-server is a project that uses express-pouchdb to run a CouchDB-compliant server backed by PouchDB.

To test the latest and greatest version of pouchdb-server, you can do e.g.:

SERVER=pouchdb-server npm test
SERVER=pouchdb-server CLIENT=selenium:firefox npm test

If you would like to modify pouchdb-server while testing, then git clone the express-pouchdb and pouchdb-server projects, npm link them all together, and then run:

    node /path/to/pouchdb-server/bin/pouchdb-server -p 6984

Then in the PouchDB project, run:

COUCH_HOST=http://localhost:6984 npm run dev

This works because npm run dev does not start up the pouchdb-server itself (only npm test does).

Testing the in-memory adapter

pouchdb-server uses the --in-memory flag to use MemDOWN. To enable this, set

SERVER_ADAPTER=memory

Whereas on the client this is configured using PouchDB.defaults(), so you can enable it like so:

LEVEL_ADAPTER=memdown

The value is a comma-separated list of key values, where the key-values are separated by colons.

Some Level adapters also require a standard database name prefix (e.g. riak:// or mysql://), which you can specify like so:

LEVEL_PREFIX=riak://localhost:8087/

Testing Pouch in a shell

For quick debugging, you can run an interactive Node shell with the PouchDB variable already available:

npm run shell

Performance tests

PERF=1 npm test

To run the performance test suite in node.js or the automated browser runner.

Performance tests in the browser

You can specify a particular version of PouchDB or a particular adapter by doing e.g.:

http://localhost:8000/tests/performance/test.html?src=http://site.com/path/to/pouchdb.js
http://localhost:8000/tests/performance/test.html?adapter=websql
http://localhost:8000/tests/performance/test.html?adapter=idb&src=//site.com/pouchdb.js

All of the browser plugin adapters (i.e. idb-alt, memory, and localstorage) are also available this way.

You can also specify particular tests by using grep=, e.g.:

http://127.0.0.1:8000/tests/performance/test.html?grep=basics
http://127.0.0.1:8000/tests/performance/test.html?grep=basic-inserts

Ad-hoc tests

There's a WebSQL storage quota test available in:

http://127.0.0.1:8000/tests/stress/websql_storage_limit.html

Run npm run dev, then open it in Safari or iOS.

Adapter plugins and adapter order

We are currently building three adapters-as-plugins: memory, localstorage, and idb-alt. All are based on the LevelDOWN API:

These adapters are built and included in the dist/ folder as e.g. pouchdb.memory.js. Including these scripts after pouchdb.js will load the adapters, placing them in the PouchDB.preferredAdapters list after idb and websql by default.

<script src="pouchdb.js"></script>
<script>console.log(PouchDB.preferredAdapters); // ['idb', 'websql']</script>
<script src="pouchdb.memory.js"></script>
<script>console.log(PouchDB.preferredAdapters); // ['idb', 'websql', 'memory']</script>

To test these adapters, you can run e.g.

ADAPTERS=memory CLIENT=selenium:firefox npm run test

Or append them as query params in the browser:

http://localhost:8000/tests/test.html?adapters=memory

The adapters list is a comma-separated list that will be used for PouchDB.preferredAdapters. So e.g. if you want to test websql in Chrome, you can do:

http://localhost:8000/tests/test.html?adapters=websql

Or even make the preferredAdapters list any crazy thing you want:

# loads websql, then memory, then idb, then localstorage
http://localhost:8000/tests/test.html?adapters=websql,memory,idb,localstorage

Keep in mind that preferredAdapters only applies to non-http, non-https adapters.

Installing a CouchDB server

Regular install

See the official CouchDB documentation for a guide on how to install CouchDB.

Docker install

Don't have a CouchDB installed on your machine? Don't want one? Let's use docker and fig.

  1. Install Docker
  2. Install Fig
  3. Run fig -f tests/misc/fig.yml up -d from PouchDB project root folder to download and run a CouchDB server in docker
  4. Check with fig -f tests/misc/fig.yml ps that couchdb is running and listen on 0.0.0.0:15984
  5. Run the test suite with: COUCH_HOST=http://127.0.0.1:15984 npm test

Now everytime you want to run the test suite, you just need to: $ fig -f tests/misc/fig.yml start