.. Copyright (C) ALbert Mietus, SoftwareBeterMaken.nl; 2016. Part of Pathways project -*- coding: utf-8 -*-

.. highlight:: shell-session


Installing the examples
=======================

When the examples (for the tutorials) are *not* needed you can skip  this article.

WebApp examples
===============

For the 'webapp' examples a browser is needed, which is automated with 'selenium' (which is part of the
:term:`gate`). Several browser are supported, like `Firefox` and `Chrome`. For each browser-brand (& version), a
specific browser-driver should be installed; aside of the generic selenium-software and the python (language) bindings.

The generic *webgate* is part of the framework, but should be configured to the selected browser and
selenium-driver. And to compete, the examples themselves have to be installed [#a]_.

.. [#a] That is: download and unpacked. When the "source" distribution is downloaded, the tests are already available
	(in :file:`pathways-r-d/examples/calculators/webapp/tst/`).

.. warning:: Generic selenium software?

   The documentation of selenium and related topics (bindings, drivers) is very-outdated.

      Note to the Reader - Docs Being Revised for Selenium 2.0!

      --- http://www.seleniumhq.org/docs/00_Note_to-the-reader.jsp, Oct 2, 2016

   Whereas the current version of selenium is 3.0.0-beta4. And the current firefox-browser (v49) is not compatible with
   older selenium versions.

   At the moment it unclear if (or when) the “generic selenium software” is needed. Most probably, it is not
   (anymore). Or it comes automatically with the selenium-python language-bindings.

   Whenever you installed as described below and it does not work, please install as described on
   http://www.seleniumhq.org/download/ And let me know, including details as symtoms and versions. --Thanks

Selenium
--------

.. tip:: Verify script

   Pathways comes with a small script (:file:`.../bin/VerifySelenium_Firefox.py` ) to verify Selenium is correctly
   installed, including browser, drivers, and language-bindings; currently only for Firefox (this will change soon).

   Run it like::

     [albert@Python3:]%  python3 {options} VerifySelenium_Firefox.py PATH/TO/DRIVER

     It will step-for-step verify all details and give tips when it fails. When all works, the browser is started and
     one page is visited. You can visually verify this. At the end, that browser (session) is closed.

   To show it options: run::

     [albert@Python3:]%  python4 VerifySelenium_Firefox.py --help


* Install the selenium-python bindings::

     [albert@Python3:]%  pip3 install --upgrade selenium

Browser & driver
----------------

Firefox
^^^^^^^

* Install `Firefox <https://mozilla.org/firefox>`_
* The *Gecko* driver: https://github.com/mozilla/geckodriver/releases

..  note: Firefox drivers

   * Be carefully with selecting a driver/browser/version!
   * Since Firefox-48, the old (build-in selenium) driver does not work anymore!
   * The "gecko-driver" should be used, but isn't stable/ready
   * The v0.9.0 is tested and does works.
   * The v0.10.0 driver does not work; it is only for selenium-3-beta

Chrome
^^^^^^

* Install `Chrome <https://www.google.com/chrome/>`_
* Install the ChromeDriver: https://sites.google.com/a/chromium.org/chromedriver/downloads


Other (browsers & version)
^^^^^^^^^^^^^^^^^^^^^^^^^^

The procedure for other browsers is described in the `selenium documentation <http://docs.seleniumhq.org/>`_. As
browsers and selenium tend to change frequently, is sensible to have a look on that site, as well on `stackoverflow
<http://stackoverflow.com/questions/tagged/selenium>`_.





configure & WebApp test
-----------------------

.. todo:: make browsers & driver selectable

   .. warning:: Currently, the config files (and even some code!) contain hardcoded paths. That is a known error....

      * But as I am the main user, it will do for now. :-)
      * A rewrite/update of the :py:mod:`core/conf` is needed.


* download and unpack the examples

  .. todo:: Make the examples (zip-file) downloadable, and document it.