Using Selenium with Koha

Selenium is an open source automated testing tool which replicates the interaction of users with the Koha intranet and OPAC by following automated tests which in the case of the Koha selenium tests are written in Perl and are avaliable in the t/db_dependent/selenium/ directory.
= Installing Selenium =
== KohaDevBox ==
KohaDevBox can be configured to configure Selenium with very few steps.
1. Edit your vars/user.yml
-#selenium: false
+selenium: true
2. Provision
If you are creating a new box, just start it (with whatever parameters you usually use):
 $ SKIP_WEBINSTALLER=1 CREATE_ADMIN_USER=1 vagrant up
If you already have a running box, you need to re-provision (from outside the box, on the kohadevbox clone): 
 $ vagrant provision
3. Start Selenium
KohaDevBox ships with a handy alias for starting Selenium. Just run this on a separate console (byobu? tmux?):
 $ start_selenium
== Manual install ==
To install Selenium do the following: 
1. Download the Selenium distribution 
wget https://selenium-release.storage.googleapis.com/2.53/selenium-server-standalone-2.53.1.jar -O /tmp/selenium.jar 
 
2. Install Mozilla Firefox and Xvfb 
sudo apt install xvfb firefox-esr
 
 
3. SELENIUM_PATH=/home/vagrant/kohaclone/selenium-server-standalone-2.53.1.jar
4. Run Xvfb 
Xvfb :1 -screen 0 1024x768x24 2>&1 >/dev/null &
 
 
5. Run the Selenium server 
DISPLAY=:1 java -jar /tmp/selenium.jar
 
Or
 DISPLAY=:1 java -jar $SELENIUM_PATH
Note: This will start up the standalone Selenium server. You need to keep this terminal window open to ensure that the Selenium server is kept running whilst you run Selenium tests. 
If you shut the window and want to restart the standalone server then just write in the commands on steps 7, 8, and 9. 
 
6. Open a new terminal window and write in: 
sudo cpanm -i Selenium::Remote::Driver
 
 
= Running Selenium tests =
To run a Selenium test you need to enter koha-shell: 
sudo koha-shell <instancename>
 
 
Then write in: 
perl <testfile>.t
 
 
 
= Writing Selenium tests =
Selenium works by finding elements on the page and interacting with them as users do. Selenium tests in Koha are written in Perl and use functions provided by the Selenium::Remote::Driver perl client. These functions replicate how users interact with the webpage for example one function is send_keys() this inputs characters into a input box or textarea. 
 
Here are two common ways to find an element on a page using Selenium: 
1. 
 $driver->find_element('//<tag>[@<attribute>="<attributevalue>"]'); 
This is using the find_element() function to find a tag on the page currently based on an attribute such as id, class, value, hrefand its value. 
2. 
$driver->find_element_by_xpath('<xpathtoelement>'); 
The xpath is the full path to an element on the page starting with the html tag 
e.g. /html/body/div[4]/div/div[1]/di v/div[2]/form[3]/table/tbody/tr[2]/td[3]/input 
I find a combination of both is useful, but I tend to use xpath by default and if Selenium cannot find the element using the xpath then I use the find_element() instead. 
A good way to find the xpath is to download and install the Firebug Mozilla Firefox extension. Then to get the xpath of a element you right click on the element, select 'Inspect Element with Firebug' and the markup which the page is built from is displayed and now all you have to do is right click on the highlighted markup and select 'Copy XPath' and you can paste it into your Selenium test. 
 
== Common Selenium problems when writing Selenium tests ==
=== Random fails ===
Selenium is known by some developers as a flaky tool due to the fact that it can randomly fail on some runs of a test but succeed on other runs of the test. I (Alex Buckley) have found the most common failure is that Selenium cannot find an element on the page. 
My solution for when Selenium fails due to not being able to find an element is to implement a pause 
$driver->pause(20000); 
This gives the page more time to load before Selenium looks for an element. 
I also implement: 
warn $driver->get_title(); 
This displays the title of the currently loaded page in the test results. It is also very helpful for showing if the correct page is currently loaded. 
=== Unable to connect to host 127.0.0.1 on port 7055 after 45000 ms ===
I (jajm) had this error message with firefox-esr 60.3.0esr-1~deb9u1.
I fixed it by downgrading to 52.9.0esr-1~deb9u1
Joubu: direct link is
https://snapshot.debian.org/archive/debian/20180701T205743Z/pool/main/f/firefox-esr/firefox-esr_52.9.0esr-1%7Edeb9u1_amd64.deb
You also will need to install libgtk2.0-0 and libhunspell-1.4-0 before.
Also work for stretch, no workaround for jessie so far.
=== Tests are failing in test environments but you are struggling to replicate locally ===
It may be a JS error.. in such a case it's often useful to try and print out the js console logs but that's not trivial using Selenium alone. You can however add the following JS block to the relevant koha page temporarily to throw errors to screen and then use the capture selenium routine to grab a screenshot
```
 (function () {
 var ul = null;
 function createErrorList() {
 ul = document.createElement('ul');
 ul.setAttribute('id', 'js_error_list');
 //ul.style.display = 'none';
 document.body.appendChild(ul);
 }
 window.onerror = function(msg){
 if (ul === null)
 createErrorList();
 var li = document.createElement("li");
 li.appendChild(document.createTextNode(msg));
 ul.appendChild(li);
 };
 })();
```
Category:Development
Category:Tips_&_Tricks
Category:Resources