From Koha Wiki

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



Sandboxes have been developed with the goal to lower the barrier for testing patches for Koha.

You can set up a sandbox with a current development version of Koha, sample data and the patches of a bug applied for you. Once you have finished testing, you can use a form to 'sign off' on the patches and move the bug report to the 'Signed off' status from where it will continue into QA.

The code of the sandboxes and documentation on how to set them up has been released under GPL and can be found in the contrib part of the general repository:;a=tree;f=sandbox

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.

The mechanism

Tutorial video

Step 1: Select a bug to test in Bugzilla

Bugs in Bugzilla can be bug fixes, small enhancements or complete new features. As there is always a lot going on, selecting a bug can take some time.

You don't need an account to search in Bugzilla, but in order to make status changes and to comment, you will have to register.

You can create a list of all bugs in the 'Needs Signoff' status by using Bugzilla's Advanced search. Just click on 'Needs Signoff' in the status field and start the search. Another way is to use the link from the Koha Dashboard (requires to be logged in).

The component column will give you an idea about the area in Koha this bug applies to. Templates bugs are often a good place to start with sandbox testing.

Once you have found a bug you'd like to test, note the bug number for the next step.

Note: There are some limits to sandbox testing. Things that cannot be tested currently include:

  • Changes to the Zebra index configuration (new or changed indexes, etc.)
  • Anything that requires command line access (cronjobs, etc.)

Step 2: Set up a sandbox

  • Pick a sandbox from the list of sandboxes at the bottom of this page. Be careful to pick one with the MARC flavor you are familiar with.
  • Click on the link in the Sandbox setup column.
  • You will see a page with 2 forms. The first form is used for setting up the sandbox. Below the heading Welcome to the Koha sandbox tester it displays information about the last use of 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.
  • Next step is to fill out the form:
    • Bugzilla numbers: mandatory, either the number of the bug you want to test or the word master. With master the sandbox will be set up without any patches applied. (see also: Testing with master)
    • Your name: not mandatory
    • Your email address: not mandatory, but it will allow the sandbox to inform you when it's ready for testing. It will also show below the heading. It will give people a clue, that you are currently working with this sandbox.
    • Translations: not mandatory. In order to help you with testing, you can set up the sandbox in your preferred language. If you leave this empty, the sandbox will be English only.
    • Database: you have several options and sample databases to pick from. Find out more under Databases
    • Anti-Spam: mandatory basic anti-spam entry to keep any bots out. Just enter Koha here.
  • Submit the form.

Once submitted, a small file will be written on the sandbox server, requesting the setup to be made. Every minute, a script checks if there is something to do. Depending on your chosen configuration and the sandbox/server you picked in can take a few minutes to set up the sandbox for use.

If you have provided an email address, you will receive an email once it's done. If you haven't provided an email address, just wait a moment and continue to the next step.

Step 3: Login and testing

  • You can now use the links to the staff and OPAC interface of your selected sandbox. The password/login is usually test/test, if it's different this will be noted under Available sandboxes.
  • After log in information about the configuration will be displayed in the news entries on the left of the staff start page.
    • If something went wrong while applying the patch, it will be displayed there. In this case: Enter a comment in Bugzilla, for example: "I tried to test this patch with the sandbox system, but there was a problem" and copy what is written on the staff page below.
    • If everything went well, you can test the patch.
      • If you run into problems, please add a description of it as a comment in Bugzilla and set the status to Failed QA.
      • If everything is working and looking great, please add your sign-off! (see step 4).

Step 4: Sign-off

  • Return to the Sandbox setup page. For the sign-off process, the second form on this page will be used.
  • Enter your information:
    • Signoff Bugzilla number: the bug number of the bug you want to sign-off on.
    • Your name: your name. It will be part of the sign-off line added to the patch files.
    • Your email: your email address. This will also be part of the sign-off line. Together with your name this information will be used for building the release notes and for the Dashboard.
    • Anti-spam: Just enter Koha here.
    • Submit the form. If you check the bug on Bugzilla now the status should have changed to Signed-off and a patch with your name in it should have been attached.

Step X: Time for more testing?

Once you've tested a patch and want to test another one...repeat from step 1.


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, drop an email to Paul Poulain (paul.poulain at with the database and it will be added quickly.

Option 1: no change (-1)

This is the fastest option as it won't update the database. This is especially useful if you are testing patches one after the other (see A workflow suggestion). If you're testing patches one after the other, you probably can choose this option (except for the first loop, of course). A bibliographic record you've just entered, checkouts you have made, any changes you have made will be kept as you've set them. If you choose this option, the Zebra indexes won't be rebuilt which will also save setup time as it can take a while for some of the sample databases.

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

This is also a fast option as there won't be any database created. When accessing the sandbox staff side, the web installer will be triggered. This is especially useful for testing patches for the web installer, but will otherwise probably be rarely used.

Option 3: MARC21, tiny dataset (1)

The database contains 101 bibliographic records, some with items, some without (barcodes 1 to 10 exist, as well as barcodes 2012-0001 to 2012-0100). Using the login/password test/test will give you access with superlibrarian permission.

Option 4: UNIMARC, public library (2)

Public library with 5k bibliographic records, a lot of members, circulation history, and holds. The acquisitions module was not used and only contains some sample data. The login/password is also test/test.

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

DBD::mysql::db do failed: Table 'pending_offline_operations' already exists at installer/data/mysql/ line 4723.
DBD::mysql::db do failed: Unknown table 'bibliocoverimage' at installer/data/mysql/ line 4897.
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 current developer 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
  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 setup, 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 a very handy and efficient way of testing patches or Koha improvements!

Testing sending emails

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

Available Sandboxes

When picking a sandbox, please note the MARC flavor it's set up for as this will effect indexing and searching. If you ask for a MARC21 database on a UNIMARC Zebra set-up, everything will be OK, except search and indexing.


BibLibre are providing the below sandboxes: login/password test/test.

Sandbox list
Sandbox setup
Zebra configuration
URL of the staff interface
Sandbox 01 UNIMARC
Sandbox 02 UNIMARC
Sandbox 03 UNIMARC
Sandbox 04 UNIMARC
Sandbox 05 UNIMARC
Sandbox 06 MARC21
Sandbox 07 MARC21
Sandbox 08 MARC21
Sandbox 09 MARC21
Sandbox 10 MARC21
If you encounter a problem with these sandboxes, please send an email 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/password test/test

Important Information

  • All PTFS Europe sandboxes have a MARC21 configuration with ICU for Zebra
  • 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 setup Zebra configuration URL of the staff interface OPAC URL
Sandbox 0 MARC21
sandbox 1 MARC21
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/password test/test

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

Sandbox list
Sandbox setup Zebra configuration URL of the staff interface
Sandbox 1 MARC21
Sandbox 2 MARC21
Sandbox 3 MARC21
Sandbox 4 MARC21
Sandbox 5 MARC21
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

Tester handbook

Personal tools