Case Conductor is a Test Case Management system. Copyright (C) 2011 uTest Inc.

This file is part of Case Conductor.

Case Conductor is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Case Conductor is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Case Conductor. If not, see <http://www.gnu.org/licenses/>.

This Django project is the user interface to the Case Conductor test case management system. It lives at https://github.com/mozilla/caseconductor-ui/, and is built to speak via HTTP API to the platform at https://github.com/mozilla/caseconductor-platform.

This version of the UI expects to use git commit hash '26b09086dcace12ad15f12f8dc272352d2411efb' of the platform. A pre-built WAR file of this version of the platform is provided at platform/tcm.war. The database scripts required to set up an initial platform database are in platform/db_scripts, and platform/reset-mysql.sh automates setting up the database. (See the platform README at platform/README.rst).

The Case Conductor UI requires Python 2.6 or 2.7.

First, update git submodules (dependency source distribution tarballs are stored in a git submodule). From the root of this repo, run:

git submodule init; git submodule update

If you want to run this project in a virtualenv to isolate it from other Python projects on your system, create the virtualenv and activate it. Then run ui/bin/install-reqs to install the dependencies for this project into your Python environment.

You'll need to create a ccui/settings/local.py file with some details of your local configuration. See ccui/settings/local.sample.py for a sample that can be copied to ccui/settings/local.py and modified.

Two settings are required:

CC_COMPANY_ID

The UI is per-company, and will ignore all data related to other companies. This setting should be the (integer) id of the company whose data this instance of the UI should manage.

CC_NEW_USER_ROLE_ID

The (integer) id of the role that all new user registrations should be given by default.

The create_company management command is available to create an initial company and a default user role. Run ./manage.py create_company "Company Name"; a new company named "Company Name" and two roles, named "Company Name Tester" and "Company Name Admin" will be created, and the command will output their IDs, which can then be used for the above two settings.

Several other settings have reasonable defaults, but may need to be modified:

CC_API_BASE

The base URL for the platform API. Defaults to "http://localhost:8080/tcm/services/v2/rest/"

CC_ADMIN_USER

The UI generally uses the privileges of the logged-in user for all API calls, but requires admin privileges on the platform API for certain operations, such as creating new users and assigning them their default role. This should be the email address of the admin credentials to use; defaults to "admin@utest.com".

CC_ADMIN_PASS

Password for CC_ADMIN_USER. Defaults to "admin".

Once this configuration is done, you should be able to run ./manage.py runserver and access the UI in your browser at http://localhost:8000.

All Compass/Sass files are pre-compiled to CSS, so no gems are development, run bin/install-gems requirements/gems.txt. Update requirements/gems.txt if newer gems should be used.

The UI codebase has an automated test suite. The platform is mocked out in the test suite, so having the platform running is not a requirement for running the tests.

To run the tests, after installing all Python requirements into your environment:

bin/test

To view test coverage data, load coverage/index.html in your browser after running the tests.

To run just a particular test module:

bin/test tests.core.test_api

To quickly populate the platform with a small amount of sample data for development and manual testing, run ./manage.py create_test_data. This will create a user with email address tester@example.com with the default new user role and password testpw, as well as several products, a test cycle, test run, and a couple test cases.

You can optionally pass an argument to the create_test_data command, the integer ID of the admin role created by create_company (above). If given an admin role ID, create_test_data will also create an admin user admin@example.com with that role and password testpw.

Django's runserver is not suitable for a production deployment; use a WSGI-compatible webserver such as Apache with mod_wsgi, or gunicorn. You'll also need to serve the static assets; Apache or nginx can do this.

For deployment scenarios where pip-installing dependencies into a Python environment (as bin/install-reqs does) is not preferred, a pre-installed vendor library is also provided in requirements/vendor/lib/python. The site.addsitedir function should be used to add this directory to sys.path, to ensure that .pth files are processed. A WSGI entry-point script is provided in deploy/vendor.wsgi that does all the necessary sys.path adjustments.

In addition to the above configuration, in any production deployment this entire app should be served exclusively over HTTPS (since almost all use of the site is authenticated, and serving authenticated pages over HTTP invites session hijacking attacks). Ideally, the non-HTTP URLs should redirect to the HTTPS version. The SESSION_COOKIE_SECURE setting should be set to True in ccui/settings/local.py when the app is being served over HTTPS. You can run "python manage.py checksecure" on your production deployment to check that your security settings are correct.

Case Conductor UI stores user session information in the cache. For local development the default cache backend is the "local memory" backend. Since many production webservers are multi-process, this cache backend is unsuitable for production use. Preferably, memcached should be used as the production cache backend. Alternately, to reduce infrastructure dependencies for very small installations, user sessions can be stored in a SQLite database. Examples of both of these configurations can be found in the sample local-settings file at ccui/settings/local.sample.py.

This app also uses the new staticfiles contrib app in Django 1.3 for collecting static assets from reusable components into a single directory for production serving. Run ./manage.py collectstatic to collect all static assets into the collected-assets directory (or whatever STATIC_ROOT is set to in settings/local.py), and make those collected assets available by HTTP at the STATIC_URL setting.