= Roles Tests =

== Introduction ==

Role tests are used to check the permissions of user roles.

== Running The Tests ==

Make sure that the database is prepopulated. If not, then run -
{{{
cd web2py/applications/eden
rm databases/*
cd ../..
python web2py.py -S eden -M -R applications/eden/static/scripts/tools/noop.py
}}}

To start the tests, run -
{{{
python web2py.py -S eden -M -R applications/eden/modules/tests/suite.py -A --suite roles
}}}

== Writing Role Tests for a Template ==

To write role tests for a template, you will need to create a folder for that template in the role test folder: {{{modules/tests/roles/<template_name>}}}. In this folder you'll have to create the following files. 

=== organisations ===
{{{<template_name>/organisations.xml}}}[[BR]]
This file will specify which organisations & branches data & users are created for.


=== data ===
{{{<template_name>/data.xml}}}[[BR]]
This file will define the data that will be created for the user's roles will be tested against. See existing examples and [wiki:S3XML#XMLFormat] for how to format this file. This file will include the string {{{%(org)s}}} which will be replaced with the name of the organisation/branch.

=== users template ===
{{{<template_name>/users_template.csv}}}[[BR]]
A file template for the users and roles which will be tested. See existing examples for how to format this file. This file will include the string {{{%(org)s}}} which will be replaced with the name of the organisation/branch. To assign a role for an organisation, using this syntax: {{{<role_name>/org_organisation.name=%(org)s}}}.

=== Test Users (optional) ===
{{{<template_name>/test_users.csv}}}[[BR]]
An optional file which is used to create users - handy for debugging.

=== Permission Matrix ===
{{{<template_name>/Org-A_permission_matrix.csv}}}[[BR]]
The permissions declared in this file are tested upon. Currently permissions are only tested for users from Org-A, but you can test their access to data from other Organisations.

== Role Test Documentation  ==
The tests are located in {{{modules/tests/roles/}}}
Files:
* The file {{{modules/tests/roles/test_roles.py}}} tests permissions against role matrix file.
* The data for the roles tests is created by {{{modules/tests/roles/create_role_test_data.py}}}