Using Selenium with Koha

From Koha Wiki

Jump to: navigation, search
Home > Documentation
Home > Documentation
Koha > Technical > Development
Tips & Tricks > Tips & Tricks/Customising Notices and Slips > Tips & Tricks

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 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):


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 -O /tmp/selenium.jar

2. Install Mozilla Firefox and Xvfb

sudo apt install xvfb firefox-esr


4. Run Xvfb

Xvfb :1 -screen 0 1024x768x24 2>&1 >/dev/null &

5. Run the Selenium server

DISPLAY=:1 java -jar /tmp/selenium.jar



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:



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.



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


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 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

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.

Developer handbook

Personal tools