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+

1. Clone the repository of UniAPR source code.

   git clone https://github.com/ise-uiuc/uniapr.git

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

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=true

You 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_tests

Please 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=true

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