Nitrate

= Nitrate =

Nitrate a new test case management system, it's written in Python and uses the Django web framework.

The TCMS provides:


 * Managers with a source of information on planning, cases and execution status.
 * Reproducibility across planning, cases and execution.
 * Audit traceability.
 * Increased productivity - Associates are able to identify and work on gaps in product coverage.
 * Fully functional XML-RPC interface.
 * Multiple authentication backends.

"If it is not in the TCMS then we do not do it", and the converse: "If we do it then it is in the TCMS". That motto has been the paradigm driving the development of the TCMS. The development team has created a canonical source of information about testing that is useful to both managers and QE Associates.

= Source Code =

We are using "git" to manage our source code. An excellent tutorial on the use of git can be found at Git-Scm. The source code can be viewed via a web UI at git fedorahosted.

Anonymous access
git clone git://git.fedorahosted.org/nitrate.git

Commit access
git clone ssh://git.fedorahosted.org/git/nitrate.git

= Installation =

How to install Nitrate on your computer, please follow this steps:

Create a development environment
Nitrate is standard Django app. The deployment method is the same as others. Before you starting to installation, please prepare the requirements as following:

Requirements
Recommendations for development
 * Python >=2.4
 * Django = 1.2.3
 * Python-MySQL
 * Kobo
 * Python-kerberos
 * Django debug toolbar

Download Source Code
You can easy to get the latest code with git:


 * 1) git clone git://git.fedorahosted.org/nitrate.git

Generate the Configuration File
We recommend you to create a new settings file based on nitrate/tcms/settings.py file for develop environment or production environment. As you can see the settings.py file contains default/safest configurations, create another settings file contains the configurations you private will be more better than modify the default settings.

At this moment, I presume the file you write named 'dev_settings.py', place the file to the same path as settings.py.

You may need to modify following contents, for more, reference the settings.py:
 * 1) Database settings

DATABASE_ENGINE = 'sqlite3'    # 'postgresql_psycopg2', 'postgresql', # 'mysql', 'sqlite3' or 'oracle'. DATABASE_NAME = 'dev.db'       # Or path to database file if using sqlite3. DATABASE_USER = ''             # Not used with sqlite3. DATABASE_PASSWORD = ''         # Not used with sqlite3. DATABASE_HOST = ''             # Set to empty string for localhost. # Not used with sqlite3. DATABASE_PORT = ''             # Set to empty string for default. # Not used with sqlite3.

TIME_ZONE = 'Asia/Shanghai'
 * 1) Local time zone for this installation. Choices can be found here:
 * 2) http://en.wikipedia.org/wiki/List_of_tz_zones_by_name
 * 3) although not all choices may be available on all operating systems.
 * 4) If running in a Windows environment this must be set to the same as your
 * 5) system time zone.


 * 1) Mail settings

EMAIL_HOST = '' EMAIL_PORT = 25 EMAIL_FROM = 'noreply@foo.com' EMAIL_SUBJECT_PREFIX = '[TCMS] '
 * 1) Set the default send mail address
 * 2) See http://docs.djangoproject.com/en/dev/ref/settings/#email-backend

FIRST_RUN = True
 * 1) First run - to detemine need port user or not.

FOOTER_LINKS =
 * 1) The URLS will be list in footer
 * 2) Example:
 * 3) FOOTER_LINKS = (
 * 4)   ('mailto:nitrate-dev-list@example.com', 'Contact Us'),
 * 5)   ('mailto:nitrate-admin@example.com', 'Request Permission'),
 * 6)   ('http://foo.com', 'foo')

Initial database schema
Database is required by Nitrate(and all of Django apps). The Django ORM supports many database backends, we recommend you to use MySQL(In fact it's a bug so far).

We provided two SQL file for usage.

Empty testopia dumps file: https://fedorahosted.org/nitrate/browser/trunk/nitrate/docs/testopia-dump-blank.sql

Nitrate upgrade dumps file: https://fedorahosted.org/nitrate/browser/trunk/nitrate/docs/mysql_initial.sql

First you need define the mysql database configuration in dev_settings.py file. Then download and import the database dumps files, I presume the database named 'nitrate'. $ mysql -u [db_username] -p nitrate < testopia-dump-blank.sql $ mysql -u [db_username] -p nitrate < mysql_initial.sql

Then use the django-admin syncdb to initial the data. $ export DJANGO_SETTINGS_MODULE=tcms.dev_settings

If you are install from git source you need to define the env as following: $ export PYTHONPATH=[nitrate_download_path]/nitrate/trunk/nitrate/ $ django-admin syncdb If you got some errrors report, just try to type upon commands and run again.

The data initialization
The initial data including the first super user, site definition, they will be needed by the server running.

Add the super user
Simple type following commands in shell should be OK $ django-admin.py createsuperuser Username: [You login user name] E-mail address: [Your email] Password: [Your password] Password (again): [Your password again] Superuser created successfully. For more information access the User authentication in Django.

Add the site definition
Here you need some python skills, just type like following: $ python >>> from django.contrib.sites.models import Site >>> Site.objects.create(name="example.com")

Replace the "example.com" to your web server domain name, the definition will be used in mailing system.

For more information access the Django site framework.

Start the Django app
After upon steps completed, now you can try to start the web server built-in Django to testing the app running.

Define the envs again if you does not completed the steps, it should confirm the envs exist in system before start the server. $ cd [nitrate_download_path]/nitrate/trunk/nitrate/ $ export DJANGO_SETTINGS_MODULE=tcms.dev_settings $ export PYTHONPATH=[nitrate_download_path]/nitrate/trunk/nitrate/

$ django-admin runserver

Then try to use web browser to open http://localhost:8000/ to see the web service working status.

Basic admin works
After your typed your super user user name and password in the browser, you will see the "Home page" of Nitrate, there are some configuration needed by you enter in the admin system.

Bug Tracker Initialization
Access http://localhost:8000/admin/testcases/testcasebugsystem/ on your server, and add a new bug tracker URL to Nitrate, it's required by execute run feature.

Click the 'Add test case bug system' link in the top of the table, type the name and description as your wish, then type the 'Url reg exp' like 'https://bugzilla.redhat.com/show_bug.cgi?id=%s', The '%s' will be replaced by bug ID.

Nitrate supported multiple bug tracker system backend, the only requirement is the bug tracker supports access the bug with bug ID.

User Groups Initialization
Access http://localhost:8000/admin/auth/group/ on your server, you need to create the group need by tester at least, apply all of add/change permissions(The permissions starts with 'auth_' also be excluded) to the group.

Then when a new memember join the system, just apply the tester group he will get the minimal permissions to create/update test plan/case/run and execute the run.

You also can create a group named 'Administrator', apply the people management permission(The permissions name starts with 'auth_') to it, allocate some trusted people to the group for the user management work.

Deploy with Apache
We recommend to use the WSGI method, it saves resources and very fast. The sample is located at: https://fedorahosted.org/nitrate/browser/trunk/nitrate/contrib/conf/nitrate-httpd.conf

Take care the config file enabled mod_auth_kerb authentication, you may need to comment the settings starts with 'Auth' and 'Krb' at first.

Then place the file to /etc/httpd/conf.d/ and modify the files path from default to you specific should be OK.

Deploy with mod_auth_kerb
First you need to request the keytab file and a /etc/krb5.conf from your KDC administrators at first, place the keytab file to /etc/httpd/conf/httpd.keytab and place the krb5.conf file into /etc.

Then modify the Nitrate product settings file. I recommend you to create another settings file inherit from dev_settings.py to disable DEBUG options and other configuration settings you need in production environment, I presume new settings file named 'product_settings.py' here.

Then modify the authentication backends settings in the file as following:
 * 1) Authentication backends

AUTHENTICATION_BACKENDS = (   'tcms.core.contrib.auth.backends.ModAuthKerbBackend', ) Then restart the web server should be done.

Deploy with Nginx
With benchmark, we found Nginx + FCGI is faster than Apache + Mod_python, To use the Nginix to deploy the Nitrate will be a good idea for production environment.

The configuration sample located at: https://fedorahosted.org/nitrate/browser/trunk/nitrate/contrib/conf/nitrate-nginx.conf

The file is very initial, and patches are welcome.

= Contact us =
 * Email: nitrate-devel@lists.fedorahosted.org
 * Mailing list: https://fedorahosted.org/mailman/listinfo/nitrate-devel
 * IRC Channel: nitrate @ irc.freenode.org