UniAPR is an efficient patch validation framework. Upon this framework, different automatic program repair (APR) techniques can be installed as patch generation add-ons. This has a couple of immediate benefits: (1) one can take advantage of the power of different APR technique each of which is good in handling different kind of bugs; (2) APR research community can focus on developing more and more sophisticated patch generation mechanisms without worrying about the cost of patch validation which dominates end-to-end program repair time.
Before installation, make sure you have the required softwares on your machine:
- Version Control System: Git
- Java Development Kit: JDK 8
- Java Build System: Maven 3+
-
Clone the repository of UniAPR source code.
git clone https://github.com/ise-uiuc/uniapr.git
-
Compile and install the UniAPR jar file to local maven repository. By default, the jar file will be installed to
$HOME/.m2/repository/org/uniapr/uniapr-plugin/1.1/uniapr-plugin-1.1.jar.cd uniapr mvn clean install
Before beginning the patch validation process, you need to set up a patches-pool directory with the appropriate hierarchy under the root path of the project which you want to validate patches for.
For example, let's say you want to validate patches generated for the com.google.javascript.jscomp.ProcessClosurePrimitives class in the Closure project. Under the root path of the Closure project, create a directory named patches-pool with the following structure:
patches-pool
├── 0
│ └── com
│ └── google
│ └── javascript
│ └── jscomp
│ ├── ProcessClosurePrimitives$1.class
│ ├── ProcessClosurePrimitives.class
│ ├── ProcessClosurePrimitives$ProvidedName.class
│ └── ProcessClosurePrimitives$UnrecognizedRequire.class
├── 1
│ └── com
│ └── google
│ └── javascript
│ └── jscomp
│ ├── ProcessClosurePrimitives$1.class
│ ├── ProcessClosurePrimitives.class
│ ├── ProcessClosurePrimitives$ProvidedName.class
│ └── ProcessClosurePrimitives$UnrecognizedRequire.class
...
In the example provided, "0" and "1" can be any numerical value that represents the patch ID. Note that you can include multiple class files in a single patch directory.
To validate patches for a project, run the following command under its root path:
mvn org.uniapr:uniapr-plugin:validate -Dhttps.protocols=TLSv1.2
| Id | Options | Description |
|---|---|---|
| 1 | d4jAllTestsFile | The path of the all_tests file generated by defects4j test command. This option should be specified when validating patches for Defects4J projects. It ensures that UniAPR will run the same set of tests, in the same order, as they are executed by Defects4J. Note that this option has been tested on Defects4J V1.2.0 projects. |
| 2 | restartJVM | Controls whether to launch a new JVM for each patch validation. If set to false, UniAPR will try to validate all patches whithin the same JVM (unless the JVM crashs), which means the side effect of test cases may carry over from one patch to another (refer to the resetJVM option for more information). If this option is set to true, UniAPR will start a new JVM for each patch validation, which will result in a slower process but with improved precision. By default, this setting is set to false. |
| 3 | argLine | Configures JVM options for JVMs spawned by UniAPR. |
| 4 | profilerOnly | Only run the profiler of UniAPR, i.e., executing all the tests found by UniAPR without validating any patches. This setting is mainly used for debugging purposes, such as checking if UniAPR has found the correct set of tests and executes them in the same order as Defects4J. By default, this setting is set to false. |
| 5 | failingTests | The tests that fail in the buggy project (the project that UniAPR is being used to validate). If not specified, UniAPR will first run the profiler to collect the failing tests, and then execute these tests before any other tests during the validation process. |
| 6 | whiteListPrefix | The class name prefix UniAPR used to distinguish application classes from library classes for profiling. By default, groupId of the project will be used as a whitelist prefix. |
| 7 | patchesPool | The name of the directory that holds the patches for UniAPR validation. By default, UniAPR looks for the directory named patches-pool under the base directory. |
| 8 | resetJVM | Turn on or off UniAPR's JVM-reset functionality. If disabled and the restartJVM is set to false, the effects of test case execution may carry over from one patch to another, potentially leading to imprecise results from UniAPR. However, UniAPR will run faster in this mode. By default, this setting is set to false. |
If you do not want to modify the pom.xml in the project for validation, you can directly run and configure UniAPR whithin command line. For example:
mvn org.uniapr:uniapr-plugin:validate -Dhttps.protocols=TLSv1.2 -Dd4jAllTestsFile=all_tests -DrestartJVM=trueYou can also configure UniAPR within the pom.xml file:
<plugin>
<groupId>org.uniapr</groupId>
<artifactId>uniapr-plugin</artifactId>
<version>1.1</version>
<!-- <configuration> -->
(1) <!-- <d4jAllTestsFile>./all_tests</d4jAllTestsFile> -->
(2) <!-- <restartJVM>true</restartJVM> -->
(3) <!-- <argLine>-Xmx8g</argLine> -->
(4) <!-- <profilerOnly>false</profilerOnly> -->
(5) <!-- <failingTests> -->
<!-- <failingTest>fully.qualified.test.Class1::testMethod1</failingTest> -->
<!-- ... -->
<!-- <failingTest>fully.qualified.test.ClassN::testMethodN</failingTest> -->
<!-- </failingTests> -->
(6) <!-- <whiteListPrefix>${project.groupId}</whiteListPrefix> -->
(7) <!-- <patchesPool>patches-pool</patchesPool> -->
(8) <!-- <resetJVM>false</resetJVM> -->
<!-- </configuration> -->
</plugin>The scripts in d4j-maven directory aid in the automatic conversion of Defects4J projects into properly configured maven projects, ensuring that UniAPR's profiler produces consistent test results with Defects4J. Currently, only Defects4J V1.2.0 projects are supported, and support for Defects4J V2.0.0 projects is still underway. For further details, please refer to the README.md in https://github.com/ise-uiuc/uniapr/tree/main/d4j-maven.
The directory example/Lang-6 is an Defects4J maven project created by the script in the d4j-maven directory, containing a preconfigured POM file and a prepared all_tests file (generated by the defects4j test command). We also include the patches generated by CapGen, a mutation-/template-based APR technique, in the example/Lang-6/patches-pool directory. To run the example, you can run the following commands:
cd example/Lang-6
mvn org.uniapr:uniapr-plugin:validate -Dhttps.protocols=TLSv1.2 -Dd4jAllTestsFile=all_testsPlease note that we need to include the option -Dhttps.protocols=TLSv1.2 when invoking Maven to satisfy a security requirement in place since June 2018.
Running UniAPR without JVM-reset feature activated will result in UniAPR failing to find the plausible patch (see the output in example/Lang-6/validateWithoutResetJVM.log). This is due to the fact that test case execution side-effects are being propagated from one patch validation session to another (as UniAPR strives to do all patch validations in the same process as long as it is possible). To mitigate this, you may want to activate JVM-reset feature. In order to run UniAPR with JVM-reset feature activated, the user can either modify the POM file and invoke UniAPR as mentioned before, or simply try the following command:
mvn org.uniapr:uniapr-plugin:validate -Dhttps.protocols=TLSv1.2 -Dd4jAllTestsFile=all_tests -DresetJVM=trueAs the output in example/Lang-6/validateWithResetJVM.log shown, the plausible patch with ID 216 is found successfully by UniAPR.
We have tested the use of UniAPR with Defects4J V1.2.0 projects on our machine. If you encounter any problems, whether in V1.2.0 or V2.0.0 Defects4J projects, please don't hesitate to create an issue to bring it to our attention.