Eve-Notes

This a lib to mutate code annotations from Java or attributes from C# source code. From a set of operators, this will create one javaMutant for each change on original code, related to code annotations. For example, consider the following code (Java):

@RequestMapping(value = "/foo")
public String form() {
  return "form";
}

The ADAT (Add Attribute) operator can create the following javaMutants:

@RequestMapping(value = "/foo", method = RequestMethod.POST)
public String form() {
  return "form";
}

@RequestMapping(value = "/foo", method = RequestMethod.GET)
public String form() {
  return "form";
}

With these javaMutants, the developer can evaluate your test suite. The ultimate goal is kill these javaMutants with tests, improving the test suite. This project was based on theory of Mutation Testing. For more details, see An Analysis and Survey of the Development of Mutation Testing and Mutation Operators for Code Annotations.

Operators

This project have a set of 9 operators:

Operator	Description
ADA	Add annotation
ADAT	Add attributes to annotation
CHODR	Change order of annotations
RMA	Remove annotations
RMAT	Remove attributes of annotations
RPA	Replace one annotation for another
RPAT	Replace one attribute for another
RPAV	Replace one attribute value for another
SWTG	Change location of one annotation

To use this project, it is necessary to choose one or more of these operators.

Configuration

You will need the srcML tool: https://www.srcml.org/. Install on your OS.

First, create a Maven project with java.

On pom.xml, Add the Jitpack repository:

<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

And the Dependency:

<dependencies>
  <dependency>
    <groupId>com.github.easy-software-ufal</groupId>
    <artifactId>mutation-tool-for-annotations</artifactId>
    <version>Tag</version>
  </dependency>
</dependencies>

Replace the Tag with target release.

How to use

First you need to fill the annotations.json of the project (located on the config folder). This is a configuration file, with information of annotations. The following code is a example of this file:

{
  "annotations": [
    {
      "annotation": "@org.springframework.web.bind.annotation.RequestMapping",
      "replaceableBy": [],
      "targets": ["type", "method"],
      "attributes": [
        {
          "name": "value",
          "type": "java.lang.String[]",
          "validValues": ["\"/ex/foo\""],
          "default": "true"
        },
        {
          "name": "method",
          "type": "org.springframework.web.bind.annotation.RequestMethod[]",
          "validValues": ["org.springframework.web.bind.annotation.RequestMethod.POST"]
        },
        {
          "name": "headers",
          "type": "java.lang.String[]",
          "validValues": ["\"content-type=text/*\""]
        }
      ]
    },
    {
      "annotation": "@org.springframework.beans.factory.annotation.Autowired",
      "replaceableBy": ["@org.springframework.beans.factory.annotation.Qualifier"],
      "targets": ["field", "method"],
      "attributes": [{}]
    },
    {
      "annotation": "@org.springframework.beans.factory.annotation.Qualifier",
      "replaceableBy": ["@org.springframework.beans.factory.annotation.Autowired"],
      "targets": ["field", "parameter"],
      "attributes": [{}]
    }
  ]
}

For each annotation, we have the following fields:

annotation: the base of annotation, with @, the package and his name. Mandatory.

replaceableBy: list of replacements of the annotation. Each replacement is a base of annotation, such as the annotation field. Optional.

targets: list of targets of the annotation. Targets are locations where the annotations can be placed. valid values: type, method, field, parameter. Mandatory (at least one target).

attributes: list of attributes of annotations. Optional.

For each attribute, we have the following fields:

name: name of the attribute. Mandatory.

type: type of the attribute. Can be any Java type. Mandatory.

validValues: list of valid values. Mandatory.

default: this mark the attribute as default, which means that the annotation will receive only the value without the attribute name. Only works when the annotation have one attribute. Can be true or false. Optional.

This file is quite similar for C#. The name of attribute include the namespace, without the @.

---

After fill the annotations.json, it is necessary to create a Java code to use this project to generate the javaMutants. The following code is an example:

MutationToolConfig config = new MutationToolConfig(new File(SOURCE_PATH));
config.setProjectName(PROJECT_NAME);
config.getOperators().addAll(Arrays.asList(OperatorsEnum.RMA, OperatorsEnum.RMAT));
config.setThreads(2);
config.setLanguage(Language.JAVA) // or Language.C_SHARP
new MutationTool(config).run();

Basic configuration

The constructor of the MutationToolConfig class have the following field:

pathSources: directory of the source code. This doesn't include the test code.

This class have the following methods:

setProjectName: set the name of original project.

setThreads: set the number of threads.

setLanguage: set the language to generate the mutants (Java or C#).

getOperators: get the list of operators.

Setting the operators

The method getOperators of MutationToolConfig class retrieve the list of operators. It is possible to add operators to this list:

Add all operators

config.getOperators().addAll(Arrays.asList(OperatorsEnum.values()));

Add some operators

config.getOperators().addAll(Arrays.asList(OperatorsEnum.RMA, OperatorsEnum.RMAT));

Generate the javaMutants

The last thing is the use the method run of the MutationTool class:

new MutationTool(config).run();

All the javaMutants will be generated in the data/javaMutants folder.