Installation & Configuration Manual

TestLink 1.6

















Copyright © 2004,2005,2006 TestLink Development Team

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. The license is available in "GNU Free Documentation License" homepage.



1 Scope

This document only serves as a reference document for the installation and configuration of TestLink. The first part includes the installation procedure and second part the configuration explanation.

The current and other documentation is available on TestLink homepage. You can also ask a help to solve your problems in an appropriate section of TestLink forum.

Summary of installation process:

  1. Tranfer files

  2. Uncompress files

  3. Generate database tables

  4. Transfer data or create default data

  5. Edit configuration file

  6. PHP File extensions

  7. Login

2 System Requirements

TestLink requires these applications as background:

There is no requirement about your operating system (tested on Linux and MS Win32).

You can use also MySQL on different server than TestLink.






3 Pre-installation steps

Do the next steps before installation:

  1. Install environment: Webserver, php4 and MySQL. Refer to documentation of these products. You can also find installations package of all these products and install it together. E.g. XAMPP, EasyPHP, Uniform Server, etc.

  2. Transfer the TestLink installation file to your webserver using whatever method you like best (ftp, scp, etc.). You will need to telnet/ssh into the server machine for the next steps.

  3. Next, untar/gunzip it to the directory that you want. The usual command is (1 step):

    # tar zxvf <filename.tar.gz>

    or

    # gunzip <filename.tar.gz>

    # tar xvf <filename.tar>

    Winzip, Stuffit, and other programs should also be able to handle decompression of the archive.

    At this point you may want to rename the directory to something simpler like 'testlink'. You will use the mv command to rename a directory (Windows users substitute the "ren" command or use explorer).

    # mv <directory_name> testlink

  1. Continue Installation or Upgrade.

4 Installation

You can use automatic scripted installation or manual steps. If you are upgrading from a previous version of TestLink look at the Upgrading section.

4.1 AUTOMATIC Installation

The following details the basic steps for installation on any system. The instructions may seem unix-centric but should work fine on Windows systems. Barring complications, it should take you about 10-30 minutes to install, configure, and be using TestLink.

This installation process has changed with release 1.6. Next we will create the necessary database tables and a basic configuration file.

  1. From your web browser access http://<yoursite>/testlink/install/index.php.

  2. This page will walk through the following steps:

  1. After a successful upgrade you should remove the <testlinkwebdir>/install/ directory for security reasons.

  2. The next part involves configuring the installation to work with your specific setup. See configuration section for description of configurable parameter.

4.1.1 MANUAL Installation

If you want to perform a Manual installation (not recomended) here are the steps needed for a successful installation. For installing the DB you can either choose the command line tools available in your MySQL installation or any MySQL Database Client (e.g. phpMyAdmin).

4.2 Ugrading

Major version upgrade: You can upgrade either automatically (via script) or manually. There is a few changes in database against both TL 1.5 and 1.0.4. I.e. you are not able to use directly your original database.

Minor version (maintenance) upgrade is manual, but easy.

4.2.1 Maintenance release update

Maintenance (Bug fixing) release is for example 1.6.0 -> 1.6.1. Database schema doesn't changed in this case.

4.2.2 Automatic upgrading major version

4.2.3 Manual upgrading

This process is not currently supported. You can do it of course after a study of changes in database (e.g. user password is encrypted now, added new fields and tables, etc.) and installation script.

4.2.4 Database Changes description

This chapter describe changes in database against previous versions.

4.2.4.1 Test Plan relation to Product

TL 1.0.4 has not this relation. The solution for the TL 1.6 table include field Product ID in the table. Test Plans could be available over all Products. Such Test Plan has Product ID value = 0.

Configuration within <testlinkinstalldir>/config.inc.php:

$g_show_tp_without_prodid=1;

$g_ui_show_check_filter_tp_by_product = 1;.

4.2.4.2 New Requirements related tables

There are three new tables for requirements based testing.

4.2.4.3 Latin to UTF-8 conversion

TestLink 1.6 allows for UTF-8 encoded character rendering, therefore any extended character data that may have snuck into your database and didn't show up in 1.5 may start appearing in 1.6 UI. You can turn UTF-8 support off in testlink by modifying a value in the <testlinkinstalldir>/config.inc.php file, but then you will be missing out on the ability to use characters beyond ASCII.


If you have the same problem I did and see lots of extended
characters appearing in your data after upgrading to 1.6 and having
UTF-8 support turned on, you should read through the following
instructions. Be sure to practice this exercise on a test machine
before performing on your deployment system.



The instructions will help you clear out any non-ASCII characters
from your database and setup your database to support UTF-8.






















Other resources:


what the heck is UTF-8
? 



http://www.joelonsoftware.com/articles/Unicode.html


octal table (you can
see octal values 000 - 177 are "normal ascii" characters).


The perl script that
is provided searches based on octal values.


http://web.cs.mun.ca/~michael/c/ascii-table.html


description of tr perl
operation


http://www.unix.org.ua/orelly/perl/learn/ch15_05.htm








 5 Configuration


 5.1 Configuration Files


All configuration parameters are inside
the file config.inc.php and included files. For this release (1.6)
these are the configuration files:


<testlink
installation directory>/config.inc.php 



<testlink
installation directory>/config_db.inc.php 



<testlink
installation directory>/cfg/<bug_tracking_system>.cfg.php 









config.inc.php


Main configuration file. See below for
more.


config_db.inc.php


Contains configuration parameters to
access the database. This file is created by the installer during the
installation or upgrade process. Normally you don't need to change it
manually.


/cfg/bugzilla.cfg.php


/cfg/mantis.cfg.php


/cfg/jira.cfg.php


Contains configuration parameters to
access bugzilla, mantis or jira issue tracking system. You need to
edit this file is you want to access issue information from testlink
(bugtracking system integration feature). To enable this feature you
need to change a configuration paramenter on the main configuration
file (config.inc.php)


 5.2 Parameters which must be configured



 5.3 Parameters which may be configured




 5.4 Customization


 5.4.1 Cascading Style Sheet


You can change TestLink appearance
writing you own CSS (Cascading Style Sheet) files.


You have to change the following
constants:


define('TL_LOGIN_CSS','gui/css/tl_login.css');
- All Login/Logout pages CSS


define('TL_TESTLINK_CSS','gui/css/testlink.css');
- Main CSS


define('TL_DOC_BASIC_CSS','gui/css/tl_doc_basic.css');
- Used in Reports


Important: paths to CSS are relative to
the <testlink installation directory>


If you want to use your own CSS files we
suggest you to proceed as follow:


    
	
  1. create a new directory inside
	the gui directory, example gui/css/my_css/
    
	
  2. copy the testlink original files to
	the new directory (you can change the names if you want)
    
	
  3. modify them at your will
    
	
  4. edit config.inc.php
    
	
    // Original
	configuration 
	
    
	
    //define('TL_LOGIN_CSS','gui/css/tl_login.css');
	//define('TL_TESTLINK_CSS','gui/css/testlink.css');
	//define('TL_DOC_BASIC_CSS','gui/css/tl_doc_basic.css'); 
	define('TL_LOGIN_CSS','gui/css/my_css/tl_login_acqua.css');
	define('TL_TESTLINK_CSS','gui/css/my_css/testlink_acqua.css');
	define('TL_DOC_BASIC_CSS','gui/css/my_css/tl_doc_basic.css');
    



 5.4.2 Duplicate names for Products, Components,
Categories, Test Cases


As you know, is possible to create one
of this objects (Products, Components, Categories, testcases) doing a
copy of an existing one.


You can configure how to proceed when
the copy is done:


if you set
$g_check_names_for_duplicates=TRUE
then the following checks will be done:


    
	
  1. Product Name is unique
    
	
  2. Component Name Inside Product is
	unique
    
	
  3. Category Name Inside Component is
	unique
    
	
  4. Test Case Name inside Category is
	unique
    



One you have set
$g_check_names_for_duplicates=TRUE, you can configure how to proceed,
if a duplicate name is found, using $g_action_on_duplicate_name.


The options are:



Example of
formatting:


$g_action_on_duplicate_name='allow_repeat';




$g_prefix_name_for_copy=
strftime("%Y%m%d-%H:%M:%S", time());


 5.4.3 Test Plan relation to Product


Starting with version 1.6 when you
create a Test Plan, it's associated to the current selected Product
as default. This is means you can filter Test Plans by Product.


Before Teslink 1.6 the Test Plans where
not associated to an specific Product. When upgrading from 1.5.x to
1.6, it's not possible for the installer to know to which Product
relates ogni test plan, then Product ID is set to 0. This results in
a situation where you find you can't see any of your old Test Plans
!!!. To solve this problem the following configuration parameter was
added:


$g_show_tp_without_prodid=TRUE;

You can also via DB administration assign this relation manual and
use this feature for data from previous version.


 5.4.4 Filtering Test Plans by Product


As stated before the default
behavour for version 1.6, is to filter Test Plan by Product. Using
the following configuration parameter:
$g_ui_show_check_filter_tp_by_product.


You can:


Allow the user, through the user
interface , to enable/disable test plan filter by Product. A check
box is displayed over the test plan combo box.
($g_ui_show_check_filter_tp_by_product =
TRUE)


Force Test Plan filtering, without any
user possibility to change it.


$g_ui_show_check_filter_tp_by_product
= FALSE;


 5.4.5 Keyword Management


If you don't want to create multiple
times the same keyword for the same Product:


$g_allow_duplicate_keywords=FALSE;


 5.4.6 Date and Time Localization


For every defined locale, you can
set the format for date and time presentation. This is configured
using the following associative arrays: $g_locales_date_format
and $g_locales_timestamp_format.


At time of this writting the
configuration is :


$g_locales_date_format
= array(


	'en_GB' =>
"%d/%m/%Y", 'it_IT' => "%d/%m/%Y", 



	'es_AR' =>
"%d/%m/%Y", 'es_ES' => "%d/%m/%Y", 



	'de_DE' =>
"%d.%m.%Y", 'fr_FR' => "%d/%m/%Y", 



	'pt_BR' =>
"%d/%m/%Y" ); 



$g_locales_timestamp_format
= array(


	'en_GB' =>
"%d/%m/%Y %H:%M:%S", 



	'it_IT' =>
"%d/%m/%Y %H:%M:%S", 



	'es_AR' =>
"%d/%m/%Y %H:%M:%S", 



	'es_ES' =>
"%d/%m/%Y %H:%M:%S", 



	'de_DE' =>
"%d.%m.%Y %H:%M:%S", 



	'fr_FR' =>
"%d/%m/%Y %H:%M:%S", 



	'pt_BR' =>
"%d/%m/%Y %H:%M:%S", );


If there is no entry in the
previous arrays, the value of the following configuration variables
will be used: $g_date_format
and $g_timestamp_format.


Example of
formatting:


$g_date_format
="%d/%m/%Y"; 



$g_timestamp_format =
"%d/%m/%Y %H:%M:%S";


 5.4.7 Test Case Generation from Requirement


One of the unique features of Test Link
is Requirement Management. After creating the Software Requirements
Specifications (SRS), and populating it with requirements you can
choose to create test cases for every requirement (Component and
Category are also created).


Using the configuration object:
$g_req_cfg,
you can configure :



For the Category name you can configure
the following options:



 5.4.8 Using Your own Smarty templates (GUI
definition)


If You want to test a different solution
for the user interface, you can develop your own Smarty Templates. At
the time of this writting we have defined the following configuration
array:


$g_tpl


with the following entries:



This allows you to create templates with
different names that the original Testlink, without the risk to
overwrite them, during the next upgrade.


Important: Not all TestLink pages are
ready for this kind of configuration.


The standard configuration:


$g_tpl['tcView'] =
"tcView.tpl"; 



$g_tpl['tcSearchView']
= "tcSearchView.tpl"; 



$g_tpl['tcEdit'] =
"tcEdit.tpl"; 



$g_tpl['tcNew'] =
"tcNew.tpl"; 



$g_tpl['execSetResults']
= "execSetResults.tpl"; 



 6 FAQ


There are listed often problems. Please,
check also TestLink forum.















Revision
History:



	
	
	
	
	
		

			
				
#

					
			
				
Description

					
			
				
Date

					
			
				
Author

					
		

	
	
		

			
				
1.0

					
			
				
Initial creation of the document in
				DocXML

					
			
				
2005/03/12

					
			
				
A. Morsing

					
		

		

			
				
1.1

					
			
				
Corrected title, updated structure
				and added new sections.

					
			
				
2005/04/12

					
			
				
M. Havlat 
				

					
		

		

			
				
1.2

					
			
				
Added some words for MySQL 4.1,
				UTF8 support

					
			
				
2005/06/27

					
			
				
A. Morsing

					
		

		

			
				
1.3

					
			
				
Updated automatic installation part

					
			
				
2005/09/12

					
			
				
F. Mancardi

					
		

		

			
				
1.4

					
			
				
Updated for TL 1.6.; added
				configuration parameters; restructured (created pre-installation
				steps section); corrected layout; added phpMyAdmin steps
				description

					
			
				
2005/09/13

					
			
				
M. Havlat

					
		

		

			
				
2.0

					
			
				
Converted to OO2 format; added DB Charset
				update explanation from Kevin

					
			
				
2005/12/04

					
			
				
M. Havlat

					
		

		

			
				
2.1

					
			
				
Corrected layout for export to HTML and PDF

					
			
				
2005/12/11

					
			
				
M. Havlat

					
		

		

			
				
2.2

					
			
				
Some small changes

					
			
				
2005/12/17

					
			
				
A. Morsing

					
		

		

			
				
2.3

					
			
				
Minor layout and grammar update

					
			
				
2006/02/14

					
			
				
M. Havlat