Version 52 (modified by spM, 12 years ago) ( diff )



"A bug is a test case you haven't written yet"

"Unit Tests allow merciless refactoring"

This page defines what our current approach versus our BluePrint for future options

Test-Driven Development is a programming style which says that you 1st write your test cases (from the specs) & then proceed to make them pass.


Selenium provides the ability to test Sahana Eden as users see it - namely through a web browser. This therefore does end-to-end Functional Testing, however it can also be used as Unit Testing

We are building our framework around the new WebDriver, despite having some legacy code in the older format:

The tests are stored in eden/modules/tests

Installation of the testing environment in your machine

In order to execute the automated Selenium powered test scripts, you must install the Selenium Web Drivers into Python.

*Web2py will need to be installed, and should come with the installation of Sahana Eden.

Download and install the latest Selenium package, which can be found at

tar zxvf selenium-2.25.0.tar.gz
cd selenium-2.25.0
python install

Running / Executing Automated test scripts:

Before running the Selenium scripts, you should put your database into a known state:


In your models/, uncomment the lines that disable confirmation popups:

# Should user be prompted to save before navigating away?
settings.ui.navigate_away_confirm = False
# Should user be prompted to confirm actions?
settings.ui.confirm = False

For the whole test suite, uncomment the following line in models/

settings.base.prepopulate = ["IFRC_Train"]

Make sure that settings.base.migrate = True and settings.base.debug = True in the config file.

Then you will need to re-populate: delete the contents of databases/* , errors/* and sessions/*

cd web2py/applications/eden
rm databases/* sessions/* errors/*

Start the Web2py server at (Selenium will start a captive browser, which it will direct to contact the server at

Run the whole test suite for the Eden application:

cd web2py
python -S eden -M -R applications/eden/modules/tests/

Run a class and all tests in that class:

cd web2py
python -S eden -M -R applications/eden/modules/tests/ -A -C mytestclass

Run just one test within a class:

cd web2py
python -S eden -M -R applications/eden/modules/tests/ -A -C mytestclass -M mytestmethod

Command Line Arguments

A number of command line arguments have been added and more are being added so to get the latest list of available options use the --help switch, which you can quickly do as follows:

python -S eden -M -R applications/eden/modules/tests/ -A --help

Important options include:

-C for class to run

-M for test method within a class to run, when you use this option either use the -C option or provide the method in the format class.method

If you have HTMLTestRunner installed then a nicely formatted html report will be generated, should you want to disable this then use the --nohtml option. The HTML report will be written to the path given by the switch --html_path which by default will the web2py folder since that is where the tests scripts are run from. The file name will have a timestamp appended to it, if you want you can have just a date by using the option html_name_date.

The option --suite will run certain predefined tests. At the moment it supports smoke, which runs a test to look for broken urls otherwise it will run all the tests. If a class or method are selected then this option is ignored. For the smoke test to work you need to install two packages, twill and mechanize, since twill uses mechanize if you install via a package manager then you probably only need to install twill.

Writing / Creating your own test scripts:

We aim to make it as easy as possible to write additional tests, which can easily be plugged into the Sahana Eden Testing System Framework.

The canonical example is: eden/modules/tests/org/

New tests should be stored in a subfolder per module, adding the foldername to eden/modules/tests/ & creating an in the subfolder.

A walk-through example:
We want to make an automated test script to test the Create Organization module. Create Organization falls under Human Resources Management (HRM) feature, therefore we must add this test script module file in the subfolder /hrm (eden/modules/tests/hrm/)

Steps of automated the test for Create Organization:

1) Let's call this test file: and save it in the subfolder /hrm.

2) We must now make sure we add the file name in the Open file in the subfolder /hrm and add:

from create_organisation import *


import os
import time
from selenium.common.exceptions import NoSuchElementException
from gluon import current
from s3 import s3_debug
from tests.web2unittest import SeleniumUnitTest

class CreateOrganization(SeleniumUnitTest):

    # -------------------------------------------------------------------------
    def test_org001_create_organisation(self, items=[0]):
            Create an Organisation
            @param items: Organisation(s) to create from the data

            @ToDo: currently optimised for a single record
        print "\n"
        # Configuration
        self.login(account="normal", nexturl="org/organisation/create")
        tablename = "org_organisation"
        #data =["organisation"]
        # Data for the Organisation resource
                    [( "name", "Romanian Food Assistance Association (Test)"), ( "acronym", "RFAAT"), ("website", ""), ("comments", "This is a Test Organization")]
        for item in items:
            _data = data[item]
            # Check whether the data already exists
            s3db = current.s3db
            db = current.db
            table = s3db[tablename]
            fieldname = _data[0][0]
            value = _data[0][1]
            query = (table[fieldname] == value) & (table.deleted == "F")
            record = db(query).select(,
                                      limitby=(0, 1)).first()
            if record:
                print "org_create_organisation skipped as %s already exists in the db\n" % value
                return False

            # Login, if not-already done so
            self.login(account=account, nexturl=url)

4) To run this automated test script. Open (modules/tests/ and add at the bottom of script so it can be executed. (NOTE: We add the class name, not the function name).


5) Run your test script. (Refer above on how to run/execute test scripts from the Test Suite).

Splitting Test Functions:
We aim to keep the test script as clean and understandable as possible. Therefore, we must separate the test functions which drives the a particular test script to another file. As you can see with the Inventory feature tests, there is a file in the INV subdirectory called This file contains all functions which helps drive the Inventory module tests such as, and so forth.

Other information on the Test System framework:

The key is to make tests which are as least fragile as possible through:

  • State (we should be able to run individual tests easilty, which check their current state as-required)
  • Deployment_Settings
  • Localisation
  • Theme

This suggests refactoring tests to centralise common elements into a library to mean fixes should only happen in 1 place.

There are a number of possible selectors to use to find your elements...the 'ID' may be the most stable, so don't be afraid of patching the code to add IDs where you'd like to be able to reach them reliably:

We separate data out into a separate file, so that this is easy to change to allow reruns of the tsts with different data sets.

Unit Tests

There are additional unit tests available, which also require running with the IFRC_Train preopulate, 'settings.base.prepopulate = 27':

To run all unit tests:

python -S eden -M -R applications/eden/modules/unit_tests/

These unit tests are meant to detect problems early during development, which means you should run them quite often while you're still working on the code (read: before and after every little change you make) rather than expecting them to be run during QA cycles. That again means you would more often need to run tests for particular modules than the whole suite.

For every module in modules/s3 and modules/eden, you can find the corresponding unit test module under modules/unit_tests/eden resp. modules/unit_tests/s3 (if one exists).

To run tests for particular modules:

# e.g. for modules in modules/s3
python -S eden -M -R applications/eden/modules/unit_tests/s3/
# e.g. for modules in modules/eden
python -S eden -M -R applications/eden/modules/unit_tests/eden/

It can be a very powerful development strategy - especially for back-end APIs - to first implement unit test cases for the functionality you intend to implement before actually implementing it. Apart from preventing bugs, this helps you to validate your design against requirements, and to keep the implementation simple and focussed. Additionally, the test cases can be a rich source of code samples how to apply your API methods.

Role Tests

This test is used to check the permissions of user roles. Currently is limited to the IFRC (Red Cross) roles for RMS, but could be extended:

python -S eden -M -R applications/eden/modules/tests/ -A --suite roles

Load Testing

We recommend using Tsung

See Also

Systers' approach:

Alternative Options:

Note: See TracWiki for help on using the wiki.