feat(stark-demo): add browserstack test script

  - configured browserstack / protractor testing
  - updated travis to run tests with ci
  - added badge to README.md
  - added documentation

ISSUES CLOSED: #274

.travis.yml

@@ -16,6 +16,8 @@ before_install:
   - echo $AUTHOR_NAME
   - export TZ=Europe/Brussels
   - npm i -g npm@6.4.1
+  - NODE_VERSION="$(node -v)"
+  - echo $NODE_VERSION
   # This ensures that we are authenticated without requiring to have an actual .npmrc file within the project
   - 'echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" >> ~/.npmrc'
 
@@ -27,6 +29,7 @@ install:
   - if [[ ${TRAVIS_BRANCH} =~ ^greenkeeper.*$ || ${AUTHOR_NAME} == "greenkeeper[bot]" ]]; then npm run clean:modules:all; fi
   - if [[ ${TRAVIS_BRANCH} =~ ^greenkeeper.*$ || ${AUTHOR_NAME} == "greenkeeper[bot]" ]]; then npm i; else npm ci; fi
   - if [[ ${TRAVIS_BRANCH} =~ ^greenkeeper.*$ || ${AUTHOR_NAME} == "greenkeeper[bot]" ]]; then npm run install:travis:all; else npm run install:ci:all; fi
+  - if [[ ${TRAVIS_TAG} == "" && ${TRAVIS_EVENT_TYPE} != "cron" ]]; then npm run build:showcase:ghpages:ci-test-env; else npm run build:showcase:ghpages; fi
 
 env:
   global:
@@ -45,14 +48,15 @@ cache:
 
 # Not needed since we use Puppeteer in karma.conf.ci.js
 # It downloads Chrome itself and works with or without Travis
-#addons:
 #  chrome: stable
 
 script:
   - npm run lint:all
   - npm run test:ci:all
+  # E2E tests only need to be run on 1 node version (v10)
+  # and the secure environmentals BROWSERSTACK_USERNAME, BROWSERSTACK_ACCESS_KEY should be set. (only on secure builds)
+  - if [[ ${NODE_VERSION} =~ ^v10.*$ && -n "${BROWSERSTACK_USERNAME}" && -n "${BROWSERSTACK_ACCESS_KEY}"  ]]; then npm run test:showcase:e2e:browserstack; else echo "Skipping browserstack tests."; fi
   - npm run docs:coverage
-  - if [[ ${TRAVIS_TAG} == "" && ${TRAVIS_EVENT_TYPE} != "cron" ]]; then npm run build:showcase:ghpages:ci-test-env; else npm run build:showcase:ghpages; fi
   - npm run docs:publish
   - npm run release:publish
   - bash ./scripts/ci/print-logs.sh

README.md

@@ -12,6 +12,7 @@
 [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
 [![License](https://img.shields.io/cocoapods/l/AFNetworking.svg)](LICENSE) [![Greenkeeper badge](https://badges.greenkeeper.io/NationalBankBelgium/stark.svg)](https://greenkeeper.io/)
+[![BrowserStack Status](https://www.browserstack.com/automate/badge.svg?badge_key=dXkxd0JnL0V6TlRuVkszSGs5TDJscWFPOXdNL2hrMFdZREtMeEQ0SXU5RT0tLTBLZVJOb1JPR3pnUVhVY1NNMUtvdVE9PQ==--32b9d322c064334a80a3409239111be75d3d6ddd)](https://www.browserstack.com/automate/public-build/dXkxd0JnL0V6TlRuVkszSGs5TDJscWFPOXdNL2hrMFdZREtMeEQ0SXU5RT0tLTBLZVJOb1JPR3pnUVhVY1NNMUtvdVE9PQ==--32b9d322c064334a80a3409239111be75d3d6ddd)
 
 # Stark
 
@@ -55,6 +56,8 @@ Stark's reusable build integrates support for:
 
 ## Developer guide
 
+### [End-to-End Testing](docs/E2ETESTING.md)
+
 TODO add links to developer guide sections
 
 ### Releases

docs/E2ETESTING.md

@@ -0,0 +1,87 @@
+# End-to-End (E2E) Testing with Stark
+
+The Stark Starter comes with a setup to write and run end-to-end tests.
+
+## Protractor
+
+Protractor is an end-to-end test framework for Angular and AngularJS applications. Protractor runs tests against your application running in a real browser, interacting with it as a user would.
+
+For more information go to [https://www.protractortest.org](https://www.protractortest.org).
+
+### Running end-to-end tests
+
+Install all dependencies.
+
+```shell
+npm run install:all
+```
+
+Build the application
+
+```shell
+npm run build:starter
+```
+
+Run the end-to-end tests with protractor. _(make sure you have nothing running on `http://localhost:3000`)_
+
+```shell
+npm run test:starter:e2e
+```
+
+### Adding Tests
+
+If you add tests they should be added as `starter/e2e/src/[testSubset]/testName.e2e-spec.ts`.
+They are automatically found here by the configuration of `specs` in the `packages/stark-testing/protractor.conf.js`.
+
+Keeping e2e tests separate like this prevents confusion when testing multiple components.
+
+## BrowserStack (optional)
+
+The showcase app uses Travis CI and BrowserStack to automatically run e2e-tests on multiple setups (Chrome, Firefox, IE, Safari, Android, IOS, ...).
+
+If you want to run your e2e-tests automatically on multiple setups one of the easiest solutions is BrowserStack.
+They offer a free solution for open source projects.
+
+For more information go to [https://www.browserstack.com/automate](https://www.browserstack.com/automate).
+
+### Running end-to-end tests with BrowserStack
+
+#### Prerequisites
+
+-   BrowserStack Account ([https://www.browserstack.com/](https://www.browserstack.com/))
+
+#### Setup
+
+Find your credentials on the [BrowserStack dashboard](https://automate.browserstack.com/dashboard).
+
+Set the environmental `BROWSERSTACK_USERNAME` to the username and `BROWSERSTACK_ACCESS_KEY` to the access key.
+
+#### Run the tests
+
+```shell
+npm run test:e2e:showcase:browserstack
+```
+
+_If you want to integrate BrowserStack in your own project you can have a look at `showcase/e2e/protractor.browserstack.conf.js` where we configured our setup._
+
+_For more documentation see:_
+
+-   _[https://github.com/angular/protractor/blob/master/lib/config.ts](https://github.com/angular/protractor/blob/master/lib/config.ts)_
+-   _[https://www.browserstack.com/automate/capabilities](https://www.browserstack.com/automate/capabilities)_
+
+### Integrating BrowserStack with Travis CI
+
+To integrate the BrowserStack testing with Travis-CI simply add the same environmentals as before. **Remember to keep them private.**
+
+### Common errors
+
+#### Port busy
+
+```shell
+LocalError: Either another browserstack local client is running on your machine or some server is listening on port 45691
+```
+
+BrowserStack Local was probably not stopped properly on the last run. You can resolve this by manually terminating it.
+
+-   MacOS: `pkill BrowserStack`
+-   Windows: Find the task in Task Manager and end it.

package.json

@@ -69,6 +69,7 @@
     "build:showcase": "cd showcase && npm run build:prod && cd ..",
     "build:showcase:ghpages": "cd showcase && npm run build:prod:ghpages && cd ..",
     "build:showcase:ghpages:ci-test-env": "cd showcase && npm run build:prod:ghpages:ci-test-env && cd ..",
+    "build:starter": "cd starter && npm run build && cd ..",
     "clean": "npx rimraf ./dist",
     "clean:all": "npm run clean && npm run clean:stark-build && npm run clean:stark-core && npm run clean:stark-ui && npm run clean:stark-testing && npm run clean:starter && npm run clean:showcase",
     "clean:stark-build": "cd packages/stark-build && npm run clean && cd ../..",
@@ -138,8 +139,12 @@
     "test:stark-core": "cd packages/stark-core && npm run test-fast && cd ../..",
     "test:stark-ui": "cd packages/stark-ui && npm run test-fast && cd ../..",
     "test:showcase": "cd showcase && npm run test-fast && cd ../..",
+    "test:showcase:e2e": "cd showcase && npm run e2e && cd ../..",
+    "test:showcase:e2e:browserstack": "cd showcase && npm run e2e:browserstack && cd ../..",
     "test:starter": "cd starter && npm run test-fast && cd ../..",
-    "test:ci:all": "npm run test:ci:stark-core && npm run test:ci:stark-ui && npm run test:ci:starter && npm run test:ci:showcase",
+    "test:starter:e2e": "cd starter && npm run e2e && cd ../..",
+    "test:starter:e2e:browserstack": "cd starter && npm run e2e:browserstack && cd ../..",
+    "test:ci:all": "npm run test:ci:stark-core && npm run test:ci:stark-ui && npm run test:ci:starter && npm run test:ci:starter",
     "test:ci:stark-core": "cd packages/stark-core && npm run test-fast:ci && cd ../..",
     "test:ci:stark-ui": "cd packages/stark-ui && npm run test-fast:ci && cd ../..",
     "test:ci:showcase": "cd showcase && npm run test-fast:ci && cd ../..",