Instructions for muJava, version I

Return to main page for current version.

This page contains the instructions for the old system. There are a few small differences, mostly having to do with names of files. We include this old version to provide for repeatability of experiments.

 

III. Downloading µJava

Although installing µJava is not technically difficult or complicated, it will require a little more effort than installing commercial packages. µJava can run on Unix, Linux, and Windows platforms. You will need to download and deploy three files; two Java "jar" files and a configuration file.

jmutation.jar openjavaHelper.jar jmutation.config

The two jar files should be placed in a directory on disk that all users who need to use µJava can access, for example, in C:\mujava\.

Although we have no license agreement, if you use µJava, we would like to hear about it. Particularly, if you publish papers that rely on µJava, please send an email to "offutt [at] ise.gmu.edu" and we will add the reference to the µJava web page.

 

IV. Using µJava to Test Classes

The muJava system requires that the Java CLASSPATH be modified to include the muJava jar files. Then one GUI (Java applet) is used to generate mutants, the tester must create tests, and another GUI is used to run mutants.

1. Environment Settings for the muJava System

There are three steps to setting up the environment for muJava, (1) CLASSPATH, (2) setting the config file, and (3) creating subdirectories.

  1. First, the Java CLASSPATH must be set to include the two muJava jar files "jmutation.jar" and "openjavaHelp.jar". In a DOS or Cygwin window, the following command will work:

    set CLASSPATH=%CLASSPATH%;C:\mujava\jmutation.jar;C:\mujava\openjavaHelper.jar

    In Win2000, go to Start-settings-Control Panel. Double-click System, go to the Advanced tab, and choose Environment Variables. Edit the CLASSPATH variable or create a new variable if there is none. Add the full path to jmutation.jar and openjavaHelp.jar to the CLASSPATH.

    In Unix, set the CLASSPATH environment variable. Assuming the jar files are stored in the home directory of user gpd:
    CLASSPATH=$CLASSPATH:/home/gpd/jmutation.jar:/home/gpd/openjavaHelp.jar ; export CLASSPATH
    Note that the syntax will vary under different shells, and it will be more convenient to put the command in your setup file such as .login, or .bashrc.

  2. Next, modify the jmutation.config file to point to a directory where you wish to store source Java files and muJava temporary files. The directory must be the complete path (either Windows or Unix). For example, the config file may contain the line: JMutation_HOME=C:\home\gpd\exp\.

    IMPORTANT: It is necessary to copy the config file to whatever directory you run the muJava system in.

  3. Finally, create a directory structure for the muJava system in the $JMutation_HOME directory. The subdirectories should be as:

    (Typo: "JMutation" in the figure should be "JMutation_HOME")

    There should be four subdirectories, used in the following ways. JMutation_HOME\src
    directory for Java files to be tested
    JMutation_HOME\classes directory for compiled classes of Java files from JMutation_HOME\src
    JMutation_HOME\testset directory for test sets
    JMutation_HOME\result directory for generated mutants

    You can create these subdirectories by hand or by using the muJava class "jmutation.makeJMutationStructure".

    java jmutation.makeJMutationStructure

2. Generating Mutants with muJava

Important note: You should run all commands in a directory that contains "jmutation.config"

  1. Put the classes to test to JMutation_HOME\src directory. muJava does not check for compilation errors, so all Java files should compile correctly. If the Java file to test needs other Java files or class files, they should also be placed in JMutation_HOME\src. For example, suppose you want to test B, which is a child class of A. Then, you should put both A.java and B.java into JMutation_HOME\src. If the file has a package structure, you should store the entire package underneath JMutation_HOME\src.
  2. Compile all the Java files in JMutation_HOME\src and copy the .class files into the JMutation_HOME\classes\ directory.

    java jmutation.compileSrc

    If you have problems, you can also compile yourself and copy the .class files manually.

  3. Generate the mutants from the GUI that is started from the command line:

    jmutation.gui.GenMutantsMain

    This command should bring a up a screen similar to the following:

    Select the files you want to mutate by clicking in the boxes on the left. Select the mutation operators you want to use by slecting their boxes. Then push RUN.

    Note: Mutant compilation is very slow. The class mutation operators produce far fewer mutants. Also note that a number of status messages go to the command window, but not the GUI.

    After mutants are generated, you can view the mutants in the "Class Mutants Viewer" and "Traditional Mutants Viewer" tabs.

    You may be interested in knowing where the mutant versions of the classes are stored. They are underneath the JMutation_HOME\result directory. The following example shows the directory Stack underneath result, with object-oriented mutants in class_mutants nad traditional mutants in a separate directory.

3. Making a test set

A testset in muJava is a Java file that contains executable test scripts. Each test is a method that contains a sequence of calls to methods in the class under test. Each test method returns a string result that is used to compare outputs of mutants with outputs of the original class. Each test method should start with the string "test". The test methods and the test class should have public access.

Below is an example of a testset class for the class Stack. Its name is StackTest. StackTest contains two test case: test1() and test2(). The testset .class file should be in the directory JMutation_HOME\testset\.

public class StackTest
{

    public String test1()
    {
        String result = "";
        Stack obj = new Stack();
        obj.push(2);
        obj.push(4);
        result = result + obj.isFull();
        result = result + obj.pop();
        return result;
    }

    public String test2()
    {
        String result = "";
        Stack obj = new Stack();
        obj.push(5);
        obj.push(3);
        result = result + obj.pop();
        result = result + obj.pop();
        return result;
    }

}

4. Running mutants.

Run the mutants from another GUI. Start it with the following command:

jmutation.gui.RunTestMain

Note: Your CLASSPATH must not include Mutation_HOME\classes\. If it does, no mutants can be killed.

You should see the following GUI. You can select which collection of mutants to run, and which testset to use. The "Class Mutants Viewer" and "Traditional Mutants Viewer" tabs will show the source view of the mutants. You can design tests to kill mutants by finding a live mutant, then analyzing the program to decide what input will kill it. Remember that between 5% to 20% of the mutants will be equivalent.

Last update: March 2005, Jeff Offutt

Assistance from the U.S. National Science Foundation
under grant CCR-98-04111 to George Mason University
is greatly appreciated.