ACE/docs/run_test.txt

   1 /**
   2 @page run_test_howto How to write a run_test.pl
   3
   4 ACE/TAO's auto_builds expect run_test.pl's to follow some guidelines
   5 that are needed to keep the auto_builds from hanging and to make
   6 sure the run_test.pl works on all platforms
   7
   8 - The run_test must not hang or block.
   9 - The run_test must clean up any temporary files when it is done.
  10 - The run_test must not require any user input
  11 - The run_test should return a non-zero value if the test failed
  12 - When an executable can't be spawned the test should directly exit and
  13   not wait for a fail to be created by that executable
  14 - The processes should support that files names are passed through
  15   the commandline
  16
  17 Following is an example
  18
  19 @subsection example Example
  20
  21 @verbatim
  22 eval '(exit $?0)' && eval 'exec perl -S $0 ${1+"$@"}'
  23     & eval 'exec perl -S $0 $argv:q'
  24     if 0;
  25
  26 # -*- perl -*-
  27
  28 use lib "$ENV{ACE_ROOT}/bin";
  29 use PerlACE::TestTarget;
  30
  31 $status = 0;
  32
  33 my $server = PerlACE::TestTarget::create_target (1) || die "Create target 1 failed\n";
  34 my $client = PerlACE::TestTarget::create_target (2) || die "Create target 2 failed\n";
  35
  36 $plain_server_ior = "server.ior";
  37 my $iorbase = "server.ior";
  38 my $server_iorfile = $server->LocalFile ($iorbase);
  39 my $client_iorfile = $client->LocalFile ($iorbase);
  40 $server->DeleteFile($iorbase);
  41 $client->DeleteFile($iorbase);
  42
  43 $SV = $server->CreateProcess ("server", "-ORBdebuglevel $debug_level -o $server_iorfile");
  44 $CL = $client->CreateProcess ("client", "-k file://$client_iorfile");
  45
  46 $server_status = $SV->Spawn ();
  47
  48 if ($server_status != 0) {
  49     print STDERR "ERROR: server returned $server_status\n";
  50     exit 1;
  51 }
  52
  53 if ($server->WaitForFileTimed ($iorbase,
  54                                $server->ProcessStartWaitInterval()) == -1) {
  55     print STDERR "ERROR: cannot find file <$server_iorfile>\n";
  56     $SV->Kill (); $SV->TimedWait (1);
  57     exit 1;
  58 }
  59
  60 if ($server->GetFile ($iorbase) == -1) {
  61     print STDERR "ERROR: cannot retrieve file <$server_iorfile>\n";
  62     $SV->Kill (); $SV->TimedWait (1);
  63     exit 1;
  64 }
  65 if ($client->PutFile ($iorbase) == -1) {
  66     print STDERR "ERROR: cannot set file <$client_iorfile>\n";
  67     $SV->Kill (); $SV->TimedWait (1);
  68     exit 1;
  69 }
  70
  71 $client_status = $CL->SpawnWaitKill ($client->ProcessStartWaitInterval());
  72
  73 if ($client_status != 0) {
  74     print STDERR "ERROR: client returned $client_status\n";
  75     $status = 1;
  76 }
  77
  78 $server_status = $SV->WaitKill ($server->ProcessStopWaitInterval());
  79
  80 if ($server_status != 0) {
  81     print STDERR "ERROR: server returned $server_status\n";
  82     $status = 1;
  83 }
  84
  85 $server->GetStderrLog();
  86 $client->GetStderrLog();
  87
  88 $server->DeleteFile($server_iorfile);
  89 $client->DeleteFile($client_iorfile);
  90
  91 exit $status;
  92
  93 @endverbatim
  94
  95 @subsection details Example Details
  96
  97 @verbatim
  98 eval '(exit $?0)' && eval 'exec perl -S $0 ${1+"$@"}'
  99     & eval 'exec perl -S $0 $argv:q'
 100     if 0;
 101
 102 @endverbatim
 103
 104 This is the standard header stuff.  The eval is a trick used
 105 to get the perl script to run if it a unix shell treats it as
 106 a shell script.
 107
 108 The SVN ID string is the usual one we put in.
 109
 110 @verbatim
 111 use lib "$ENV{ACE_ROOT}/bin";
 112 use PerlACE::TestTarget;
 113 @endverbatim
 114
 115 The use lib line is used to tell Perl where the PerlACE modules are.
 116 It should NOT be a relative path to the bin directory.  This is how
 117 it used to be done, but doing so would be incompatible with the "flat"
 118 directory layout of ACE+TAO.  The correct way is demonstrated above.
 119 After the "use lib" line, always use $PerlACE::TAO_ROOT to reference
 120 the location of TAO.  Use either $ENV{ACE_ROOT} or $PerlACE::ACE_ROOT
 121 to reference the location of ACE.
 122
 123 And PerlACE::Run_Test is a module to be used by all run_test.pl's.
 124 It does a couple of things, including parsing some common command
 125 line arguments (like -Config and -ExeSubDir) and also brings in
 126 the PerlACE::Process module.
 127
 128 @verbatim
 129 my $server = PerlACE::TestTarget::create_target (1) || die "Create target 1 failed\n";
 130 my $client = PerlACE::TestTarget::create_target (2) || die "Create target 2 failed\n";
 131 @endverbatim
 132
 133 We need to have two targets to run the tst on
 134
 135 @verbatim
 136 my $iorbase = "server.ior";
 137 my $server_iorfile = $server->LocalFile ($iorbase);
 138 my $client_iorfile = $client->LocalFile ($iorbase);
 139 $server->DeleteFile($iorbase);
 140 $client->DeleteFile($iorbase);
 141 @endverbatim
 142
 143 We need to have a fully
 144 qualified path to all *.ior and *.conf files.  We unlink the file
 145 immediately because we use WaitForFileTimed later.
 146
 147 @verbatim
 148 $SV = $server->CreateProcess ("server", "-ORBdebuglevel $debug_level -o $server_iorfile");
 149 @endverbatim
 150
 151 The server we have to spawn
 152
 153 @verbatim
 154 $CL = $client->CreateProcess ("client", "-k file://$client_iorfile");
 155
 156 $server_status = $SV->Spawn ();
 157
 158 if ($server_status != 0) {
 159     print STDERR "ERROR: server returned $server_status\n";
 160     exit 1;
 161 }
 162 @endverbatim
 163
 164 The PerlACE::Process is created with an executable and
 165 arguments.  @note Unlike the old Process module, the process
 166 isn't started until one of the Spawn methods is used. We check
 167 the result of the spawn, if we couldn't spawn the process
 168 we directly exit the script.
 169
 170 @verbatim
 171 if ($server->WaitForFileTimed ($iorbase,
 172                                $server->ProcessStartWaitInterval()) == -1) {
 173     print STDERR "ERROR: cannot find file <$server_iorfile>\n";
 174     $SV->Kill (); $SV->TimedWait (1);
 175     exit 1;
 176 }
 177 @endverbatim
 178
 179 The WaitForFileTimed method waits until the file is
 180 created.  In this way, we know when to start the client.  If
 181 no IOR file is used, then you'd need to use Perl's sleep
 182 method.
 183
 184 @verbatim
 185 if ($server->GetFile ($iorbase) == -1) {
 186     print STDERR "ERROR: cannot retrieve file <$server_iorfile>\n";
 187     $SV->Kill (); $SV->TimedWait (1);
 188     exit 1;
 189 }
 190 if ($client->PutFile ($iorbase) == -1) {
 191     print STDERR "ERROR: cannot set file <$client_iorfile>\n";
 192     $SV->Kill (); $SV->TimedWait (1);
 193     exit 1;
 194 }
 195 @endverbatim
 196
 197 This transfers the file from the server to the client in
 198 case that is needed with the used test targets.
 199
 200 @verbatim
 201 $client_status = $CL->SpawnWaitKill ($client->ProcessStartWaitInterval());
 202
 203 if ($client_status != 0) {
 204     print STDERR "ERROR: client returned $client_status\n";
 205     $status = 1;
 206 }
 207 @endverbatim
 208
 209 Here is an example of starting the client.  SpawnWaitKill will start
 210 the process and wait for the specified number of seconds for the
 211 process to end.  If the time limit is reached, it will kill the
 212 process and return -1.
 213
 214 The return value of SpawnWaitKill is the return value of the
 215 process, unless it timed out.  You don't need to check for the
 216 timeout, since SpawnWaitKill will print out a timeout error.
 217 Instead, just check for != 0.
 218
 219 @verbatim
 220 $server_status = $SV->WaitKill ($server->ProcessStopWaitInterval());
 221
 222 if ($server_status != 0) {
 223     print STDERR "ERROR: server returned $server_status\n";
 224     $status = 1;
 225 }
 226 @endverbatim
 227
 228 Here is the termination of the server.  Servers are usually terminated
 229 either by TerminateWaitKill or just WaitKill.  TerminateWaitKill is
 230 used when the server doesn't shut down itself.  WaitKill is used when
 231 it does (such as when the client calls a shutdown method).  Once
 232 again, we check the return status.
 233
 234 @verbatim
 235 $server->GetStderrLog();
 236 $client->GetStderrLog();
 237
 238 $server->DeleteFile($server_iorfile);
 239 $client->DeleteFile($client_iorfile);
 240
 241 exit $status;
 242 @endverbatim
 243
 244 This example illustrates how to get the host name within the cross
 245 platform test. In your test program add functionality to handle a
 246 command line argument to pass the host name of the target. In the
 247 run_test.pl script you can use the following code as example.
 248
 249 @verbatim
 250 my $server = PerlACE::TestTarget::create_target (1) || die "Create target 1 failed\n";
 251 my $hostname = $server->HostName();
 252 $SV = $server->CreateProcess ("server", "-ORBEndpoint iiop://$hostname:43210");
 253 $CL = $server->CreateProcess ("client", " -p 43210 -h $hostname");
 254 @endverbatim
 255
 256 And finally, we unlink any files that were created and then just
 257 exit with $status.
 258
 259 */