[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.
NOTE: Protractor will open a new browser window in the foreground when it is started.
## 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):
The `protractor.sh` script is a one-liner to run Protractor tests. It handles database creation/saving/restoring and manages the required local server processes. However, it assumes several things:
- It is being ran in the top directory of the `beat.web` repository
- The repository has already ran `./bin/buildout` successfully and with default development configuration
- Protractor's `.conf` file is `./protractor-conf.js`
- Default (no) additional arguments passed to `webdriver-manager` or Django `runserver`
- Django uses `./django.sql3` as the database
- If `./django.sql3` does not exist, the default database generated by `./bin/django install` is sufficient for testing
## Manual test running
If the `protractor.sh` script won't work, one can test manually.
The `webdriver-manager` must be running while testing. To run tests using a local BEAT web server, you must have the BEAT web server up as well.
### Starting the webdriver server
- Start the webdriver server in a separate shell (or append ` &` to run it as a background process in the current shell):
- 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:
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`:
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:
@@ -184,6 +184,127 @@ Or, to generate an HTML report::
``test.sql3`` on your current directory. You may delete it when you're done.
End-to-End Testing
------------------
`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.
.. warning::
Protractor will open a new browser window in the foreground when it is started.
Setup
=====
Currently, testing the BEAT web platform with Protractor requires additional setup after successfully setting up the project locally:
- Install Protractor
.. code:: bash
./parts/buildout-node/node-*/bin/npm i -g protractor
- Download/update the webdriver-manager's dependencies (Selenium & more)
The ``protractor.sh`` script is a one-liner to run Protractor tests. It handles database creation/saving/restoring and manages the required local server processes. However, it assumes several things:
- It is being ran in the top directory of the ``beat.web`` repository
- The repository has already ran ``./bin/buildout`` successfully and with default development configuration
- Protractor's ``.conf`` file is ``./protractor-conf.js``
- Default (no) additional arguments passed to ``webdriver-manager`` or Django ``runserver``
- Django uses ``./django.sql3`` as the database
- If ``./django.sql3`` does not exist, the default database generated by ``./bin/django install`` is sufficient for testing
Manual test running
===================
If the ``protractor.sh`` script won't work, one can test manually.
The ``webdriver-manager`` must be running while testing. To run tests using a local BEAT web server, you must have the BEAT web server up as well.
Starting the webdriver server
_____________________________
- Start the webdriver server in a separate shell (or append `` &`` to run it as a background process in the current shell)
- If you started your webdriver server as a background process, you can kill all webdriver processes
.. code:: bash
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:
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``:
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:
