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, some members, circulation history, and holds. The acquisitions module was not used and only contains some sample data. The login/password is also test/test.

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

But because the sandboxes do not actually send out e-mails, you will need to use a SQL report to view the contents of the generated e-mails found in the message_queue table.

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 for the community: login/password test/test.

They are build with Zebra search engine and some also ElasticSearch. For tests requiring Zebra search, use the correct MARC Flavour.

You can access ElasticSearch server via /elasticsearch/, index is named koha_master.

Sandbox list
Sandbox setup Configuration URL of the staff interface OPAC URL
Sandbox 01 Zebra UNIMARC Staff 01 OPAC 01
Closed outside of HackFests Zebra UNIMARC Staff 02 OPAC 02
Closed outside of HackFests Zebra UNIMARC Staff 03 OPAC 03
Sandbox 04 actually used for Mana Bug 17047 and Bug 18618 Zebra UNIMARC Staff 04 OPAC 04
Sandbox 05 Zebra MARC21 Staff 05 OPAC 05
Closed outside of HackFests Zebra MARC21 Staff 06 OPAC 06
Closed outside of HackFests Zebra UNIMARC Staff 07 OPAC 07
Closed outside of HackFests Zebra UNIMARC Staff 08 OPAC 08
Closed outside of HackFests Zebra UNIMARC Staff 09 OPAC 09
Closed outside of HackFests Zebra UNIMARC Staff 10 OPAC 10
Sandbox 11 Zebra UNIMARC + ElasticSearch Staff 11 OPAC 11
Closed outside of HackFests Zebra UNIMARC + ElasticSearch Staff 12 OPAC 12
Closed outside of HackFests Zebra MARC21 + ElasticSearch Staff 13 OPAC 13
Closed outside of HackFests Zebra MARC21 + ElasticSearch Staff 14 OPAC 14
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

Sandbox list
Sandbox setup Zebra configuration URL of the staff interface OPAC URL
Sandboxes Trial new sandbox server using the new docker based systems
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

The username and password are 'koha'

Videos on how to use:

Tester handbook

Personal tools