Updated readme and added install script

package.json

@@ -17,7 +17,7 @@
     "sqldumptest": "NODE_ENV=test DUMP_NAME_SUFFIX=-test npm run sqldump",
     "sqlresettest": "NODE_ENV=test npm run sqldrop && NODE_ENV=test npm run sqlinit",
     "starttest": "NODE_ENV=test node index.js",
-    "_e2e": "PATH=$PATH:./node_modules/phantomjs/lib/phantom/bin:./test/e2e/bin NODE_ENV=test ./node_modules/.bin/mocha test/e2e/index.js",
+    "_e2e": "NODE_ENV=test mocha test/e2e/index.js",
     "e2e": "npm run sqlresettest && npm run _e2e"
   },
   "repository": {

test/e2e/README.md

@@ -1,6 +1,44 @@
-Running e2e tests requires Node 7.6 or later and a dedicated test database.
+# e2e Tests
+
+Running e2e tests requires Node 7.6 or later and a dedicated test database. It uses mocha, selenium-webdriver and phantomjs.
+
+## Installation
+
+These e2e tests have to be performed against predefined resources (e.g. lists, users, etc.) and therefore a dedicated test database and test config is required.
+
+Both can be created by running `sudo sh test/e2e/install.sh` from within your mailtrain directory. This creates a MYSQL user and database called `mailtrain_test`, and generates the required `config/test.toml`.
+
+## Running e2e Tests
+
+For tests to succeed Mailtrian must be started in `test` mode on port 3000 (as http://localhost:3000/ is the predefined service url). The tests itself have to be started in a second Terminal window.
 
 1. Start Mailtrain with `npm run startest`
 2. Start e2e tests with `npm run e2e`
 
-By default the tests run with `phantomjs`. To use different browsers see `test/e2e/bin/README.md`.
+## Using Different Browsers
+
+By default e2e tests use `phantomjs`. If you want to use a different browser you need to install its driver and adjust your `config/test.toml`.
+
+* Install the `firefox` driver with `npm install geckodriver`
+* Install the `chrome` driver with `npm install chromedriver`
+* Other drivers can be found [here](https://seleniumhq.github.io/selenium/docs/api/javascript/)
+
+Then adjust your config:
+
+```
+[seleniumwebdriver]
+browser="firefox"
+```
+
+Current Firefox issue (and patch): https://github.com/mozilla/geckodriver/issues/683
+
+## Writing e2e Tests
+
+You should spend your time on features rather than writing tests, yet in some cases, like for example the subscription process, manual testing is just silly. You best get started by reading the current test suites, or just open an issue describing the scenario you want to get tested.
+
+Available commands:
+
+* `npm run sqldumptest` - exports the test DB to `setup/sql/mailtrain-test.sql`
+* `npm run sqlresettest` - drops all tables then loads `setup/sql/mailtrain-test.sql`
+* `npm run _e2e` - just runs e2e tests
+* `npm run e2e` - runs `sqlresettest` then `_e2e`

test/e2e/bin/.gitignore

@@ -1,3 +0,0 @@
-*
-!.gitignore
-!README.md

test/e2e/bin/README.md

@@ -1,8 +0,0 @@
-This directory serves for custom browser drivers.
-
-1. https://seleniumhq.github.io/selenium/docs/api/javascript/
-2. Download a driver of your choice and put it into this directory
-3. chmod +x driver
-4. Edit config/test.toml
-
-Current Firefox issue (and patch): https://github.com/mozilla/geckodriver/issues/683

test/e2e/install.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+# This installation script works on Ubuntu 14.04 and 16.04
+# Run as root!
+
+if [[ $EUID -ne 0 ]]; then
+   echo "This script must be run as root" 1>&2
+   exit 1
+fi
+
+set -e
+
+export DEBIAN_FRONTEND=noninteractive
+
+MYSQL_PASSWORD=`pwgen 12 -1`
+
+# Setup MySQL user for Mailtrain Tests
+mysql -u root -e "CREATE USER 'mailtrain_test'@'localhost' IDENTIFIED BY '$MYSQL_PASSWORD';"
+mysql -u root -e "GRANT ALL PRIVILEGES ON mailtrain_test.* TO 'mailtrain_test'@'localhost';"
+mysql -u mailtrain_test --password="$MYSQL_PASSWORD" -e "CREATE database mailtrain_test;"
+
+# Setup installation configuration
+cat >> config/test.toml <<EOT
+[www]
+port=3000
+[mysql]
+user="mailtrain_test"
+password="$MYSQL_PASSWORD"
+database="mailtrain_test"
+[testserver]
+enabled=true
+[seleniumwebdriver]
+browser="phantomjs"
+EOT
+
+echo "Success! The test database has been created.";

test/e2e/page-objects/page.js

@@ -7,15 +7,14 @@ const until = webdriver.until;
 
 module.exports = driver => ({
     driver,
-    url: '/',
     elements: {},
 
     element(key) {
         return this.driver.findElement(By.css(this.elements[key] || key));
     },
 
-    navigate() {
+    navigate(path) {
-        this.driver.navigate().to(config.baseUrl + this.url);
+        this.driver.navigate().to(config.baseUrl + (path || this.url));
         return this.waitUntilVisible();
     },