µJava

Version 4, June 2013

JUnit tests, Java 1.6 features (including generics), and fault fixes.
(minor bug fixes, May 2014, August 2016)

µJava Home page: https://cs.gmu.edu/~offutt/mujava/

April 2015: µJava has been released as open source on github under the Apache
license.
A command line interface to µJava, muScript, was released March 2014.
The Version 3 page is still available.

µJava (muJava) is a mutation system for Java programs. It automatically generates

mutants for both traditional mutation testing and class-level mutation
testing. µJava can test individual classes and packages of multiple classes. Tests are
supplied by the users as sequences of method calls to the classes under test
encapsulated in JUnit classes.

µJava is the result of a collaboration between two universities, Korea Advanced

Institute of Science and Technology (KAIST) in S. Korea and George Mason
University in the USA. The research collaborators are Yu Seung Ma, PhD candidate
at KAIST in Korea, Dr. Yong Rae Kwon, Professor at KAIST in Korea, and Dr. Jeff
Offutt, Professor at George Mason University in the USA. Most of the design was by
Jeff and YuSeung, and the original software development was done by
YuSeung. µJava was modified extensively in 2012 and 2013 by Nan Li. Source files
are available on a limited basis to researchers in mutation analysis; please
contact Offutt for more information

We offer µJava on an "as-is" basis as a service to the community. We welcome

comments and feedback, but do not guarantee support in the form of question
answering, fault fixing, or improvements (in other words, we don't have money for
support, just good intentions). This page contains the following:

1. An overview of object-oriented Java and µJava.

2. Links to downloadable files.
3. Detailed description of how to install, set up, and run µJava.
4. References to published papers.

March 2007: Laurie Williams and Ben Smith of NC State have modified µJava to
be an Eclipse plugin. Their version is available from sourcefourge.
I. Overview
µJava was built by Ma, Offutt and Kwon [1]. µJava uses two types of mutation
operators, class level and method level. The class level mutation operators were
designed for Java classes by Ma, Kwon and Offutt [2], and were in turn designed from
a categorization of object-oriented faults by Offutt, Alexander et al. [3]. µJava creates
object-oriented mutants for Java classes according to 24 operators that are specialized
to object-oriented faults. Method level (traditional) mutants are based on the selective
operator set by Offutt et al. [4]. After creating mutants, µJava allows the tester to
enter and run tests, and evaluates the mutation coverage of the tests.

In µJava, tests for the class under test are encoded in separate classes that make calls
to methods in the class under test. Mutants are created and executed automatically.
Equivalent mutants must be identified by hand.

We have separate descriptions for the class-level mutation operators and the method-
level mutation operators used by µJava in PDF.

History

 2003. First released as JMutation (Java Mutation System).

 2004. The name was changed to MuJava (Mutation System for Java).
 2005. Software Copyright Registration, ALL RIGHTS RESERVED.
 2005. Version 2 released with several fault fixes and modified mutation
operators.
 2008. Version 3 released with minimal support for Java 1.5 and 1.6.
 2013. Version 4 released to support JUnit tests and Java 1.6 language features,
including generics, annotations, enumerations, varargs, enhanced for-each
loops, and static imports.
 2015. Additional and improved error messages. Bug fixes for OpenJava.
Licensing changed to the Apache license.

II. Downloading µJava

Although installing µJava is not technically difficult or complicated, it will require a
little more effort than installing many 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.
 mujava.jar µJava system library
openjava.jar OpenJava library that is adapted for µJava (OpenJava WWW page)
mujava.config A file to specifies the µJava system home directory

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\.

µJava was updated in April 2013 to work with JUnit and generics. The old versions
are still available if you need them.

Version 3

mujava-v3.jar µJava system library

openjava2005.jar OpenJava library that is adapted for µJava (OpenJava WWW page)
mujava-v3.config A file to specifies the µJava system home directory

Issues with version 3:

 µJava could not compile classes that use Java generics. (This was corrected in
version 4.)
 Fault fix, 5-December-2011: The program did not properly initialize the time-
out counter, so time-out only worked if users explicitly set it. This
caused µJava to freeze during execution sometimes.
 Fault fix, 6-December-2011: muJava implemented the ROR operator
incorrectly.

µJava was updated in December 2008 to work with Java 1.5 and 1.6. The old versions
are still available if you need them.

Version 2

mujava-v2.jar µJava system library (Updates and fault fixes, May 2006)
adaptedOJ.jar OpenJava library that is adapted for µJava (OpenJava WWW page)
mujava.config A file to specifies the µJava system home directory

The mujava.jar file was updated in May 2006. The old version, mujava-v1.jar, is still
available if you need it.
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] gmu.edu" and we will add the reference to the µJava web page.

Version 1

A new version of µJava was made available in summer 2005. Some of the operators
were modified and numerous fault fixes were made. For completeness, the previous
version is still available, but we recommend that new users use the current version.

Version 1 instructions
Differences between version 1 and version 2
Downloadable files:
jmutation.jar openjavaHelper.jar jmutation.config

III. Using µJava to Test Classes

The muJava system requires that the Java CLASSPATH be modified to include
the muJava jar, the openjava jar, the JUnit library, and and the Java tools.jar files.
Also, the general PATH variable must include the java bin directory; this is usually
set automatically when java was installed, but not always. 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.

i. The Java CLASSPATH must include two µJava jar files and one standard Java
jar file. tools.jar is standard with Java (JDK) compilers and is probably located
in the "JavaHome/lib/" directory. The twoµJava files
are mujava.jar and openjava.jar, which are downloaded from this site.

Windows

In a DOS window, use the following command (assuming that classes is under
C:\mujava):

set CLASSPATH=%CLASSPATH%;C:\mujava\mujava.jar;C:\mujava\openjava.jar;C:\jdk1.7.0\lib\
 tools.jar;C:\mujava\classes

In a Cygwin window, use the following command:

CLASSPATH="$CLASSPATH;C:\mujava\mujava.jar;C:\mujava\openjava.jar;C:\jdk1.7.0\lib\
tools.jar;C:\mujava\classes" ; export CLASSPATH

To change your CLASSPATH permanently in Windows, 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 mujava.jar and openjava.jar to the
CLASSPATH.

Unix

In Unix, set the CLASSPATH environment variable. Assuming the jar files are
stored in the home directory of user mujava:
CLASSPATH=$CLASSPATH:/home/mujava/mujava.jar:/home/mujava/openjava.jar:/
java1.4/jdk1.7.0/lib/tools.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, .bash_profile, or .bashrc.

Mac

Open the Terminal, type "echo $JAVA_HOME" and "echo $PATH" and make
sure the environment variables JAVA_HOME and PATH are correctly set.

If you do not know how to install JDK 7 on a Mac, please read the article
about how to install JDK 7 and how to set up the JAVA_HOME and PATH
environment variables.

ii. Next, modify the mujava.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: MuJava_HOME=C:\home\mujava\exp.

IMPORTANT: It is necessary to copy the config file to the directory you run
the muJava system in.
iii. Finally, create a directory structure for the muJava system in the
$MuJava_HOME directory. Assuming your MuJava_HOME directory is
called MuJava, the subdirectories should look like:

There should be four subdirectories, used in the following ways.

MuJava_HOME\src directory for Java files under test

directory for compiled classes of Java files
MuJava_HOME\classes
from MuJava_HOME\src
MuJava_HOME\testset directory for test sets
MuJava_HOME\result directory for generated mutants

Create these subdirectories by hand or by using the muJava class

"mujava.makeMuJavaStructure".

java mujava.makeMuJavaStructure

Potential problems: We have identified several potential problems with

installing µJava.

 It is important that the MuJava_HOME variable NOT have a trailing slash.

This will confuse µJava.
 If you have a different version of the java compiler and the JVM, µJava may
get confused. This happens sometimes when a new application on your
computer updates the JVM. If you have problems compiling or killing mutants,
we suggest deleting all Java components and reinstalling the latest version.
 If your tools.jar file is out of date (pre Java 1.4, we think), parts of µJava may
not work.

2. Generating Mutants with muJava

Important note: You should run all commands in a directory that contains
"mujava.config"
 i. Put the source files to test to MuJava_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 MuJava_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 MuJava_HOME\src. If the file has a package structure, you should store
the entire package underneath MuJava_HOME\src.
ii. Compile all the Java files in MuJava_HOME\src and copy the .class files into
the MuJava_HOME\classes\ directory.
iii. Start the GUI from the command line. Use it to generate mutants:

java mujava.gui.GenMutantsMain

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

 v.

vi. Select the files you want to mutate by clicking in the boxes on the left. Select
the mutation operators you want to use by selecting their boxes. Then push
RUN.
vii. Note: 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.
viii. After mutants are generated, you can view the mutants in the "Class Mutants
Viewer" and "Traditional Mutants Viewer" tabs, as shown in the following two
figures.
 ix.

x.
 xi.

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

A short shell script will help you run µJava. Below is an example shell script for
windows that creates mutants:

3. Making a test set

A testset in muJava must be a JUnit test case. JUnit test suite is not supported. Each
test is a method that contains a sequence of calls to methods in the class under test.
The test methods and the test class should have public access.

Below is an example of a JUnit test class for the class vendingMachine. Its name
is testVendingMachine. The JUnit .class files should be in the
directory MuJava_HOME\testset\.
4. Running mutants.

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

java mujava.gui.RunTestMain

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 are typically
equivalent.
And the following will run µJava to kill mutants:
Last update: June 2013, Jeff Offutt and Nan Li

Assistance from the U.S. National Science Foundation

under grant CCR-98-04111 to George Mason University
was greatly appreciated.