test docs

svn path=/trunk/boinc/; revision=458
2002-10-03 20:41:23 +00:00 · 2002-10-03 20:41:23 +00:00 · 6a5eedfcbc
parent c0813dcd55
commit 6a5eedfcbc
8 changed files with 195 additions and 195 deletions
--- a/3
+++ b/3
@ -2065,6 +2065,9 @@ David   Oct 3 2002
        main.C
        validate.C
        validate_test.C
+    test/
+        test.inc (new)
+        test_uc.php
    tools/
        add.C
        backend_lib.C,h
--- a/doc/client_data.html
+++ b/doc/client_data.html
@ -57,11 +57,10 @@ and installs a pointer.
 <h3>Handling a scheduler RPC reply</h3>
 <p>
 A similar approach is used when handling the reply
-from an scheduling server RPC (CLIENT_STATE::handle_scheduler_reply).
+from a scheduling server RPC (CLIENT_STATE::handle_scheduler_reply).
 The RPC returns a interconnected set of basic objects,
 represented in a SCHEDULER_REPLY object.
 For each of these basic objects, we see (e.g. lookup_app())
-if it's alread present in the CLIENT_STATE structure.
+if it's already present in the CLIENT_STATE structure.
 If not, we create and insert a new object,
-then link it (e.g., link_app()) to establish pointers to
-associated objects in CLIENT_STATE.
+then link it (e.g., link_app()) to existing objects in CLIENT_STATE.
--- a/doc/create_project.html
+++ b/doc/create_project.html
@ -53,10 +53,6 @@ Setting up a BOINC server
 <li> <a href=test.html>Test applications and scripts</a>
 <li> <a href=project_startup.html>Project startup checklist</a>

-<!--
-<li> <a href=master_url.html>The master URL</a>
-<li> <a href=install.html>Installing a BOINC server</a>
-->
 </ul>

 <font size=+1><b>
--- a/doc/install.html
+++ b/doc/install.html
@ -1,160 +0,0 @@
-<title>Installing a BOINC server</title> 
-<body bgcolor=ffffff>
-
-<h2>Installing a BOINC server</h2>
-<p>
-To create a BOINC server you must have the following software installed:
-<ul>
-<li> MySQL
-<li> Apache with PHP
-</ul>
-If Apache is configured to run with Fast CGI, rename fcgi to cgi in
-the "boinc/sched" directory, replacing the existing cgi.
-<p>
-Add the following environment variables (with appropriate changes) to your .tcshrc
-<pre>
-# These 5 are used at compile time
-setenv BOINC_DB_NAME        boinc_barry
-setenv BOINC_DB_PASSWD
-setenv BOINC_KEY            0xdabacafe
-setenv BOINC_KEY_DIR        ~/keys
-setenv BOINC_UPLOAD_DIR     ~/upload
-
-# These 3 are used at runtime
-setenv BOINC_DOWNLOAD_DIR   ~/download
-setenv BOINC_UPLOAD_URL     http://maggie.ssl.berkeley.edu/barry/cgi/file_upload_handler
-setenv BOINC_DOWNLOAD_URL   http://maggie.ssl.berkeley.edu/barry/download
-
-# These 4 are for test scripts
-setenv BOINC_PLATFORM       sparc-sun-solaris2.7
-setenv BOINC_EMAIL          barry@ssl.berkeley.edu
-setenv BOINC_USER           barry
-setenv BOINC_MASTER_URL     http:\\\\\/\\\\/maggie.ssl.berkeley.edu\\\\/~barry
-</pre>
-
-Each time BOINC_DB_NAME, BOINC_DB_PASSWD, BOINC_KEY, BOINC_KEY_DIR, or BOINC_UPLOAD_DIR are
-changed you must recompile the scheduler by going into the sched/ directory, typing
-"make clean", "make", and "make install".
-
-<p>
-After setting your necessary environment variables you must edit your httpd.conf to
-configure Apache.
-
-Add the following lines (with appropriate changes) where aliases are placed.
-
-<pre>
-Alias /barry/ "/disks/philmor/a/users/barry/"
-
-&#60;Directory&#62;
-    Options Indexes FollowSymlinks MultiViews
-    AllowOverride None
-    Order allow,deny
-    Alias from all
-&#60;/Directory&#62;
-</pre>
-
-This allows you to resolve URL's and path names that go to your home directory.
-This way you can have your upload and download directories, key directory, and cgi
-directory in your home directory and still have them reacheable through the web.
-<p>
-In addition add the following lines (with appropriate changes) where script 
-aliases are placed.
-
-<pre>
-ScriptAlias /barry-cgi/ "/disks/philmor/a/users/barry/cgi/"
-
-&#60;Directory "/disks/philmor/a/users/barry/cgi/"&#62;
-    AllowOverride None
-    Options None
-    Order allow,deny
-    Allow from all
-&#60;/Directory&#62;
-</pre>
-
-This allows CGI files to be executed in the specified directory.  You will put
-your scheduler and file_upload_handler into this directory.
-<p>
-You must make a directory for downloads and a directory for uploads.  Make sure
-that the download directory is world readable.  You must also make a directory to hold
-the different necessary keys.
-<p>
-Now you are ready to install BOINC.
-Unzip and untar the BOINC release.  Type
-"configure", "make", and "make install".  "make" will compile all the source 
-code and "make install" will install a BOINC server in the INSTALL_DIR (currently
-set to /usr/local/boinc/) specified in the Makefile.
-
-<p>
-Go into the boinc/test directory, and type
-<h4>
-test_uc.php
-</h4>
-This script runs a test case that initializes the database with a
-user account, application and workunits, runs the client, and checks the
-results. 
-
-<h4>
-BOINC_DB_NAME
-</h4>
-This is name of the database that the particular BOINC project you are running
-uses.  Each BOINC project must have a different BOINC_DB_NAME.
-<h4>
-BOINC_DB_PASSWD
-</h4>
-<h4>
-BOINC_KEY
-</h4>
-This should be set to any 32 bit hex value desired. To run
-multiple BOINC projects on one machine, each project needs to have
-a different BOINC_KEY compiled into it.  The BOINC_KEY is used to create
-a shared memory segment.  Each project has a different shared memory segment.
-<h4>
-BOINC_KEY_DIR
-</h4>
-This should be set to a directory in which the public and private
-keys for BOINC are to be created. If you wish to place this in a
-different directory, change the variable appropriately.
-<h4>
-BOINC_UPLOAD_DIR
-</h4>
-This is where clients will upload their results to.  It is important 
-that this directory is different from the BOINC_DOWNLOAD_DIR.
-<h4>
-BOINC_DOWNLOAD_DIR
-</h4>
-This is where clients will download project applications and other necessary files to run
-those applications from.  It is important that this directory is different from
-the BOINC_UPLOAD_DIR.
-<h4>
-BOINC_UPLOAD_URL
-</h4>
-This is the url to the file_upload_handler.
-<h4>
-BOINC_DOWNLOAD_URL
-</h4>
-This is the url to the BOINC_DOWNLOAD_DIR.
-<h4>
-BOINC_PLATFORM_NAME
-</h4>
-This is currently used by one of the test scripts.
-It is not critical for the running of BOINC.  Normally, projects
-will have a list of platforms that their applications will be allowed to run
-on.
-<h4>
-BOINC_EMAIL
-</h4>
-This is currently used by one of the test scripts to create a user. 
-It is not critical for the running of BOINC.
-<h4>
-BOINC_USER
-</h4>
-This is currently used by one of the test scripts to create a user. 
-It is not critical for the running of BOINC.
-<h4>
-BOINC_MASTER_URL
-</h4>
-This is currently used by one of the test scripts.
-It is not critical for the running of BOINC.
-Normally, each project will be identified by a BOINC_MASTER_URL.
-The client will go to this URL and will be told where to go
-to get work from the scheduler.
--- a/doc/master_url.html
+++ b/doc/master_url.html
@ -1,23 +0,0 @@
-<title>The master URL</title> 
-<body bgcolor=ffffff>
-<h2>The master URL</h2> 
-<p>
-Each project is publicly identified by a <b>master URL</b>.
-The <b>master page</b> at this URL has two functions.
-<ul>
-<li> It is the home page of the project; when viewed in a browser it
-describes the project and contains links for registering and for
-downloading the core client.
-<li> It contains XML elements of the form <pre>
-&lt;scheduler&gt;http://host.domain.edu/cgi/scheduler&lt;scheduler&gt;
-&lt;scheduler&gt;http://host2.domain.edu/cgi/scheduler&lt;scheduler&gt;
-</pre>
-that give the URLs of the project's scheduling servers.
-These tags can be embedded within HTML comments.
-The BOINC core client reads
-and parses the master page to locate scheduling servers.
-If at any point it is unable to
-connect to any scheduling server for a project,
-it rereads the master page.
-This mechanism lets a project change the locations of its scheduling
-servers, or add new servers. 
--- a/doc/security.html
+++ b/doc/security.html
@ -35,7 +35,7 @@ A project intentionally releases an application that abuses participant
 hosts, e.g. by stealing sensitive information stored in files.
 <li>
 <b>Accidental abuse of participant hosts by projects</b>.
-A project releases an application that unintentionally abuses particpant
+A project releases an application that unintentionally abuses participant
 hosts, e.g. deleting files or causing crashes.
 </ul>
 BOINC provides mechanisms to reduce the likelihood of some of these attacks. 
--- a/doc/test.html
+++ b/doc/test.html
@ -1,19 +1,200 @@
-<title>Test applications and scripts</title> 
+<title>Testing BOINC</title> 
 <body bgcolor=ffffff>
-<h2>Test applications and scripts</h2> 
+<h2>Testing BOINC</h2> 

+<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):
 <pre>
 setenv BOINC_PROJECTS_DIR   /home/david/boinc_projects
+# BOINC projects directory
 setenv BOINC_HOSTS_DIR      /home/david/boinc_hosts
+# BOINC hosts directory
 setenv BOINC_USER_NAME      david
+# prepended to web error log entries
 setenv BOINC_SRC_DIR        /home/david/boinc_cvs/boinc
+# BOINC source directory
 setenv BOINC_CGI_DIR        /home/david/cgi-bin
+# path of a CGI directory
 setenv BOINC_CGI_URL        http://localhost/cgi-bin
+# URL of that directory
 setenv BOINC_HTML_DIR       /home/david/html
+# path of a web-page directory
 setenv BOINC_HTML_URL       http://localhost
+# URL of that directory
 setenv BOINC_KEY_DIR        /home/david/boinc_keys
+# path of some pre-generated security keys
 setenv BOINC_PLATFORM       i686-pc-linux-gnu
+# platform name of this machine
 </pre>
+<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
+&lt;?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>
 <p>
 The <b>apps</b> directory contains the following test applications: 
 <ul>
@ -28,6 +209,9 @@ writes to stdout.
 character per second.
 Checkpoints every 5 characters. Restartable.
 </ul>
+
+<h3>3) Test scripts</h3>
+<p>
 The <b>test</b> directory contains PHP scripts, together with XML
 templates and sample input files, for initializing and testing the
 entire system: 
@ -48,7 +232,7 @@ You have to run the client yourself, kill and restart it a few times.
 <b>test_water.php</b>: tests some aspects of water marks.
 <li>
 <b>test_rsc.php</b>: tests that scheduling server only sends
-feasable work units. 
+feasible work units. 
 </ul>
 <p>
 These scripts use functions defined in the PHP include file
--- a/test/test.inc
+++ b/test/test.inc
@ -252,6 +252,7 @@ class Project {

 class User {
    var $name;
+    var $email_addr;
    var $authenticator;

    function User() {