2002-10-03 20:41:23 +00:00
|
|
|
<title>Testing BOINC</title>
|
2002-08-20 23:54:17 +00:00
|
|
|
<body bgcolor=ffffff>
|
2002-10-03 20:41:23 +00:00
|
|
|
<h2>Testing BOINC</h2>
|
2002-10-03 18:33:46 +00:00
|
|
|
|
2002-10-03 20:41:23 +00:00
|
|
|
<h3>1) PHP-based testing framework</h3>
|
|
|
|
|
|
|
|
|
|
doc/test.php is a library of PHP classes that make it easy to
|
|
|
|
|
write "test scripts" that perform end-to-end tests of BOINC.
|
|
|
|
|
|
|
|
|
|
<h4>1.1) Goals of the testing framework</h4>
|
|
|
|
|
|
|
|
|
|
The goal of the framework is to support automated testing of BOINC itself,
|
|
|
|
|
and of BOINC applications.
|
|
|
|
|
Each test is performed by a PHP script that initializes
|
|
|
|
|
the system to a deterministic state, executes the system,
|
|
|
|
|
detects termination, and returns success or failure depending
|
|
|
|
|
on the final state.
|
|
|
|
|
<p>
|
|
|
|
|
Many BOINC features involve multiple projects and/or multiple hosts.
|
|
|
|
|
It would be prohibitively complex to do automated testing
|
|
|
|
|
on multiple physical hosts.
|
|
|
|
|
Fortunately the BOINC architecture makes it possible for
|
|
|
|
|
multiple projects and (virtual) hosts to reside on a single physical host.
|
|
|
|
|
So the testing framework uses this approach.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
The framework lets you write scripts with any of the following attributes:
|
|
|
|
|
<ul>
|
|
|
|
|
<li> Multiple projects
|
|
|
|
|
<li> Multiple applications per project
|
|
|
|
|
<li> Multiple participants per project
|
|
|
|
|
<li> Multiple hosts, with arbitrary enrollment in projects
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h4>1.2) Directory structure</h4>
|
|
|
|
|
|
|
|
|
|
Each project has various files that must be kept separate.
|
|
|
|
|
You must designate a "BOINC projects" directory on your test host.
|
|
|
|
|
The framework will create subdirectories as follows:
|
|
|
|
|
<pre>
|
|
|
|
|
boinc_projects/
|
|
|
|
|
proj1/
|
|
|
|
|
cgi/
|
|
|
|
|
download/
|
|
|
|
|
html_ops/
|
|
|
|
|
html_user/
|
|
|
|
|
keys/
|
|
|
|
|
upload/
|
|
|
|
|
proj2/
|
|
|
|
|
...
|
|
|
|
|
</pre>
|
|
|
|
|
where proj1, proj2 etc. are the names of the projects in your scripts.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Similarly, each virtual host has various files that must be kept separate.
|
|
|
|
|
You must designate a "BOINC hosts" directory on your test host.
|
|
|
|
|
The framework will create subdirectories as follows:
|
|
|
|
|
<pre>
|
|
|
|
|
boinc_hosts/
|
|
|
|
|
host1/
|
|
|
|
|
projects/
|
|
|
|
|
slots/
|
|
|
|
|
client_state.xml
|
|
|
|
|
log_flags.xml
|
|
|
|
|
host2/
|
|
|
|
|
...
|
|
|
|
|
</pre>
|
|
|
|
|
where host1, host2 etc. are the names of the hosts in your scripts.
|
|
|
|
|
|
|
|
|
|
<h4>1.3) Classes</h4>
|
|
|
|
|
|
|
|
|
|
The framework provides the following classes
|
|
|
|
|
<pre>
|
|
|
|
|
class Project { // represents a project
|
|
|
|
|
var $name; // defaults to "test"; override if needed
|
|
|
|
|
function add_user($user); // add a User to project's DB
|
|
|
|
|
function add_app($app); // add an application
|
|
|
|
|
function add_app_version($app_version); // add an app version
|
|
|
|
|
function install(); // set up directories and DB
|
|
|
|
|
function start(); // start feeder
|
|
|
|
|
function stop(); // stop feeder
|
|
|
|
|
function check_results_done(); // verify that all results are in state DONE
|
|
|
|
|
function compare_file($out, $correct); // verify that a result file
|
|
|
|
|
// matches a known-correct file
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
class User { // represents an account on a project
|
|
|
|
|
var $name; // override if needed
|
|
|
|
|
var $email_addr;
|
|
|
|
|
var $authenticator;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
class Host { // represents a (virtual) host
|
|
|
|
|
function Host($user);
|
|
|
|
|
function add_project($project);
|
|
|
|
|
function install();
|
|
|
|
|
function run($flags);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
class App { // represents an application
|
|
|
|
|
function App($name);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
class App_Version { // represents an application version
|
|
|
|
|
var $version; // defaults to 1
|
|
|
|
|
var $exec_name; // name of executable; default to app name
|
|
|
|
|
function App_Version($app);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
class Work { // represents a workunit and some results
|
|
|
|
|
var $wu_template; // name of workunit template file
|
|
|
|
|
var $result_template; // name of result template file
|
|
|
|
|
var $nresults; // number of results for this WU
|
|
|
|
|
var $input_files; // array of input file names
|
|
|
|
|
function Work($project, $app);
|
|
|
|
|
function install(); // install in DB and directories
|
|
|
|
|
}
|
|
|
|
|
</pre>
|
|
|
|
|
A test script instantiates one or more instances of
|
|
|
|
|
these classes, links them as needed,
|
|
|
|
|
installs them, starts the projects, runs the hosts.
|
|
|
|
|
It then checks the final state
|
|
|
|
|
(typically, that results are done and result files are correct).
|
|
|
|
|
|
|
|
|
|
<h4>1.4) Environment vars</h4>
|
|
|
|
|
|
|
|
|
|
Before using the test framework,
|
|
|
|
|
you must define the following environment variables
|
|
|
|
|
(example values are given - you must supply your own):
|
2002-10-03 18:33:46 +00:00
|
|
|
<pre>
|
|
|
|
|
setenv BOINC_PROJECTS_DIR /home/david/boinc_projects
|
2002-10-03 20:41:23 +00:00
|
|
|
# BOINC projects directory
|
2002-10-03 18:33:46 +00:00
|
|
|
setenv BOINC_HOSTS_DIR /home/david/boinc_hosts
|
2002-10-03 20:41:23 +00:00
|
|
|
# BOINC hosts directory
|
2002-10-03 18:33:46 +00:00
|
|
|
setenv BOINC_USER_NAME david
|
2002-10-03 20:41:23 +00:00
|
|
|
# prepended to web error log entries
|
2002-10-03 18:33:46 +00:00
|
|
|
setenv BOINC_SRC_DIR /home/david/boinc_cvs/boinc
|
2002-10-03 20:41:23 +00:00
|
|
|
# BOINC source directory
|
2002-10-03 18:33:46 +00:00
|
|
|
setenv BOINC_CGI_DIR /home/david/cgi-bin
|
2002-10-03 20:41:23 +00:00
|
|
|
# path of a CGI directory
|
2002-10-03 18:33:46 +00:00
|
|
|
setenv BOINC_CGI_URL http://localhost/cgi-bin
|
2002-10-03 20:41:23 +00:00
|
|
|
# URL of that directory
|
2002-10-03 18:33:46 +00:00
|
|
|
setenv BOINC_HTML_DIR /home/david/html
|
2002-10-03 20:41:23 +00:00
|
|
|
# path of a web-page directory
|
2002-10-03 18:33:46 +00:00
|
|
|
setenv BOINC_HTML_URL http://localhost
|
2002-10-03 20:41:23 +00:00
|
|
|
# URL of that directory
|
2002-10-03 18:33:46 +00:00
|
|
|
setenv BOINC_KEY_DIR /home/david/boinc_keys
|
2002-10-03 20:41:23 +00:00
|
|
|
# path of some pre-generated security keys
|
2002-10-03 18:33:46 +00:00
|
|
|
setenv BOINC_PLATFORM i686-pc-linux-gnu
|
2002-10-03 20:41:23 +00:00
|
|
|
# platform name of this machine
|
2002-10-03 18:33:46 +00:00
|
|
|
</pre>
|
2002-10-03 20:41:23 +00:00
|
|
|
<h4>1.5) Example script</h4>
|
|
|
|
|
|
|
|
|
|
The following script (test/test_uc.php)
|
|
|
|
|
illustrates the use of the testing framework.
|
|
|
|
|
<pre>
|
|
|
|
|
#! /usr/local/bin/php
|
|
|
|
|
<?php
|
|
|
|
|
include_once("test.inc");
|
|
|
|
|
|
|
|
|
|
$project = new Project;
|
|
|
|
|
$user = new User();
|
|
|
|
|
$host = new Host($user);
|
|
|
|
|
$app = new App("upper_case");
|
|
|
|
|
$app_version = new App_Version($app);
|
|
|
|
|
|
|
|
|
|
$project->add_user($user);
|
|
|
|
|
$project->add_app($app);
|
|
|
|
|
$project->add_app_version($app_version);
|
|
|
|
|
$project->install(); // must install projects before adding to hosts
|
|
|
|
|
|
|
|
|
|
$host->add_project($project);
|
|
|
|
|
$host->install();
|
|
|
|
|
|
|
|
|
|
echo "adding work\n";
|
|
|
|
|
|
|
|
|
|
$work = new Work($project, $app);
|
|
|
|
|
$work->wu_template = "uc_wu";
|
|
|
|
|
$work->result_template = "uc_result";
|
|
|
|
|
$work->nresults = 2;
|
|
|
|
|
array_push($work->input_files, "input");
|
|
|
|
|
$work->install();
|
|
|
|
|
|
|
|
|
|
$project->start();
|
|
|
|
|
$host->run("-exit_when_idle");
|
|
|
|
|
$project->stop();
|
|
|
|
|
|
|
|
|
|
$project->check_results_done();
|
|
|
|
|
$project->compare_file("uc_wu_0_0", "uc_correct_output");
|
|
|
|
|
$project->compare_file("uc_wu_1_0", "uc_correct_output");
|
|
|
|
|
?>
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
<h4>1.6) Implementation</h4>
|
|
|
|
|
|
|
|
|
|
<h3>2) Test applications</h3>
|
2002-04-30 22:22:54 +00:00
|
|
|
<p>
|
2002-08-19 18:43:10 +00:00
|
|
|
The <b>apps</b> directory contains the following test applications:
|
2002-04-30 22:22:54 +00:00
|
|
|
<ul>
|
2002-08-19 18:43:10 +00:00
|
|
|
<li>
|
|
|
|
|
<b>concat</b>: concatenates its input files.
|
|
|
|
|
Input and output filenames are passed on the command line.
|
|
|
|
|
<li>
|
|
|
|
|
<b>upper_case</b>: reads from stdin, converts to upper case,
|
2002-04-30 22:22:54 +00:00
|
|
|
writes to stdout.
|
2002-08-19 18:43:10 +00:00
|
|
|
<li>
|
|
|
|
|
<b>uc_slow</b>: like upper_case, but processes only one
|
|
|
|
|
character per second.
|
|
|
|
|
Checkpoints every 5 characters. Restartable.
|
2002-04-30 22:22:54 +00:00
|
|
|
</ul>
|
2002-10-03 20:41:23 +00:00
|
|
|
|
|
|
|
|
<h3>3) Test scripts</h3>
|
|
|
|
|
<p>
|
2002-07-29 19:01:38 +00:00
|
|
|
The <b>test</b> directory contains PHP scripts, together with XML
|
|
|
|
|
templates and sample input files, for initializing and testing the
|
|
|
|
|
entire system:
|
2002-04-30 22:22:54 +00:00
|
|
|
<ul>
|
2002-08-19 18:43:10 +00:00
|
|
|
<li>
|
|
|
|
|
<b>test_uc.php</b>: tests I/O connection using descriptors.
|
|
|
|
|
<li>
|
|
|
|
|
<b>test_concat.php</b>: tests I/O connection using command-line
|
2002-07-29 19:01:38 +00:00
|
|
|
args and filenames.
|
2002-08-19 18:43:10 +00:00
|
|
|
<li>
|
|
|
|
|
<b>test_uc_slow.php</b>: tests checkpoint/restart.
|
|
|
|
|
You have to run the client yourself, kill and restart it a few times.
|
|
|
|
|
<li>
|
|
|
|
|
<b>test_prefs.php</b>: tests some aspects of preferences.
|
|
|
|
|
<li>
|
|
|
|
|
<b>test_api.php</b>: tests to ensure the api is working properly.
|
|
|
|
|
<li>
|
|
|
|
|
<b>test_water.php</b>: tests some aspects of water marks.
|
|
|
|
|
<li>
|
|
|
|
|
<b>test_rsc.php</b>: tests that scheduling server only sends
|
2002-10-03 20:41:23 +00:00
|
|
|
feasible work units.
|
2002-04-30 22:22:54 +00:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
2002-08-19 18:43:10 +00:00
|
|
|
These scripts use functions defined in the PHP include file
|
|
|
|
|
<b>init.inc</b>.
|
|
|
|
|
You can use these functions to easily write test
|
2002-07-29 19:01:38 +00:00
|
|
|
scripts for your own applications.
|
2002-09-10 17:04:05 +00:00
|
|
|
|
