libjava/classpath/doc/testing.framework.text

   1 Guile Testing Framework for GNU Classpath
   2 Written by Paul Fisher (rao@gnu.org)
   3
   4 GNU Classpath tests are written in Java.  Guile is responsible for
   5 executing the tests and organizing the results.  Guile and Java
   6 communicate through JNI.  If JNI is unavailable, see the section on
   7 modifying the framework to allow for an alternate means of
   8 communication. [This has not been written. -PF]
   9
  10 All tests must implement gnu.test.Test.  gnu.test.Test contains two
  11 methods:
  12
  13 1. String getName()
  14 2. Result test()
  15
  16 When getName() is called, your test should return the name of the
  17 test.  When test() is called, your test should be performed.  Upon
  18 completion of the test (either through success or failure), a Result
  19 object is returned.  test() may throw runtime exceptions and errors --
  20 if this happens, an implicit error result is returned.
  21
  22 There are seven predefined result types, including the POSIX 1003.3
  23 result codes.  All result objects may optionally be constructed with a
  24 single String argument specifying additional information about the
  25 result.
  26
  27 gnu.test.Pass        : Test passed and was excepted to pass.
  28 gnu.test.XPass       : Test passed but was expected to fail.
  29 gnu.test.Fail        : Test failed but was expected to pass.
  30 gnu.test.XFail       : Test failed and was expected to fail.
  31 gnu.test.Unresolved  : Test produced indeterminate results.
  32 gnu.test.Untested    : Test was not run -- a placeholder.
  33 gnu.test.Unsupported : Test does not have the required support to run.
  34
  35 (Error is also a valid result type, but only in Guile/JNI code.)
  36
  37 System.out and System.err are used for directing additional
  38 information about the running test.  System.out should be used to send
  39 status messages when tests are expected to take large amounts of time.
  40 System.err should be used to send messages which are logged to the
  41 verbose log.
  42
  43 Example test:
  44
  45 import gnu.test.*;
  46 public class StringCharAtZeroTest implements Test
  47 {
  48   public getName() {
  49     return "java.lang.String.charAt(0)";
  50   }
  51
  52   public Result test() {
  53     char ch = "foobar".charAt(0);
  54     if (ch == 'f')
  55       return new Pass();
  56     else
  57       return new Fail("zero index of \"foobar\" is '" + ch + "'");
  58   }
  59 }
  60
  61 It's often desirable to group multiple tests together into one file.
  62 In this case, inner classes should be used.  There's also the added
  63 benefit that tests can easily share data through static variables in
  64 the parent class.
  65
  66 For example:
  67
  68 import gnu.test.*;
  69 public class TestContainer {
  70   public static class test1 implements Test {
  71      String getName() {
  72        return "test1";
  73      }
  74      Result test() {
  75        // test1 ...
  76      }
  77   }
  78   public static class test2 implements Test {
  79     String getName() {
  80       return "test2";
  81     }
  82     Result test() {
  83       // test2 ...
  84     }
  85   }
  86 }
  87
  88 The testsuite contains a file known as "tests.to.run" which contains a
  89 newline delimited listing of all tests to be executed.  Just add the
  90 name of the new test to the file and it'll be included in future runs
  91 of the testsuite.
  92
  93 Running the testsuite:
  94 guile-jvm -s test.scm tests.to.run
  95
  96 (It would be more natural for the testsuite to read from standard in
  97 if a file was not specified, but read-line in Guile 1.3a is broken.)
  98
  99 Classes are located via the environmental variable CLASSPATH.
 100
 101 Results are sent to two log files -- one summary (classpath.sum) and
 102 one verbose (classpath.log).