Installing Bugzilla Test Runner v 0.7

This chapter describes the installation process of the Bugzilla Test Runner (BTR). In short, you need to install a couple of Perl packages and run an installation script.

An usual source of installation problems comes from the fact that BTR needs to modify a number of Bugzilla's original files. Files are modified automatically using the UNIX patch tool. Patch does a good job figuring out the lines that need to be modified, but if your Bugzilla installation is heavily customized, patch will fail very likely. Another reason for patch to fail is that you might try to install BTR on a Bugzilla whose version is not yet supported by BTR. BTR team tries to keep up with Bugzilla versions as they are released, but usually we lag behind and a new Bugzilla is released before the BTR patch is ready and tested for that particular version. Please, check the list of supported Bugzilla versions before attempting an installation.

In case patch fails, please check the patch issues section for more information.

Before installing BTR, first backup your existing Bugzilla installation. Backup its database and every file inside your Bugzilla directory.

2.1 Requirements.

1. Bugzilla 2.18 or higher.
2. MySQL database.
3. HTML::Parser and Text::Diff Perl modules.

Bugzilla Test Runner, as its name suggests, requires Bugzilla installed and running. No excuses, don't even dare to install BTR before you have tested that your Bugzilla is up and running fine.

Currently, BTR can be run only on MySQL database. It uses MySQL-specific features, which prevent it from working with other SQL databases. Bugzilla aims toward compatibility with other RDBMS and BTR will probably follow. For now, the only choice is MySQL.

BTR installation procedure is now tested on Windows platforms. Mind that the Windows install is very recent and hasn't been around for as long as the Linux version.

2.2 Fast-lane installation instructions.

These steps should work for most installations. There are separated but equivalent procedures for Linux and Windows:

2.2.1 Linux.

• Back up the content of your Bugzilla directory and the Bugzilla database.
  
  
• Install required modules from CPAN:
  
  perl -MCPAN -e 'install "Text::Diff"'
  perl -MCPAN -e 'install "HTML::Parser"'
  
  
• At the command shell, go to your Bugzilla directory. Copy there the BTR tar distribution file you downloaded. This file can be deleted after the installation is completed.
  
  
• Uncompress there the BTR tar file:
  
  tar xzvf testrunner-0.7.tar.gz
  
  
• Run the installation script:
  
  ./tr_install.pl
  
  This script tries to figure out the right patch needed according to the Bugzilla version detected. In case of problems it stops the installation and offers some diagnosis.
  
  Notice that the script must be executed from Bugzilla directory.
  
  
• Assign permissions. Initially, no Bugzilla users other than members of the admin group have permissions to edit test cases or manage test plans. Go to the 'users' page at Bugzilla and grant access to the 'edittestcases' and 'managetestplans' groups as needed.

2.2.2 Windows.

• Back up the content of your Bugzilla directory and the Bugzilla database.
  
  
• Install required modules. From the command prompt run:
  
  ppm install Text::Diff
  ppm install HTML::Parser
  
  
• Unzip the BTR zip distribution file you downloaded to your Bugzilla folder. Use the tool of your preference for this task.
  
  
• Add the bin folder of your MySql installation to your path. The install script you are going to run on the next step won't work if it cannot find mysql.exe.
  
  
• From the command prompt, go to your Bugzilla folder and run the installation script:
  
  perl tr_install.pl
  
  This script tries to figure out the right patch needed according to the Bugzilla version detected. In case of problems it stops the installation and offers some diagnosis.
  
  Notice that the script must be executed from Bugzilla folder.
  
  
• Assign permissions. Initially, no Bugzilla users other than members of the admin group have permissions to edit test cases or manage test plans. Go to the 'users' page at Bugzilla and grant access to the 'edittestcases' and 'managetestplans' groups as needed.

2.3 Detailed installation instructions.

This version assumes you are running Linux. Windows users, please, check the section Windows notes for specific details on your platform.

Before touching anything... back up the content of your Bugzilla directory and database.

2.3.1 Installing required PERL modules.

From the command shell, run:

perl -MCPAN -e 'install "Text::Diff"'

This installs the 'Diff' module. Bugzilla runs diff from the shell. (Possibly, future versions of BTR may do the same)

BTR uses HTML::Parser for importing test cases and test plan documents from HTML documents. If you don't need this functionality, you won't need this module and you can skip to the next section. Else, run this from the command shell:

perl -MCPAN -e 'install "HTML::Parser"'

(originally used HTML::Parser v.3.23)

2.3.2 Setting up the BTR files.

To install BTR, copy the BTR tar-ball to the directory where your copy of Bugzilla is installed. Then, unpack the file:

tar xzvf testrunner-0.7.tar.gz

This should create a number of files whose name starts with the "tr_" prefix, including the tr_testrunner directory.

2.3.3 Customizing the BTR database.

Don't continue if you haven't backed up your Bugzilla database.

BTR uses the Bugzilla original database. It uses some of the standard Bugzilla tables and defines some new ones.

BTR database needs are defined in the create_db_mysql.sql script, inside the tr_testrunner directory. Soon, you will use this SQL script to recreate all the BTR database elements. Before you run the install script, you can edit this file to customize your installation.

Among other things, the script defines the test types that you will use. The following test types are currently defined:

• unit
• integration
• system
• acceptance

If you don't like them, or want to define your own types, you need to change the SQL script. In the future, BTR will have an easier way to define test plan types. Right now, you must manually edit the SQL script with your favorite text editor. Find insert into test_plan_types ... statements and change, remove, or add new types to suit your needs.

You can customize the templates for test case functional groups. Test cases in BTR are grouped into functional groups. This gives a test plan some structure and helps organize it.

You can define any test group in Test Runner. The templates are a shortcut to frequently used groups.

To change or add test case functional groups, find insert into group_templates statement and add your templates there. You can also do this later, manually editing the contents of the group_templates table using your favorite SQL tool.

2.3.4 Running the installation script.

On the shell command, cd to your Bugzilla directory and run:

./tr_install

from the command line.

A summary of what this script does:

• Checks that you are really calling it from Bugzilla directory.
• Checks if Bugzilla's files are already patched. In case they are not:
• If no patch file was specified at the command line, tries to figure out the right patch to use.
• Checks whether or not patch will run successfully using the --dry-run option.
• If check says it's OK, applies the patch.
• Restores original permissions on the patched files.
• Sets up default (minimal) permissions on BTR's files.
• Checks the database, creates BTR tables if needed, using the create_db.sql script in the tr_testrunner directory.
• Updates BTR tables as needed.
• Add groups 'managetestplans' and 'edittestcases' to Bugzilla if needed.
• Copies BTR's templates to Bugzilla templates directory.
• Runs Bugzilla's checksetup.pl script. This script is used to compile BTR's templates.

2.3.5 Patch issues.

Modifying original Bugzilla's files is a delicate process and error prone. Luckily on Bugzilla v 2.20 patching is really limited thanks to the introduction of UI hooks. Eventually, at some point, patching will be completely eliminated, but while we get there, BTR needs to rely on the patch tool and a patch file specific to the Bugzilla version you are running.

If you get the infamous *** Patching of Bugzilla's files failed. message when running the install script, don't give up your hopes yet. Next are some notes that may help you:

• In case you modified some of the original Bugzilla's files that BTR needs to modify itself, patch might fail to guess the lines where the modifications are applied. In this case, it is fair to assume that you have some pretty good skills and therefore you should be able to apply the patch manually, provided you have the patience. It isn't as bad as it sounds though.
  
  
  • Go to the tr_testrunner directory. There you will find a number of patch files, each for a specific Bugzilla version. The naming of patches is patch-<Bugzilla version number>.
  • Open the patch file right for your Bugzilla using any text editor. You will probably recognize it as a standard diff file. Those - and + signs at the left of a line are there to indicate what needs to be removed or added, respectively. For each file listed in the file, modify it using your best guest. We do this all the time when there is a new Bugzilla release coming. It takes some time but isn't rocket science.
    
    
  After you are done patching, you need to run the install script, but tell it not to do any patching (you just did it, right?). Use the following command line:
  
  ./tr_install.pl -nopatch
  
  The install script doesn't know that the patch was applied successfully because it cannot find the file tr_testrunner/tr_patch_successfull. The content of this file is a line of text with the BTR version number, 0.7 in this case.
  
  
• You tried to install BTR on a Bugzilla version that is not supported. Although you'd probably prefer to wait for an oficial patch to be released, if you have the time and are craving to get BTR working, you can try a manual patch. Check out the previous point. Instead of a full manual patch you might like to apply the patch, let it modify as many files as it can, and do a manual patch on the rest. To do this, use the following command line:
  
  patch -bp 1 -i tr_testrunner/<patch file>
  
  
• You got a patch file delivered individually from the oficial BTR site. Run the install script instructing it to use that file:
  
  ./tr_install.pl <patch file>
  
  
• For whatever the reason, the install script fails to determine which patch file needs to be applied. Instruct it to use a particular patch file. Similarly to the previous case, run:
  
  ./tr_install.pl tr_testrunner/<patch file>

Mind also that in this version of BTR, the install script attempts first a "dry run" of the patch to check whether or not it works. If there is some kind of problem the installation aborts and no file gets modified.

Hope these notes helped you. In case they didn't, please review every step, check the BTR's forum, or file a request for support at BTR's sourceforge site.

2.3.6 Granting access to users.

Initially none of the Bugzilla's users other than members of the admin group have permission to edit test cases or manage test plans. Go to the 'users' page on Bugzilla and grant access to the 'edittestcases' and 'managetestplans' groups as needed.

2.4 Upgrading from version 0.6.2.

2.4.1 Linux.

• Back up the contents of your Bugzilla directory and the Bugzilla database. Back up BTR's files: every file in your Bugzilla directory whose name starts with tr_, including the tr_testrunner directory.
  
  
• Copy the BTR 0.7 distribution file to your Bugzilla directory.
  
  
• At the command shell, cd to your Bugzilla directory and uncompress there the distribution file:
  
  tar xzvf testrunner-0.7.tar.gz
  
  
• Run the installation script:
  
  ./tr_install.pl
  
  Notice that the script is executed from Bugzilla directory.

2.4.2 Windows.

• Back up the contents of your Bugzilla folder and the Bugzilla database. Back up BTR's files: every file in your Bugzilla folder whose name starts with tr_, including the tr_testrunner folder.
  
  
• Unzip the BTR 0.7 distribution file to your Bugzilla folder using your favorite zip tool.
  
  
• At the command prompt, cd to your Bugzilla folder and run the install script:
  
  perl tr_install.pl
  
  Notice that the script is executed from Bugzilla folder.

If you find this does not work correctly for you, please take time to review every step, file a bug to BTR, or contact the BTR maintainers.

2.5 Windows notes.

There isn't yet an install wizard as you are probably expecting, but installing BTR now on Windows should be much easier than it was with previous versions (it really was a challenge). The installation procedure has been tested to work on Windows (at least XP). Mind however that BTR's support of Windows platforms is relatively new and BTR as well as Bugzilla were originally designed with Linux in mind.

Please mind that before attempting to install BTR, Bugzilla must be successfully installed in your Windows box. Therefore, PERL, MySQL, and a mean to send emails must be working fine as well. Please, to save your time, double-check that Bugzilla is working in your machine before asking for help regarding an installation problem.

There are specific instructions for Windows platforms at the fast-lane installation instructions and upgrading from version 0.6.2 sections.

For the detailed installation instructions section, these are some notes with details for Windows platforms:

• Similarly to the Bugzilla case, PERL packages are installed on Windows using the ppm tool from the command prompt:
  
  ppm install Text::Diff
  ppm install HTML::Parser
  
  
• BTR's distribution file for Windows platforms is a zip file. Use your favorite unzip tool to extract files to your Bugzilla folder.
  
  
• For your convenience, text lines on Windows distribution files are terminated following the Windows way (\r\n).
  
  
• You need to have the path to your mysql.exe file in your PATH environment variable. The install script calls it and it will fail if it cannot be found. This file is in the bin folder of your MySQL installation. Add the path <MySQL install folder>\bin to your PATH if it isn't already there.
  
  
• To call the install script, open a command prompt, use cd to move to your Bugzilla folder and from there, call:
  
  perl tr_install.pl
  
  
• The patch command-line tool is distributed for your convenience with your BTR distribution for Windows platforms. Patch is part of the GNU utilities for Win32. It's located in the tr_testrunner\tools folder and is used by the install script.

2.6 Testing the installation.

Go to your Bugzilla's home page. Look for a number of links, at the bottom of the page, following the text 'Test Runner:'. Click on the 'manage' link. If this leads to a page asking you to select a product from a list of products you defined within Bugzilla, then BTR is working. Congratulations!