Enabling and configuring source control operations for ApTest Manager

The source control operations are defined in the file config.pl, in the root directory of your ApTest Manager installation.

Note: if the sourceControl flag in config.pl is set to 1, if any of the source control operations described below are not defined, users will be prohibited from performing operations that would require that functionality. Source control commands are executed only if the sourceControl flag is enabled.

Note: these commands are executed in the context of your web server application, so be certain that the user your web server is running as is able to perform source control operations. Also, ensure that the source control application(s) are in the path of the web server, or use absolute paths in the commands below.

1 Macros
2 Source control commands
3 Troubleshooting

1 Macros

In each of the source control configuration options, the following macros can be used:

%OLDDIR - the original directory name (when renaming)
%DIR - the directory name (new directory when creating or renaming)
%OLDFILE - the original pathname (when renaming)
%FILE - the path to the file on which to operate (or new file when creating or renaming)
%BFILE - the basename the file on which to operate (or new file when creating or renaming)
%RFILE - the suite-relative path to the file on which to operate (or new file when creating or renaming)
%SUITE - the name of the test suite
%SUITEDIR - the path to the root of the test suite in the file system
%USER - the name of the user who performed the operation

There are also macros that correspond to fields in revision history tables:

%HIST_FIELDNAME

where FIELDNAME is the name of the field in the history table. Note that the expanded macro will be limited to 512 characters, to protect against exceeding the command line limit for your system. Special characters to your system's shell will be escaped appropriately. You must enclose the field(s) in quotation marks appropriate for your server system (e.g., " for Windows, ' for UNIX).

2 Source control commands

Note: there is no source control command for removing a repository. If you delete a test suite in ApTest Manager, it will be removed from the collection of test suites that ApTest Manager presents to users. However, it will not be removed from the source control system's repository. This is a safety feature to prevent the loss of historical data. If you really want to remove a test suite from the source control repository as well, you must do it outside of ApTest Manager.

2.1 addDir

The command to add a directory to the repository. For example:

$addDir = q(cvs add %DIR; cvs commit -m 'commit from ApTest Manager user %USER' %DIR);

2.2 addDirR

The command to add a directory and its contents to the repository. If this is defined, then only one source control operation per folder add will be performed. Without it, ApTest Manager uses addFile and addDir to emulate this behavior.

2.3 addFile

The command to execute to add a file to the repository. Used when creating new test cases. For example:

$addFile = q(cvs add %FILE; $checkin);

2.4 checkin

The command to execute to check a file into the source tree. In this command, the string %FILE represents the file to check in. For example:

$checkin = q(cvs commit -m 'commit from ApTest Manager user %USER' -f %FILE);

2.5 edit

The command to execute to check a file out of the source tree for editing. For example:

$edit = q(cvs edit %FILE);

In this command, the string %FILE represents the file to check out. If your source code control system does not require "checkout" operations, you can leave this as q()

2.6 newRepository

The command to execute to create a new instance in the repository. This is used when creating a new test suite. For example:

$newRepository = q(cd %SUITEDIR; \
cvs import -m 'initial version' %SUITE.ts aptest r1; \
cd ..; rm -rf %SUITE.ts; cvs checkout %SUITE.ts);

2.7 removeFile

The command to remove a file from the repository. For example:

$removeFile = q(cvs remove -f %FILE, $checkin);

2.8 removeDir

The command to remove a directory from the repository. This command is not expected to remove the files inside the folder - the removeFile operation will be used to do that.

Note: CVS does not support removing directories.

2.9 removeDirR

The command to recursively remove a directory and the files and directories within that directory. If this is defined, then only one source control operation per folder remove will be performed. Without it, ApTest Manager uses removeFile and removeDir to emulate this behavior.

2.10 renameFile

The command to execute to rename a file in the repository. For example:

$renameFile = q(cp %OLDFILE %FILE; \
cvs remove -f %OLDFILE; \
cvs commit -m "ApTest Manager removing file by %USER" %OLDFILE; \
cvs add %FILE; \
cvs commit -m 'commit from ApTest Manager by %USER' -f %FILE);

2.11 renameDir

The command to execute to rename a directory in the repository.

Note: CVS does not support renaming folders or files. renameFile can be emulated, but renameFolder is much harder to emulate.

2.12 update

The command to execute to ensure that files are synchronized with the repository. This command is only used by a test suite manager within the test suite management menu when source control is enabled.

$update = q(cvs update -d);

3 Troubleshooting

Since source control integration in ApTest Manager is a very flexible feature, it is possible that you will run into trouble crafting commands that work seamlessly with your organization's revision control tool. The following are some hints:

Always try the commands "by hand" first. ApTest Manager is going to execute these commands via your server operating system's default command shell, so try it that way.
Remember that ApTest Manager is running as a specific user on your server system - the web server user. So test the commands as that "user" to ensure that user has appropriate privilege.
Set the ApTest Manager debugging level to 5 in the config.pl file:
```
$debug = 5;
```
The debugging information about source control operations will be added to the file data/syslog.txt along with lots of other information about what is happening in ApTest Manager. Source control operations specifically will have the string Suite::_sourceop toward the beginning of each line, so you can easily monitor just those operations (on UNIX systems, anyway) using a command like:
```
tail -f data/syslog.txt | grep "Suite::_sourceop"
```
ApTest Manager has no way to know if your source control operations succeed or fail. The output from the source operation will be captured in the log file. If you think that things are not working, the output from your operations should tell you quite a lot. In particular it will tell you 1) the command that was executed, 2) the exit status of the command, and 3) any output the command sent to standard output / standard error.

Table of Contents