////
******************************************************************************
* Copyright 2018 Mettenmeier GmbH.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
*
*     http://www.eclipse.org/legal/epl-v10.html
*
******************************************************************************
////
= openKonsequenz "StandbyPlanning" - How to work with Selenium tests
:Date: 2018-11-22
:Revision: 1

== Installing the Selenium IDE

The *Selenium IDE* is a plugin available for most browsers, including Firefox and Chrome. It should be available via the respective menu ("Add-ons" for Firefox, "Extensions" for Chrome, etc.). If that is not the case it can be downloaded manually from the official site: https://www.seleniumhq.org/download/#selenium_ide

After installing the *Selenium IDE* can be opened from the browser. It will use the respective browser for both running and recording tests.

== Running tests

After opening the project you can use the list on the right to navigate to the test or suite you want to run (switch tests/suites via the dropdown menu at the top).

The *Selenium IDE* has a toolbar at the top of the command table which is used to run the test. Clicking the regular "play" icon will run the current test. Next to it is another play icon that will run all tests in a suite, as long as one is selected in that suite. Other options include pausing/stopping the execution, setting the speed of the playback or skipping a step.

The text area at the bottom of the window will log each command's results. Additionally the respective commands will be colored green/red, depending on success/failure.

== Creating tests and suites

To create tests or suites, click the `+` icon at the top of the test/suit list on the right. It will create the one which is chosen in the dropdown next to it.

A test needs to always begin with an `open` command. As `target` value you choose the URL you want the test to run in. If this `target` value is not a full URL it is automatically combined with the `base URL` defined above the table of test steps. That way you can define relative locations and re-use tests with different base URLs.

Commonly used commands include `click` and `type`. Both of them have a `target`, defining the HTML element they access and the `type` command additionally requires a `value`, which specifies what should be typed. Other commands work the same way, `target` naming the element and `value` the text, duration, true/false etc. These can be entered using the form below the command list. It also contains a picker next to the `target` input field, with which you can select an element in an active playback/record window.

The `assert` and `verify` commands can be used to check for specific elements and cases. The difference between them is that `assert` interrupts the test if it fails, `verify` continues while still logging the error.

To add tests to suites you rightclick the respective suite and choose `Add tests`. Added tests can be rearranged via drag-and-drop. 

== Recording tests

The easiest way to create tests is to record them. To start recording, choose a `base URL` from which to start, then press the `REC` button at the right end of the playback toolbar. A new window will open on the specified URL.

All interactions with this window will be recorded as commands. When you have gone through the steps you wish to record, switch back to the *Selenium IDE* window and press the button again to stop recording.

The recorded list of commands should work when played back, but it can contain unnecessary commands or imprecise `target` values. Things like setting window size, hovering over buttons or clicking into an input field and/or dropdown menu can be deleted to improve the readability and keep the test short.

The *Selenium IDE* will always attempt to find a way to precisely identify the selected element. However, sometimes the automatically selected `target` is not the best possibility. In that case you can highlight the respective command and select the `target` field in the form below. A dropdown will open which lets you choose between the possible definitions found while recording.

Just like with manual creation, you can add/edit/delete commands by hand as needed.