Initial commit.

1 files changed, 89 insertions, 0 deletions

diff --git a/doc/testing.framework.text b/doc/testing.framework.text
new file mode 100644
index 000000000..c79dcd93a
--- /dev/null
+++ b/doc/testing.framework.text
@@ -0,0 +1,89 @@
+Guile Testing Framework for GNU Classpath
+
+GNU Classpath tests are written in Java.  Guile is responsible for
+executing the tests and organizing the results.  Guile and Java
+communicate through JNI.  If JNI is unavailable, see the section on
+modifying the framework to allow for an alternate means of
+communication. [This has not been written. -PF]
+
+All tests must implement gnu.test.Test.  gnu.test.Test contains two
+methods:
+
+1. String getName()
+2. Result test()
+
+When getName() is called, your test should return the name of the
+test.  When test() is called, your test should be performed.  Upon
+completion of the test (either through success or failure), a Result
+object is returned.  test() should never throw an exception or error.
+
+There are seven predefined result types, including the POSIX 1003.3
+result codes.  All result objects may optionally be constructed with a
+single String argument specifying additional information about the
+result.
+
+gnu.test.Pass        : Test passed and was excepted to pass.
+gnu.test.XPass       : Test passed but was expected to fail.
+gnu.test.Fail        : Test failed but was expected to pass.
+gnu.test.XFail       : Test failed and was expected to fail.
+gnu.test.Unresolved  : Test produced indeterminate results.
+gnu.test.Untested    : Test was not run -- a placeholder.
+gnu.test.Unsupported : Test does not have the required support to run.
+
+(Error is also a valid result type, but only in Guile/JNI code.)
+
+System.out and System.err are used for directing additional
+information about the running test.  System.out should be used to send
+status messages when tests are expected to take large amounts of time.
+System.err should be used to send messages which are logged to the
+verbose log.
+
+Example test:
+
+import gnu.test.*;
+public class StringCharAtZeroTest implements Test
+{
+  public getName() {
+    return "java.lang.String.charAt(0)";
+  }
+
+  public Result test() {
+    char ch = "foobar".charAt(0);
+    if (ch == 'f')
+      return new Pass();
+    else
+      return new Fail("zero index of \"foobar\" is '" + ch + "'");
+  }
+}
+
+It's often desirable to group multiple tests together into one file.
+In this case, inner classes should be used.  There's also the added
+benefit that tests can easily share data through static variables in
+the parent class.
+
+For example:
+
+public class TestContainer {
+  public static class test1 implements Test {
+     // test1
+  }
+  public static class test2 implements Test {
+     // test2
+  }
+}
+
+The testsuite contains a file known as "tests.to.run" which contains a
+newline delimited listing of all tests to be executed.  Just add the
+name of the new test to the file and it'll be included in future runs
+of the testsuite.
+
+Running the testsuite:
+guile-jvm -s test.scm tests.to.run
+
+(It would be more natural for the testsuite to read from standard in
+if a file was not specified, but read-line in Guile 1.3a is broken.)
+
+Classes are located via the environmental variable CLASSPATH.
+
+Results are sent to two log files -- one summary (classpath.sum) and
+one verbose (classpath.log).