From Koha Wiki

Jump to: navigation, search
Koha > Technical > Development > Quality Assurance Testing



The sandbox system has been developed with the goal to lower the barrier for a librarian to test patches and improvements of Koha.

It's based on a simple mechanism that will let anyone ask for a Koha setup, an up-to-date Koha, set up with a specific patch and a sample database for testing.

Beware: each Koha set up is reset nightly. So if you are testing over a number of days, you will need a new sandbox set-up each day.

BibLibre provides some servers with Koha setup (sandboxes). The code of this sub-project has been released under GPL, with documentation, so that anyone is able to setup sandboxes (see :;a=tree;f=sandbox;h=83030c458a12c39c56fddbab3c60b329655bc612;hb=HEAD).

The Dashboard page shows important bug information:

- last 5 sign offs
- 'needs signoff' with the 5 oldest bugs waiting to get tested
- a list of current bug status numbers
- 'random bug' to give you some inspiratoin on what to fix next

Take a look and get inspired to do lots of signing off and bug work!

The mechanism

Tutorial video

Step 1 : select in Bugzilla a patch or improvement to test

Selecting the bug to work on can take some time. Some bugs have many Comments, so put some time aside for this part of the process. Also some bugs need testing by librarians (look at the various Components), some need testing by Koha developers.

Go to
Note: To see the full list of bugs and improvements in Bugzilla you do not need to login.
Note: To view the patches that need sign-off and to add your comments, you will need to register. When your credentials for login have been emailed to you, login @ and click Search.
To get the full list of the "Needs signoff" patches, highlight under the filter: Status "Needs signoff" and under the filter "Priority" select all (P1-high, P2, P3, P4, P5-low) then hit Search. You will see this information: Priority: P1 - high, P2, P3, P4, P5 - low Status: Needs Signoff on the new Bugzilla page.
The "Needs signoff" bug list can be filtered by ID#, Component, Priority etc. Make a note of the bug # you have selected as you will need it to define the sandbox parameters.

Step 2 : define the sandbox parameters

The 1st step is to define the parameters for the sandbox. Head to the sandbox creation list (see the "Available sandoxes" table below for the full URLs).

You'll see a welcome header (Welcome to the Koha sandbox tester) and, just below information about the existing setup for the sandbox. For example: The current setup on this sandbox is = Sandbox setup by unknown with database -1 and bug 7376 on Wed Feb 1 10:46:16 2012 If the setup is a few minutes old, it's probably wise to use another sandbox, to avoid a conflict with another tester. Otherwise, you can continue with this sandbox.

You will have to enter some information:

  • the bugzilla number: the bug you want to test or the word "master" to access a Koha set-up without a specific patch aplied. More about "Master" a little later under the Tips and Tricks heading: "Testing with Master".
  • your email address: this field is not mandatory, but you're highly encouraged to provide it, for 2 reasons: you'll be emailed once the sandbox is ready. Depending on your configuration, this can require a few minutes. Information about the creation of this sandbox will be available to anyone connecting. So, if you're working on a given sandbox, someone else will see it, and could catch you on IRC or drop you an email. This is the only mechanism that will avoid 2 users using the same sandbox at the same time!
  • the translation you would like to install. By default, you'll get fr-FR, you can choose another one, or remove anything, you'll have only english available
  • the database you want to setup. There are some options that are described below under the heading "Databases" which is important to read.
  • anti-spam: this is a fairly basic anti-spam entry. Just enter Koha in this field, and hit OK. This is to prevend form-bot-autosubmitter to break the server.

When you submit the form, a small file will be written on the server, requesting the setup to be made. Every minute, a script checks if there is something to do. If there is a sandbox to setup, the script will install the requested configuration, and send you an email once it's done.

Step 3 : communication

If you have provided an email address during the request for a sandbox set-up process, look at your mailbox. You'll receive an email when the sandbox is ready to be used. Depending on the database you've requested, the email will arrive more (less than one minute) or less (up to 5 minutes) quickly. If you haven't provided an email address (bad idea), just wait a moment and go to step 3.

Step 4 : login

You can now go back to the sandbox list, click on the staff interface of the sandbox number you asked for and log-in to the Koha staff interface. Depending on the database you've choosen, the login/password will differ. This access information is available under the heading "Databases".

When you log-in, you'll see, on the left, the result of your configuration request.

  • If something went wrong with automatically applying the patch, it will be written. In this case, forget the sandboxes to test it: just head to bugzilla, and enter a comment to say "I tried to test this patch with the sandbox system, it does not work, here is the result & paste what is written ..."
  • If everything went well, you can test the patch, and, if you validate the patch, then add a message on bugzilla and change the status to "signed-off". Note that you can't upload a signed-off patch automatically for instance. This feature could be added, but it does not exist yet.

Step 5 : time for more testing?

Once you've tested a patch and want to test another one... just go to step 1 again, and repeat.

Databases : Choose one option

When a sandbox is installed, all the important dates in Koha are updated to today's date. For example, a check-out that is late since "yesterday" will still be due for "yesterday" if you choose the database again next week. If you want to add another database for tests, just drop me a mail (Paul Poulain, current RM, paul.poulain at with the database, i'll add it quickly.

Option 1: no change (-1)

This is the fastest option. If you're testing patches one after the other, you probably can choose this option (except for the first loop, of course). It won't update the database. So a biblio you've just entered, or a debarred patron, will be kept as you've set them. If you choose this option, you won't do a zebra reindexing, that can be quite long for some sample databases.

Option 2: no database (run webinstaller) (0)

As described, you won't get any database. This is probably an option you'll use rarely, but it can sometimes be useful. And for testing installer, this is a must-have!

Option 3: marc21 tiny dataset (1)

Default config, login/password with test/test, superlibrarian, 101 biblio, some with items, some without (barcode 1 to 10 exist, as well as barcode 2012-0001 to 2012-0100).

Option 4: UNIMARC public library (2)

Public library with 5k biblio, a lot of members, circulation history, holds. Acquisition not used in real situation, so only sample datas (log-in with test/test)

Note that when you set-up this database, your email will contain 3 errors that you can ignore:

1) DBD::mysql::db do failed: Table 'pending_offline_operations' already exists at installer/data/mysql/ line 4723.
2) DBD::mysql::db do failed: Unknown table 'bibliocoverimage' at installer/data/mysql/ line 4897.
3) DBD::mysql::db do failed: Table 'biblioimages' already exists at installer/data/mysql/ line 4898.

Tips and tricks

Testing with "master"

"Master" is the technical name for the uptodate version of Koha (not the last release, but what will be released on the next release. Most bugs you'll have to test will say something like: "this feature is not working in master before applying this patch, it's working well after applying the patch". You may/will want to compare the differences. The sandbox system can help you: just ask for "master" instead of entering a bugzilla number.

A workflow suggestion

1) go to the sandbox list, select a sandbox and ask for "master"(not a bugzilla #) and the db you need
2) log-in again when you've received the email confirming set-up and test the behaviour(that is wrong)
3) go to the sandbox list again, ask for NNNN (the bug you want to test), with database= -1 (no change)
4) log-in again when you've received the email confirming set-up, and test that the behaviour is now correct
5) Update the bugzilla ticket

Hint : you can even use 2 sandboxes in parallel, one running master, one running the bug you want to test, each on it's own Firefox tab. It's very handy and efficient way of testing patches or Koha improvements!

Testing sending emails

If you want to test a bug concerning emails or for example test sending a cart by email, you must specify a valid email adress in system preference "KohaAdminEmailAddress".

Available Sandboxes



BibLibre provides some sandboxes (login: test/test):

Sandboxes 1 to 3 and 13 to 17 have a UNIMARC configuration for zebra.
Sandboxes 6 to 8 have a MARC21 configuration for zebra.

So, if you want to test a patch and you need zebra, choose wisely ! If you ask for a MARC21 database on a UNIMARC zebra set-up, everything will be OK, except zebra!

Limits of those sandboxes
It's not possible currently to properly test zebra/dbupdate/installer patches with those sandboxes

Sandbox list
Sandbox setup
Zebra configuration
URL of the staff interface
Sandbox 1 UNIMARC
Sandbox 2 UNIMARC
Sandbox 3 UNIMARC
Sandbox 6 MARC21
Sandbox 7 MARC21
Sandbox 8 MARC21
Sandbox 13 UNIMARC
Sandbox 14 UNIMARC
Sandbox 15 UNIMARC
Sandbox 16 UNIMARC
Sandbox 17 UNIMARC
If you encounter a problem with these sandboxes, please send a mail to sandboxes at biblibre dot com or ask on the irc channel.

PTFS Europe

PTFS Europe are providing the below sandboxes for the community. (login: test/test):

Important Information

  • All PTFS Europe sandboxes have a MARC21 configuration for zebra (Using DOM for Authorities, DOM for Biblios and ICU for characters)
  • Everything else is as per the biblibre sandboxes
  • It is the aim at some point to build a larger MARC21 sample database, if you have such a database (preferably not too big) which you would be happy to donate (I would anonymize any patron data before using it) we would be most grateful.
  • We are currently revisiting our sandbox setup. For now we are cutting the number of sandboxes to 2, to improve reliability of our sandbox server. We are investigating the configuration of additional sandbox servers.

Sandbox list
sandbox # URL to setup the sandbox
URL of the staff interface
sandbox 0
sandbox 1
If you encounter a problem with these sandboxes, please send a mail to sandboxes at ptfs-europe dot com or contact Martin Renvoize (aka ashimema) on the irc channel

ByWater Solutions

ByWater Solutions are providing the below sandboxes for the community. (login: test/test):

See a video demo of how to use these sandboxes here:

Sandbox list
sandbox # URL to setup the sandbox
URL of the staff interface
sandbox 1
sandbox 2
sandbox 3
sandbox 4
sandbox 5
If you encounter a problem with these sandboxes, please send a mail to support at bywatersolutions dot com or contact Kyle Hall (aka khall) on the irc channel
Personal tools