This is Mauve, a free test suite for the Java Class Libraries.

Mauve is intended to test several different varieties of the
libraries.  For instance, it will contain tests that are specific to a
particular JDK version.  Tags in the test files help the test
framework decide which tests should or should not be run against a
given runtime.


This file has two main sections:
0) CONFIGURING AND BUILDING THE TESTSUITE
1) RUNNING THE TESTS
2) NOTES


******CONFIGURING AND BUILDING THE TESTSUITE*******
To build, first run configure.  Below we cover the following:
  0.  Specifying which VM to test.
  1.  Configuring the auto-compilation feature.
  2.  Environment variables for configure.
  3.  Other options to configure.
  4.  Building the testsuite.


0. Specifying the VM to test.
  The configure script takes the following option that specifies which java
  implementation the testsuite will test:
  
      --with-vm=TESTVM
  
  For example, specifying --with-vm=jamvm will invoke "jamvm" when 
  running the tests, and will therefore test the java implementation associated
  with your jamvm installation.  If this option is not specified, it defaults
  to "java".

  
1. Configuring the auto-compilation feature.
  If you plan to use the auto-compilation feature of the Harness, which
  compiles tests inline before running them (so new tests, or changed
  tests are run properly without an additional step), you need to be sure
  it is properly configured. The following options are associated
  with auto-compilation:

	 --enable-auto-compilation  	Enable the auto-compilation feature
	 --with-ecj-jar					Specify the location of the eclipse-ecj.jar
	 								file for the compiler to use.  This defaults
	 								to /usr/share/java/eclipse-ecj.jar and only 
	 								needs to be specified if the location on your
	 								machine is different from this.  If no valid
	 								ecj jar is found, auto-compilation will be 
	 								turned off.
	 --with-bootclasspath			Specify the bootclasspath for the compiler.

  Auto-compilation is enabled by default, and the bootclasspath is found
  automatically.  If you wish to disable auto-compilation or change the
  bootclasspath you should use the appropriate option(s) above.


2. Environment variables for configure.
  You can control the configuration with some environment variables:

     JAVA   Name of Java interpreter to use
     JAVAC  Name of Java (to class) compiler to use
     GCJ    Name of Java (to object) compiler to use

  GCJ is only used when the `--with-gcj' option is given to configure.  

	 								
3. Other configure options. 
  The configure script also supports the following `--with' options:

     --with-gcj					Indicate you will be using gcj, this will tell
     							make to build the object files and use the 
     							appropriate compiler
     --with-tmpdir=DIR          Put temporary files in DIR
                                defaults to `/tmp'
     --with-mailhost=HOSTNAME   Use mail server at HOSTNAME for socket tests 
                                defaults to `mx10.gnu.org'
                                (Use this option if your local firewall
                                 blocks outgoing connections on port 25.)

                                 
4. Building the testsuite.
  If you are using the auto-compilation feature, there is no need to build the
  tests, it will suffice to compile the files Harness.java and 
  RunnerProcess.java.
  
  If you are using gcj or are not using the auto-compilation feature, you should
  now run GNU make to build the testsuite.
  
  
  

*******RUNNING THE TESTS*******
The Mauve tests are run using the harness script in the top directory.  This
section provides instructions on how to perform the following tasks:

  0.  Running all the tests.
  1.  Specify the VM on which to run the tests and any VM arguments
  2.  Select a subset of the tests to run
  3.  Use an input file to specify the tests to run
  4.  Change the timeout interval
  5.  Change the information displayed when tests are run
  6.  Turn on (or off) test auto-compilation.
  7.  Test output format
  

0. Running all the tests
  To run all the tests in the Mauve test suite, type 'HARNESSVM Harness' where 
  HARNESSVM is the VM you wish to use to run the Harness.  Note that this is NOT
  the same as the VM on which you run the tests.  Read item 1 to learn how to 
  set the VM on which you run the tests.
  
  You can also run all the tests by typing 'HARNESSVM Harness gnu.testlet'.
  

1.  Specifying the VM on which to run the tests and any VM arguments

  The VM on which to run the tests can be specified by configure as described
  in the first section, CONFIGURING AND BUILDING THE TESTSUITE.  It can also be
  done via command line options to the Harness (which override the configure
  options).  To set the VM via the command line, use:
  
  -vm [vmpath] 
  
  If, for example, I wanted to run all the JTable tests using JamVM, and then 
  run them all on Sun's VM for comparison, I would type:

  HARNESSVM Harness javax.swing.JTable -vm jamvm

  and then

  HARNESSVM Harness javax.swing.JTable -vm java

  if "java" was a system command to run Sun's VM.  If not, you should specify
  the path to Sun's "java" executable (ex: /usr/lib/java-1.5.0/bin/java).  Note
  again that HARNESSVM is just the VM used to run the harness, and not the tests.
  This is done for performance considerations to allow the Harness to be natively
  compiled and ran while testing a variety of VMs.
  
  To specify arguments for the VM, use:
  
  -vmarg ARGUMENT
  
  For example, the following command will run the JTable tests on JamVM with
  the -Xnocompact argument:
  
  HARNESSVM Harness javax.swing.JTable -vm jamvm -vmarg -Xnocompact

  For debugging purposes it may be helpful to run the testprocess with a
  special program like strace, time or gdb. To prepend such a command before
  the VM use the -vmprefix argument and specify a path to the program you want
  to run:

  -vmprefix [prefixpath]

  For example, the following command will run a Socket test with strace on
  Cacao:

  HARNESSVM Harness java.net.Socket -vm cacao -vmprefix strace

2.  Selecting a subset of the tests to run

  This is a common task for developers, you may be working to fix a bug in a 
  certain area and want to run all the related tests, but not the entire
  testsuite.  Simply specify the folder containing the tests, and all the tests
  in that folder (and its subfolders, although this can be turned off) will be 
  run.

  Example: run all the java.net tests (remember, this uses system default 
  "java" unless you have environment variable MAUVEVM set):

  1.  HARNESSVM Harness java.net
  2.  HARNESSVM Harness gnu.testlet.java.net
  3.  HARNESSVM Harness gnu/testlet/java/net
  3.  HARNESSVM Harness gnu/testlet/java/net/
  *   It makes no difference if you use "." or "/", or if you have the
      "gnu.testlet" preceeding the test folder or if you have a trailing "/".
      
  You may want to exclude certain tests from a run, this done using the
  -exclude option.  Extending our previous example, let's run all the java.net
  tests except for the java.net.Socket tests.
      
  1.  HARNESSVM Harness java.net -exclude java.net.Socket
  2.  HARNESSVM Harness -exclude java.net.Socket java.net

  The test or folder you want to exclude must follow the -exclude option, but 
  other than that, the order doesn't matter.  In example #2 above java.net is
  still taken to be tests you want to run, not tests you want to exclude.  So
  if you want to exclude more than one folder, you need to use the -exclude
  flag multiple times.
  
  If a folder has several subfolders and you want to exclude them all, you
  can use the -norecursion option instead of explicitly excluding them 
  all.  So to run the AbstractDocument tests but not the BranchElement or
  LeafElement tests, type:
  
  HARNESSVM Harness javax.swing.text.AbstractDocument -norecursion
  
  Again, the order of the arguments/options doesn't matter.
  
  
3.  Using an input file to specify tests to be run

  Simply use the -file [filename] option.  The input file should list, one per
  line, the tests or folders you want to test.

  Example: HARNESSVM Harness -file myInputFile

  The input file specifies only tests to be run, not excluded, to exclude tests
  you need to explicitly do so as in Section 2 above. 

  Example: HARNESSVM Harness -file myInputFile -exclude java.net.Socket
  

4.  Changing the timeout interval

  The Harness detects tests that have hung and terminates them.  It does so 
  simply by allowing all tests to run for 60 seconds and if they haven't 
  completed, declaring them hung.  If a test simply takes a long time you may
  want to increase this interval.  If on the other hand, no passing tests take
  longer than a few seconds and hanging tests are slowing down your test runs,
  you may want to decrease the interval.  To set the timeout interval use
  the -timeout [interval] option.  The interval is specified in milliseconds.

  Example: HARNESSVM Harness gnu.java.security -timeout 30000
  
  will set the timeout to be 30 seconds instead of 60.
  
  
5.  Changing the information displayed during test runs

  By default the Harness prints only messages for those tests that fail, and 
  prints full stack traces for uncaught exceptions. The following
  options affect what is printed:
  
  -hidecompilefails: hides failures from the compiler.  These can still be 
					 found in the .ecjErr file.
  
  -verbose: 		 prints information about each passing harness.check() call
					 within the tests, whether they pass or fail.
  
  -noexceptions: 		 suppress full stack traces for uncaught exceptions
  
  -showpasses: 		 prints one-line summaries for passing tests
  
  -debug:      		 prints toString() information when a 
               		 harness.check(Object, Object) call fails.


6.  Turning off (or on) test auto-compilation
  The auto-compilation feature is enabled by default, but can be turned off by 
  using the --disable-auto-compilation option to configure.  You can also turn
  off the option by using the following Harness option:
  
  -compile no	   OR    -compile false
  
  If you have disabled auto-compilation in configure but wish to turn it on
  for a particular test run, use
  
  -compile yes     OR    -compile true
  
  Note that auto-compilation requires a correct path to eclipse-ecj.jar and 
  a correct bootclasspath.  The following options deal with this:
  
  -bootclasspath BOOTCLASSPATH
  -ecj-jar ECJ_JAR_LOCATION
  
  These can also be specified at configure time via 
  --with-bootclasspath and --with-ecj-jar, the latter defaulting
  to /usr/share/java/eclipse-ecj.jar if no location is specified.  The default
  bootclasspath is found automatically and shouldn't need to be changed unless
  you specifically want to specify an alternate location.
  
  So the default setup of:
    1.  ./configure
    2.  make
    3.  HARNESSVM Harness
    
  will run with auto-compilation enabled with the ecj jar being 
  /usr/share/java/eclipse-ecj.jar and the bootclasspath found automatically.


7.  Test output format
  Test results are available in xml format by use of the '-xmlout' and '-autoxml' flags

  '-xmlout' is supplied with the xml file name where the total test run data will be stored:

    HARNESSVM Harness -xmlout XML_FILE

  '-autoxml' is supplied with the directory name, where individual xml files will be generated
  and stored for each test executed:

    HARNESSVM Harness -autoxml RESULTS_DIRECTORY


******NOTES*******
This section explains some additional notes to take into account when using
Mauve. It has the following subsections:
  0. External Data
  
0. External Data

  Tests can have additional data included. Usually, data is located either
  in the same package of the test, or in a subpackage.
  The following files come from external sources. The list includes the
  last known license at time the file was added, the source and the location
  in Mauve. For details on the use see the corresponding tests.
  
  * gnu/testlet/javax/sound/sampled/data/k3b_success1.wav, GPL,
  k3b-1.0.1-1.fc7.2 (fedora 7)
  * gnu/testlet/javax/sound/sampled/data/k3b_success1.au, GPL,
  converted from k3b_success1.wav.