barebones protractor setup & docs

README_PROTRACTOR.md

+# End-to-End Testing with Protractor
+[Protractor](http://www.protractortest.org/#/) is an e2e (end-to-end) testing tool for web apps. Protractor runs tests through Selenium using a real browser, and as such needs a headed environment and a compatible browser installed.
+
+## Setup
+Currently, testing the BEAT web platform with Protractor requires additional setup after successfully setting up the project locally:
+
+- Install Protractor:
+```sh
+./parts/buildout-node/node-*/bin/npm i -g protractor
+```
+
+- Download/update the webdriver-manager's dependencies (Selenium & more):
+```sh
+./parts/buildout-node/node-*/bin/webdriver-manager update
+```
+
+- Start the webdriver server in a separate shell (or append ` &` to run it as a background process in the current shell):
+```sh
+./parts/buildout-node/node-*/bin/webdriver-manager start
+```
+NOTE: You may only have 1 webdriver manager running at once.
+
+- After the webdriver finishes initialization, you can run tests (*WARNING*: Protractor will open a new browser window in the foreground):
+```sh
+./parts/buildout-node/node-*/bin/protractor protractor-conf.js
+```
+NOTE: To run tests using a local BEAT web server, you must have the web server running while Protractor executes tests.
+
+- If you started your webdriver server as a background process, you can kill all webdriver processes:
+```sh
+pkill -f webdriver-manager
+```
+
+## Understanding the output of Protractor
+By default Protractor prints to `STDOUT`. If a test passes, nothing is printed about that particular test. If a test fails, Protractor will print more information about the failure, including the specific test, type of failure that occurred, and a stack trace. At the end of testing, Protractor will print a summary of the test run.
+
+### Saving test results
+Beyond simply piping Protractor's output to a file, you may enable detailed logging via a specified JSON file. Just uncomment the relevant line in `protractor-conf.js` and optionally change the output file location:
+```js
+	//resultJsonOutputFile: './protractor-test-results.json'
+```
+
+## Adding your test to Protractor
+The configuration file detailing the test files is `protractor-conf.js`. The `specs` field is a comma-separated list of test files - just add your new test file to the list and run protractor again.
+
+For example, to add the test file `example-spec.js`:
+- Before
+```js
+	specs: [
+		'./beat/web/reports/static/reports/test/test-spec.js'
+	],
+```
+- After
+```js
+	specs: [
+		'./beat/web/reports/static/reports/test/test-spec.js',
+		'example-spec.js'
+	],
+```
+
+
+## Writing Protractor tests
+Protractor uses and expects tests to use the [Jasmine BDD testing framework](https://jasmine.github.io/). For a tutorial on writing Protractor tests, see the [official Protractor tutorial](http://www.protractortest.org/#/tutorial). Protractor also has documentation on their website.
+
+### BEAT platform & Protractor's Angular support
+By default, Protractor assumes that the tested website will use Angular in a particular fashion to more intelligently detect a page that has finished rendering. However, the BEAT platform does not use Angular this way, and Protractor will hang forever. To tell Protractor not to assume this compatibility, add the following line at the top of each top-level `describe` block in your test files:
+```js
+browser.ignoreSynchronization = true;
+```

beat/web/reports/static/reports/test/test-spec.js

+// 'describe' blocks can hold other 'describe' blocks and test blocks
+describe('BEAT platform', function() {
+	/*
+	 * the BEAT platform does not use Angular in a way that
+	 * Protractor can automatically reason about,
+	 * so disable special Angular features
+	 */
+	browser.ignoreSynchronization = true;
+	// 'it' blocks are individual tests
+	it('should have the page title of "BEAT"', function() {
+		// 'browser' is a global object representing the browser
+		// assumes the BEAT web server is running locally on port 8000
+		browser.get('http://localhost:8000');
+
+		// simple test to sanity check Protractor
+		expect(browser.getTitle()).toEqual('BEAT');
+	});
+});

protractor-conf.js

+exports.config = {
+	seleniumAddress: 'http://localhost:4444/wd/hub',
+
+	specs: [
+		'./beat/web/reports/static/reports/test/test-spec.js'
+	],
+	allScriptsTimeout: 60000,
+
+	//resultJsonOutputFile: './protractor-test-results.json'
+}