TestLink Developer's Guide

Martin Havlt, Andreas Morsing and Francisco Mancardi

Copyright 2005 - 2008 TestLink Development Community Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 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.

Table of Contents
1. General.....................................................................................................................................................1 1.1. Purpose.............................................................................................................................................1 1.2. TestLink Community goals..............................................................................................................1 2. Project Processes......................................................................................................................................1 2.1. Bug tracking policy..........................................................................................................................1 2.2. Team organization............................................................................................................................1 2.3. Contributions review........................................................................................................................1 2.4. CVS Branching................................................................................................................................1 2.5. Release policy..................................................................................................................................1 2.5.1. Types of Builds.........................................................................................................................1 2.5.2. Build Process............................................................................................................................1 3. Coding conventions.................................................................................................................................1 3.1. Introduction......................................................................................................................................1 3.2. Coding rules.....................................................................................................................................1 3.2.1. Code formatting........................................................................................................................1 3.2.2. Functions..................................................................................................................................1 3.2.3. Database access........................................................................................................................1 3.3. File naming conventions..................................................................................................................1 3.4. Comments.........................................................................................................................................1 3.4.1. Standard file Header.................................................................................................................1 3.4.2. Standard function header..........................................................................................................1 3.4.3. Code attributes..........................................................................................................................1 3.5. File structure.....................................................................................................................................1 3.5.1. CVS structure...........................................................................................................................1 3.6. CVS..................................................................................................................................................1 1. Architecture...............................................................................................................................................1 1. GUI - Smarty templates........................................................................................................................1 3.7. Conventions......................................................................................................................................1 3.7.1. Filename...................................................................................................................................1 3.7.2. Header.......................................................................................................................................1 3.8. Common practices............................................................................................................................1 3.8.1. HTML page header...................................................................................................................1 3.8.2. Tables.......................................................................................................................................1 3.8.3. Help reference..........................................................................................................................1 3.8.4. Buttons......................................................................................................................................1 3.8.5. Action results............................................................................................................................1 3.8.6. Combobox Menu......................................................................................................................1 3.9. Debugging........................................................................................................................................1 3.10. Logs................................................................................................................................................1 3.11. Timing............................................................................................................................................1

3.12. Smarty variables parsing................................................................................................................1 4. How-to.....................................................................................................................................................1 4.1. How to write interface for Bug Tracking systems...........................................................................1 4.1.1. Name the interface....................................................................................................................1 4.1.2. Create the config file................................................................................................................1 4.1.3. Create the interface file............................................................................................................1 4.1.4. Setup your bugtracking interface..............................................................................................1 4.1.5. Testing the interface.................................................................................................................1 4.1.6. Some words..............................................................................................................................1 5. Documentation.........................................................................................................................................1 5.1. Documents........................................................................................................................................1 5.1.1. Developers documentation.......................................................................................................1 5.1.2. User documentation..................................................................................................................1 5.1.3. Source texts..............................................................................................................................1 6. Third party components...........................................................................................................................1 6.1. ADOdb.............................................................................................................................................1 6.2. phplayersmenu.................................................................................................................................1 6.3. FCK Editor.......................................................................................................................................1 6.4. Smarty templates..............................................................................................................................1

1.
1.1.

General
Purpose

This document defines standards, practices and procedures for development, testing and publishing.

1.2.

TestLink Community goals

Testlink developers and supporters are open community. All work on project should be done with respect to other members. The main requirements are: maintenability, support for contribution by users and simplicity. It allow us to save time nad go ahead.

2.
2.1.

Project Processes
Bug tracking policy

1. Each bug or new feature request should have the next phases:

New (issue is reported with this initial status) Feedback (issue is not clear) reporter is requested to deliver clarification. Acknowledged reporter is informed, that we accepted his report. Confirmed issue was analysed and requires an action. Developer could assign it to yourself or an appropriate other developer. However anybody could overtake it to work. Assigned developer works on the issue. Solved work is done. Closed RC or official release was released with solved the issue.

2. New features request must have severity Feature request. 3. BTS doesn't allow anonymous access. 4. Each main version has own project within BTS (for example 1.6, 1.7).

2.2.

Team organization

Testlink community owns all rights of the project. Roles within the team: 1. Team leaders (define goals, coordinate significant changes in project, plan a release content, approve members) The current core team: Francisco Mancardi, Martin Havlt and Andreas Morsing 2. Developers (has access to CVS; implement new functionality and do bug fixing) 3. Contributors (hasn't access to CVS; the code should be reviewed before add to repository). They contribute via tracker attachments. 4. Build manager (responsible for builds of course) 5. Infrastructure support (BTS, homepage, forum, demo) 6. Testers (coordined regular testing before announce of release, development of test automation)

2.3.

Contributions review

Mentor could be assigned to a new contributor. Mentor helps acquaint you with TestLink's dev group processes, tools, and direction. Somebody who will make sure your contributions are aligned with the overall goals of the core team. Rule: one contributor - one mentor. So contributor knows who can contact at the first. Contributor of course (could) communicate with all. But mentor keep in mind, that his responsibility is to to answer questions or suggestion. Mentor suggest/agree/disagree contributor take an exact work.

Mentor primarily review his work. Mentor say ok, this guy can obtain CVS access. Mentor ask if contributor is longer time silent.

2.4.

CVS Branching

New features development is executed on main branch HEAD only. For each official maintenance release 1.x is created a new branch to allow bug fixing. A branch label example: branch_testlink_1_6.

All major (and higher) bug fixes should be fixed on both HEAD and the latest maintenance branch. No database changes and official development are allowed on branch, because of maintenance effort increases too much. All development of new features is acceptable on HEAD. DB changes must be discussed with DB schema owner (Francisco). Please, do all development under related number in our BTS.

2.5.
2.5.1.

Release policy
Types of Builds

For TestLink there are mainly three phases with the next release categories: beta, release candidate, official major release and hot-fix release. The main policy is release often, so TestLink gets early feedback by users. One release per months is nice plan. Beta release - Main planned updates are done, when a first Beta is released. Minor enhancement is still ok. Users are welcome to report problems to tracker. For example: TestLink 1.8 Beta1. Release Candidate (RC) - focus is on bug fixing, exceptional minor enhancement is acceptable (because real world differes from ideal). For example: TestLink 1.8 RC2. Official major release is successfull RC. A hot-fix branch is created in repository. For example: TestLink 1.8.0. Hot-fixes - Bug fixing and localization is acceptable changes only. No development is accepted. For example: TestLink 1.8.3.

2.5.2.

Build Process

This chapter describes steps requires for build process. The process should have one or more rounds with dependence on results of preliminary testing. The list of task: 1. Ask developers if some work is not open at least one day before. 2. Update README. Update CHANGELOG file with data generated by mantis. 3. Verify/update TL version in [Link]. 4. Generate pdf/html files for Installation manual and cvs:<testlink_root>/documentation Public it to homepage. 5. Tag files in CVS (E.g. # cvs tag testlink_1_6_RC1). 6. Export CVS e.g.: 7. # cvs -d:pserver:anonymous@[Link]:/cvsroot/testlink login User Guide. Upload into

8. # cvs -z3 -d:pserver:anonymous@[Link]:/cvsroot/testlink export -r testlink_1_5_1 testlink 9. Build testlink_<version>.zip and testlink_<version>.[Link] packages from tagged files. Do cvs export. 10. Load packages to SF ([Link] 11. Add new build name to Mantis. Set the curent next build as closed. Move resolved Mantis issues to status "closed". 12. Publish the information about build (include download and documentation links). release should be also announced in public sites about testing.

Official

Community email (also announce the next target release). SF news TestLink homepage news [Link] option=com_content&task=new&sectionid=1&Itemid=0, [Link] [Link]

13. Update roadmap info if required (main release). Edit [Link] option=com_content&task=view&id=6&Itemid=2.

3.

Coding conventions

This chapter describes the coding conventions which should be confirmed by each developer of TestLink.

3.1.

Coding rules

There are some rules which all developers should follow

Write your code for humans and not for computers! Don't re-invent the wheel! Take a look at already existing code at first! Initialize each variable, before using them! If you are not sure about the existence of indices within associative array, use isset to test. Avoid scripts with huge size, use functions instead (and put them into function only files) Avoid functions of huge size, use small to medium sized functions only Avoid magic numbers Avoid unnecessary comments! Don't use fixed paths for accessing files Limit your access to $_GET, $_POST, $_FILES and similiar things, to one place in your script (preferrable at the beginning)! Don't access $_GET, $_POST, $_FILES directly, use wrappers instead! Document code changes! That means, at least document your code change in the change log. You may also drop a short mail to other developers (maybe the initial author), so the documentation can be also be updated (if needed) Use TAB with a width of 4 spaces! Set error_reporting to E_ALL and set TL_LOG_LEVEL_DEFAULT to EXTENDED to get the maximum error messages while developing! Use the shortest possible meaningful names for variables and functions! Don't bloat the code with debug output, unnecessary comments, unnecessary blank lines and so on Don't ignore bad code! If it's safe to refactor it, just refactor! Don't duplicate code! No copy/paste.

3.2.

Code formatting

Always use braces and indent your code in the right way. Choose one of these styles and be consistent:
if ($showFeature == 'editTc') { // show edit test cases $treeframePath = 'lib/testcases/[Link]?feature=tcEdit';

$workframePath = 'gui/instructions/[Link]'; } OR if ($showFeature == 'editTc') { // show edit test cases $treeframePath = 'lib/testcases/[Link]?feature=tcEdit'; $workframePath = 'gui/instructions/[Link]'; }

3.3.

Functions

for the following rules we use the example below.

/** * Function verifies if login exists * @param string login * @return integer number of founded records; i.e. 1 if account exists */ function existLogin($login) { $sql = "SELECT * FROM user,rights WHERE [Link] = [Link] AND login='" . mysql_escape_string($login) . "'"; $result = mysql_query($sql); $userExists = 0; if ($result) { if ($row = mysql_fetch_row($result)) $userExists = $row; } return $userExists; }

3.3.1.

Use unambiguous return type

In every situation a function must return the same variable type. As seen in the example the function returns a number (0) or an array, which are two different types, so return null instead of 0

3.3.2.

Function header contents must be right

The information contained in the header must be coherent with the code. As you can see if the account exists the returned value is not 1, instead an array with the account data is return. This rule applies also when you change an existing function. So don't forget to update also the function header (if present and needed).

3.4.

Database access

for the following rules we use the example below.

3.4.1.

SQL keyword have to be uppercase!

To ease to reading of SQL-Statements write all SQL keyword in uppercase letters

3.4.2.

Use mysql_fetch_array whenever it's possible

TODO: redefine:To avoid index errors and simplify introducing new columns use mysql_fetch_array whenever possible.

3.5.

File naming conventions

This section describes the file naming conventions used in TestLink.

Use Camel case or all lower case as default convention for all filenames. Underscore and other special characters are not acceptable. Note that unix/linux file system differs upper and lower case. The name of a Smarty Template called/launched from a PHP page called [Link] must be [Link], i.e. the filenames without considering the extension must be identical. Php include files should be named <title>.[Link]. Configuration php files should follows <title>.[Link]. Class definition in php is indicated by filename <title>.[Link] . Separated parts of Smarty templates should be named inc_<title>.tpl .

3.6.

Comments

To allow automatic creating of code documentation the phpDocumentor syntax will be applied to all code comments Only BlockComment
/** ... */

and Line Comments

//

are allowed (# is not allowed) All comments have to be in plain english. Code should not be clustered with comments, but instead the code should be written in a readable way, so its meaning its clear and therefore it doesnt need to be commented. Only comment things where is absolutly needed and avoid useless comments like those bad examples:
//Initializing variables $pass = 0;

or

// execute SQL request $sqlTC = "SELECT id,title,summary,steps,exresult,version,keywords,"

or
$result = mysql_query($sql); //Execute query

or
//I had to write this code so that the loop before would work.. I'm sure there is a better way to do it but hell if I know how to figure it out.. if(count($testCaseArray) > 0){

These comments are quite unnecessary and useless (as they give no additional clues for the reader) and should be removed, before they bloat the code. Example for a good comment:
// Chop the trailing comma off of the end of the keywords field $myrowTC[6] = substr($myrowTC[6], 0, -1);

Here it isnt clear in the first view that there is always a trailing comma at the end of the keyword list, so its helpful to comment this intrinsic fact.

3.6.1.

Standard file Header

Each file must contain the standard file header as seen in the example below below:
/** * TestLink Open Source Project - [Link] * This script is distributed under the GNU General Public License 2 or later. * * Filename $RCSfile: [Link],v $ * * @version $Revision: 1.4 $ * @modified $Date: 2005/11/15 [Link] $ by $Author: schlundus $ * * @author <LastName, FirstName or nick> * * **/

3.6.2.

Standard function header

Each function be should be prefixed with a standard function header as seen in the example below
/** * generates data for tree menu of Test Case Suite (in Test Plan) *

* @author <LastName, FirstName> * * @param string $linkto path for generated URL * @param integer $hidetc [0: show TCs, 1: disable TCs ] * @param string $getArguments additional $_GET arguments * * @return string input string for layersmenu * * @todo * **/

This header consists of: a comment: What does this function @author tags (optional) author nick or name @param tags for each parameter the function takes @return tag describing the return value (if any) @todo tag (if applicable) describing the next development/refactorization

3.6.3.

Code attributes (unused - obsolete)

Any Code (this includes HTML, JS and PHP) may be attributed with
/// <tagname>

-tags Line Comments with

///

have a special meaning, they can be used to tag the code and ease the automatic generating of automatic reports like changelog, todo list.... At the moment there are currently four possible tags:
<change>

marking a change in the code

<fix>

a change in the code which is a bugfix

<enhancement>

a change (or a extension) of the code which is an improvement or an addition feature

<todo>

a reminder for something which has to be done with the code Each tag can have up to four attributes (if applicable) namely:

version

this describes the version to which the action was applied

id

this refers to a bug id on sourceforge

author

the initials of the author

date

date of the action (should be given in YYYY-mm-dd Example:

/// <fix version="1.5.1" date="2005-02-15" author="scs" id="5678543">corrected the uninitialized use of the variable $key</fix>

Any code change has to be at least commented by one code-tag, if the change applies to one line only the code-tag has to be applied to the line before the change. If the change modifies many different lines of a function body, the code tag has to be included in the function comment If the change modifies many different lines within the whole file, the code tag has to be included in the file header.

3.7.

File structure

The file structure of TestLink should contain all sources of information which are needed by endusers to bring TestLink to work and also all possible information for developers. The infrastructure should be strongly categorized into the user related and the developer related sources of information, so end-user can easily identify documents which aren't needed for usage. The infrastructure should contain documents, license information, sources and the website for TestLink. All items within the infrastructure must be versioned. This should be done per CVS so all items could be easily maintained and obtained. All new files should contain only alphanumeric lower-case characters.

3.7.1.

CVS directory structure

This section describes the directory structure on [Link].

Documents (modul) developers Developers Guide <major_release_vesion> (for example '1.7') User manual (obsolete) Installation manual unsorted documents related to new features docs includes obsolete www pages (for [Link]) testlink (source modul) gui (All user interface related material like templates, images, stylessheets should be

inside this directory and the appropriate subdirectories. This directory should also contains the locale specific stylesheets.)

 javascript templates themes

css images templates_c lib (All classes, function files should reside in this directory, no GUI related or standalone scripts! E.G. each scripts should contain only functions and/or classes Subdirectories as needed). functions general testcases ... install (The install (and update)scripts, install (update) information are here). sql (scripts with SQL requests needed by the installation) thirdparty (Thirdparty component; as is fckeditor, etc.) colorpicker htmlarea ... config (configuration scripts (like [Link]) should be here) locale (All localization related strings. Subdirectories are named like the appropriate locale like en_GB) en_GB de_DE ... docs User manual (exported) Installation and Configuration manual (exported) Other user documentation Examples (import files)

3.8.

CVS

This section presents some short rules regarding to CVS handling. A good rule is to have two TestLink-source directories while developing. One which holds the current CVS contents and the other one in your web servers document root for developing. So its easy to revert any developing mistakes. Applying your changes to CVS is also easy, as the only thing you have to do is diff'ing your developing directory with the CVS directory and merge your changes and commit into CVS. As you are not the only developing (-:, some rules should be applied while plaing with CVS.

Update your CVS directory before applying your changes to it! As other developers may also change things on parts you are working on, updating avoids conflicts. Don't commit anything you are working on, which isn't complete! As CVS is accessible by all most people aren't happy if they checked out something, which isn't working at all. So commit only when your changes (e.G. new feature) are working and complete. This doesn't meant that we expect only bugfree commits (-:. So don't commit your nearly 50%-ready changes, go in a two-weeks holiday and after that commit the rest. If you intend to work on a bigger feature it makes sense to communicate this to the other developers, so the amount of interferences are minimized. If you intend to work on a new feature which wasn't assigned to you, please contact the other developers, nothing is more frustrating and resource wasting when two different people

are implementing same thing in parallel.

4.

Architecture

TestLink common page consists from the next parts:

Load configuration (include [Link]) Load core functions and classes (include [Link]) Load page specific functions and <testlink_root>/lib/functions/ directory) Initiate database connection and session
testlinkInitPage($db);

classes

(include

scripts

from

Parse input variables Process the page logic Call smarty templates component (initiate, add the page specific variables and render with related template).

4.1.

Debugging / Logging

TBD: Describe Audit functionality See [Link] to set logging level and target file. Log rotation is not internally supported. Recommended user level is ERROR. Now any log messages from the levels ERROR or INFO will be recorded. DEBUG messages will be ignored. We can have as many log entries as we like. They take the form: tLog("testing level ERROR", 'ERROR'); tLog("testing level INFO", 'INFO'); tLog("testing level DEBUG"); This will add the following entries to the log: [05/Jan/27 [Link][INFO][guest] - Login ok. (Timing: 0.000763) [05/Jan/27 [Link][DEBUG][havlatm] - User id = 10, Rights = admin tLogSqlError($sql) - function specified for unsuccesful database query.

4.1.1.

Timing

Timing is available for performance optimalization. Use the next functions: tlTimingStart ($name), tlTimingStop ($name) and tlTimingCurrent ($name). The last one returns the measured time.

4.2.

Users and roles

Any user has one generic role, none or more project related roles and none or more test plan roles. Generic role is valid if no specific role is set for the current Project or the current Test plan.

4.2.1.

Rights Definitions

Keywords used for definition of role abilities.

Right
mgt_view_tc mgt_modify_tc mgt_view_key mgt_modify_key mgt_modify_product mgt_view_req mgt_modify_req cfield_view cfield_management role_management user_role_assignment mgt_view_events See audit/debug log

Description
View Test Specification (Test Suites and Test Cases) Edit Test Specification (create, modify, delete, order, move, and copy both Test Suites and Test Cases) View keywords Modify keywords Create,edit and delete Test Projects View requirements Create,edit, associate and delete requirements View defined custom fields Manage custom fields Modify existing roles and add a new ones

Table 1: Test Project related Rights

Right
testplan_execute testplan_create_build testplan_metrics testplan_planning

Description
Ability to execute Test Cases (insert Test Results) Ability to create Builds View reports and metrics Create, edit, delete Test Plans, assign test urgency, assign ownership, milestones, edit Test Case Suite

testplan_user_role_assig Assign the rights to view projects nment Table 2: Test Plan related Rights

Role
Guest Test Executor (Tester) Test Analyst

List of Rights
mgt_view_tc, mgt_view_key, tp_metrics

Permissions
Browse data only.

tp_execute,tp_metrics

Execute test only.

tp_execute, mgt_view_tc, (Senior Tester) mgt_view_req Test Designer

tp_metrics, mgt_modify_tc,

tp_create_build, Edit Test Specification, mgt_view_key, execute tests, create Build.

tp_metrics, mgt_view_tc, mgt_modify_tc, Edit Test Specification and mgt_view_key, mgt_modify_req, mgt_view_req Requirements. tp_execute, tp_create_build, tp_metrics, tp_planning, All Test Plan permissions, tp_assign_rights, mgt_view_tc, mgt_modify_tc, edit Test Specification and mgt_view_key, mgt_modify_key, mgt_view_req, execute tests. mgt_modify_req tp_execute, tp_create_build, tp_metrics, tp_planning, Everything possible. Only tp_assign_rights, mgt_view_tc, mgt_modify_tc, this role can maintain Test mgt_view_key, mgt_modify_key, mgt_view_req, Projects and users. mgt_modify_req, mgt_modify_product, mgt_users

Test Leader

Administrator

Table 3: Default Role attributes

4.2.2.

Test Plan assignment to users

There is a table with Test Plan rights (i.e. which users can see which Test Plan). This table is made up of a combined user id and project id. The main page contains code which checks to see if the logged in user has the appropriate permissions (and then shows the allowed projects). It is not recommended that this be hacked with.

5.

Graphic User Interface

TestLink has independent GUI rendering by component Smarty templates. All files (except generated documents) are expected to fulfill the XHTML 1.0 Transitional standard. A browser is instructed to not cache the pages. CSS 1.0 atttributes are prefered standard because of www client compatibility. Parameters from standard CSS 2.0 and later must be verified in both IE and Firefox before using.

5.1.

GUI - Smarty templates

This section describe common practices using of some parts of templates. See more Smarty homepage to functional description and syntax. Also using of CSS is described in this chapter.

5.1.1.

Filename standard

All Smarty Templates are stored in the directorey <tl_root>/gui/templates/. See related general chapter above for naming convention.

5.1.2.

Header standard

The simple header is used in each template. See the next example. The last line of the example informs about changes. No needs to describe changes in body of template more.
{* TestLink Open Source Project - [Link] *} {* $Id: [Link],v 1.3 2005/08/27 [Link] schlundus Exp $ *} {* Purpose: smarty template - show test set tree *} {* 20050828 - scs - added searching for tcID *}

5.1.3.

HTML page header

Html header is defined in inc_header.tpl. This template is included to each page template immidiatelly after file description. E.g. {include file="inc_head.tpl" jsTree="yes"}. The header template can have the next parameters:

$openHead="yes" - The [Link] includes a closing of html header as default. This parameter cause that header remains open for another definition e.g. javascripts call. </head> must be defined in page then. $jsValidate="yes" - includes [Link] javascript library to the html header. It includes functions for input verificiation. $jsTree="yes" - includes inc_jsTree.tpl (javascript to the html header).

Functions in testlink_library.js are everytime loaded. Included modificable parameters (via $smarty->assign()):

$pageCharset - UTF-8 is default; $css - <tl_root>/gui/css/[Link] is default for pages and tl_doc_basic.css for generated documents;

$SP_html_help_file etc.

5.2.

Tables

There are four basic types of style:

class="common" - used to view data class="simple" - used to forms (input) data class="invisible" - used where div/span formating is not sufficient class="smallGrey" - used to define options, filters in left (navigation) pane

5.3.

Help reference

Use the next example of code to show help icon in title: <h1> <img alt="{lang_get s='help'}: {lang_get s='your_string_identifier'}" class="help" src="icons/sym_question.gif" onclick="javascript:open_popup('{$helphref}[Link]');" /> {lang_get s='your_string_identifier'}: {$[Link]|escape} </h1> Use the next example of code to call help by click a string: <span class="help" onclick="javascript:open_popup('../help/[Link]#testspec');">{lang_get s='your_string_identifier'}</span>

5.4.

Buttons

Each button should be included in <div class="groupBtn">. Navigation buttons should be in a top part of a page. Input data buttons should be in a bottom part of a page. Both top and bottom button should be used if page is long (e.g. the test execution page with tens of test cases).

5.4.1.

Action feedback

The template inc_update.tpl is useful generalized template. See for more in. Styles [Link], [Link] should be also used for information about some result.

5.4.2.

Combobox Menu

Use smarty component html_options. See more into Smarty documentation. E.g. <select name="optReq"> {html_options options=$option_yes_no selected=$reqs_default} </select>

5.5.

Delete Pop up

Use a pop-up window for confirmation of delete operations. This pop-up window should be generated using EXT JS javascript library.

Illustration 1: Pop-up dialog example

Pop title will contain operation ('Delete'). Message body should contain as a minimun, following information: indication about will be done ('You are going to delete:') name of item on which user is working (for example 'Mantis release 1.2') confirmation question ('Are you sure?')

The following pieces must be present to add a pop-up window in a smarty template: [1] {lang_get s='warning_delete_testplan' var="warning_msg" } [2] {lang_get s='delete' var="del_msgbox_title" } [3] {include file="inc_head.tpl" jsValidate="yes" openHead="yes"} [4] {include file="inc_del_onclick.tpl"} [5] <script type="text/javascript"> /* All this stuff is needed for logic contained in inc_del_onclick.tpl */ var del_action=fRoot+'lib/plan/[Link]? do_action=do_delete&tplan_id='; </script> [6] <body {$body_onload}> ... [7] <img style="cursor: pointer;" alt="{lang_get s='testplan_alt_delete_tp'}" title="{lang_get s='testplan_alt_delete_tp'}" onclick="delete_confirmation({$[Link]}, '{$[Link]|escape:'javascript'}', '{$del_msgbox_title}','{$warning_msg}');" src="{$[Link].TL_THEME_IMG_DIR}/[Link]"/>

Explanation: [1] gets the appropriate message from [Link]. This message must have placeholder (%s) that will be replaced with name of item.

Example:
$TLS_warning_delete_testplan="You are going to delete: %s <br /><br /> Are you sure?";

[2] will be pop up title. [3] standard include that must have option openHead="yes". [4] include delete on click logic (javascript functions) [5] definition of callback function that will be called when user press yes button. [6] initialization for ext js [7] configuration of onclick event to call 'delete_confirmation()' javascript function.

/* function: delete_confirmation args: o_id: object id, id of object on with do_action will be done. is not a DOM id, but an specific application id. o_name: name of object, used to to give user feedback. title: pop up title msg: can contain a wildcard (%s), that will be replaced with o_name. returns: */

Illustration 2: Another pop up example with a more detailed message

5.6.

Smarty variables parsing

Smarty allows to view all assigned variable via special window.

Set line 101: var $debugging = true; in <tl_root>/third_party/smarty/[Link].

6.
6.1.

How-to
How to write interface for Bug Tracking systems

This section shortly describes how to write a new interface for bug tracking systems. A bugtracking interface mainly consists of two files: First a config file located in the cfg-directory and a interface definition file located in the lib/bugtracking-folder.

6.1.1.

Name the interface

First choose a name for your interface and make this name available in [Link] (search for TL_INTERFACE_BUGS). Just use some simple word like 'BUGZILLA' or 'MANTIS'.

6.1.2.

Create the config file

As already mentioned the config file is located in the cfg-folder. The file should contain all the configuration options for the interface like dbhost and such stuff. For the already used options just look at the [Link] file. For simplicity just name the config file similiar to the name you've chosen in 1.1 like [Link] for 'BUGZILLA'

6.1.3.

Create the interface file

The interface file is located in lib/bugtracking and should be named similiar to the name chosen in 1.1 like int_bugzilla.php for 'BUGZILLA'. Create a new interface which extends the base interface in the file int_bugtracking.php. It is important to made the interface name available via the define "BUG_INTERFACE_CLASSNAME". For an example of a bugtracking interface look at int_bugzilla.php file.
[Link] Description of the base class

The base class already contains code for some basic stuff like connecting. So mostly there is no need to overload these functions. The only function which is directly called by TestLink is the buildViewBugLink-Function which retuns a link to the bugtracking system. The base already has a default implementation of it, so maybe you dont have to change it. The default implementation calls to helpers name buildViewBugURL and getBUGStatusString. The first one build the URL for accessing the bugtracking system and the second one returns a user friendly description of the bug like BugID and such stuff. So these two ones are the first to change. Another helper which may come in handy is getBugStatus which should be overloaded to get the bug status from the bugtracking-db. this status can be used in the two other helpers. For an example how to implement these function just look at the mantis and bugzilla interfaces. For comments and the purposes of the different base interface functions just look at the int_bugtracking.php file. The code is well documented and straight forward.

6.1.4.

Setup your bugtracking interface

After you named the interface and created the two files it is necessary to add these filenames to the int_bugtracking.php file. This can be done by adding the interface to the two associative array $configFiles and $interfaceFiles and the beginning of the file.

6.1.5.

Testing the interface

If the connection to the bugtracking system is successfully done. You should test the interface. So enter a dummy bug in your bugtracking system and execute a testcase from a dummy-testplan within TestLink. You should now see a input field for entering bugs. So mark the testcase as failed and enter the id of the created dummy bug. Now switch to the reports and execute the report of failed testcases. The report should no show a link the bug. Clicking the link should open a new window which shows the bug in your bugtracking.

6.1.6.

Some words

As the bugtracking base interface is quite new, i may be that it will not always be sufficient. So feel free to contact us. I would also be very appreciated if you send your created and working interface(s) to us, so we can integrate them to our TestLink distribution.

7.

Documentation

As already stated, all TestLink related documents should be made public and available, so no information gets lost or will be concentrated on a single person. Documentation is stored in CVS under module 'documents'. Each document should have a single point of authority that means that this person is the only one person allowed to extend and change this document. This person is also responsible to collect possible changes, evaluate them and possibly put them into the document he owns. All documents should be versioned and also all versions should be available (this is done by CVS). Each document should also have a form of change (or revision) history which shortly describes the changes between two versions. Table of Revision history is at the end of documents. Please, hold it current. All documents should adhere the same format and underlying representation. To easily maintain the documents we choose to use Open Office 2. Output formats HTML and PDF are exported and published for users. Docbook system (used for TL1.5 is now obsolete). Exception are README, LICENSE and CHANGELOG. This documents are not versioned and have simple text format. Update of this files is a part of Build process. See 5. The user related documents must be updated and check-in to CVS before build (i.e. README, CHANGELOG, User manual and Installation manual). All this documents must be available with build package and manuals also on web pages.

7.1.

Developers documentation

The documents are stored in directory: <testlink_root>/documents/<version>/. This directory holds any developer related sources of information like this documents, or documents related to organization, coding standard.... List of subdirectories:

Developers Guide - This document is related to the developing process of TestLink which should be applied by all developers. It is describing the architecture, interfaces and database of TestLink. changelog - This directory holds the changes for TestLink versions. TXT type is used. Updates are generated by BTS (Mantis).

7.2.

User documentation

The documents are stored in CVS: <testlink_root>/documents/end-users/. This document contains the sources of the end-users related material. This can be the XML sources of the manual or something else.

User manual Installation and configuration manual readme stored in source root directory; updated during build process

7.3.

Source texts

The directory <testlink_root>/testlink/documents/ contains the documentaion exported fo html format (created during build process).

There are also instructions and help files available (see <testlink_root>/testlink/gui/help/). This files are localized.

8.
8.1.

Third party components

ADOdb

ADOdb component is used as abstraction layer for connection to database. The component is accessible via class database. Manual: [Link]

8.2.

phplayersmenu

The component is used for tree menu with Test Suites and Test Cases. Pages: [Link] Note: the projects seems dead

8.3.

FCK Editor

The component is used as html editor. [Link] The component has amount of nice features that are not used in default configuration. Include pictures upload. We recommend to look at the component possibilities for all users.

8.4.

Smarty templates

Smarty templates are used for GUI rendering. Manual: [Link]

#
0.1 0.5 0.6 Coding standard create

Description

Date

Authors

2005/3/13 SCS, FM, MHT

Initial compilation from the all related documentation to Developer's Guide Conversion to OO2, layout correction, doc section updated

2005/07/1 Martin Havlat 5 2005/12/1 Martin Havlat 1

0.7

0.8

Added processes, build, CVS structure, documentation 2006/01/1 Martin Havlat overview (all partly moved from obsolete architecture guide); 3 created index Layout update; updated Documentation chapter; added Team 2006/01/1 Martin Havlat organization chapter 7 Update of BTS section 2007/02/2 Martin Havlat 6 2007/09/2 Martin Havlat 7

0.9

0.10

0.11

Update styles

0.12

Major update (edit obsolete texts); Chapters: filenames, 2008/02/0 Martin Havlat releases 2 Minor update and revision for TestLink 1.8 2008/08/1 Martin Havlat 8

0.13

Table 4: Revision History