kGenProg is an Automated Program Repair tool written in Java for Java.
This is a reimplementation of GenProg, which automatically repairs bugs using genetic algorithm.
Requirements
- JDK11+
Installation
Just download a jar file.
There are sample bugs in kusumotolab/kGenProg-example. You can download all the bugs from here.
Gradle
kGenProg is also available for Gradle environments. Currently, kGenProg is distributed on JitPack. To add JitPack repository to your build file, append it in your build.gradle at the end of repositories.
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}Then, please add the dependency to kGenProg.
dependencies {
implementation 'com.github.kusumotolab:kGenProg:Tag'
}Please replace Tag with the version ID that you want to use.
You can find more detailed descriptions here.
Usage
$ java -jar path/to/kGenProg.jar [--config <path> | (-r <path> -s <path>... -t <path>...)]
[-x <fqn>...] [-c <path>...] [-w <path>] [-o <path>] [-v | -q] [--headcount <num>]
[--max-generation <num>] [--time-limit <sec>] [--test-time-limit <sec>]
[--required-solutions <num>] [--random-seed <num>] [--fault-localization <name>]
Example
There are some artificial bugs for testing kGenProg in kGenProg/example. Run kGenProg with the following command for kGenProg/example/CloseToZero01.
$ cd kGenProg/example/CloseToZero01
$ java -jar path/to/kGenProg.jar -r ./ -s src/example/CloseToZero.java -t src/example/CloseToZeroTest.javaYou can configure parameters with a .toml file using --config option.
See docs/kgenprog-config-template.toml to learn how to write a config file.
$ java -jar path/to/kGenProg.jar --config kGenProg/example/CloseToZero01/kgenprog.tomlIf you pass no options, kGenProg reads config file named kgenprog.toml in the current directory.
$ cd kGenProg/example/CloseToZero01
$ java -jar path/to/kGenProg.jarOptions
| Option | Description | Default |
|---|---|---|
--config |
Specifies the path to config file. | Reads config file named kgenprog.toml in the current directory. |
-r, --root-dir |
Specifies the path to the root directory of the target project. It is recommended to specify the current directory after moving into the root directory of the target project, for implementation reason. | Nothing |
-s, --src |
Specifies paths to "product" source code (i.e. main, non-test code), or to directories containing them. Paths are separated with spaces. | Nothing |
-t, --test |
Specifies paths to test source code, or to directories containing them. Paths are separated with spaces. | Nothing |
-x, --exec-test |
Specifies fully qualified names of test classes executed during evaluation of variants (i.e. fix-candidates). It is recommended to specify test classes detecting a bug. Class names are separated with spaces. | All test classes |
-c, --cp |
Specifies class paths needed to build the target project. Paths are separated with spaces. | Nothing |
-o, --out-dir |
Specifies an output directory. Generated files include patches and history json. They can be enabled by --patch-output or --history-record |
./kgenprog-out |
-v, --verbose |
Be more verbose, printing DEBUG level logs. | false |
-q, --quiet |
Be more quiet, suppressing non-ERROR logs. | false |
--mutation-generating-count |
Specifies how many variants are generated in a generation by a mutation. | 10 |
--crossover-generating-count |
Specifies how many variants are generated in a generation by a crossover. | 10 |
--headcount |
Specifies how many variants survive in a generation. | 10 |
--max-generation |
Terminates searching solutions when the specified number of generations reached. | 10 |
--time-limit |
Terminates searching solutions when the specified time in seconds has passed. | 60 |
--test-time-limit |
Specifies a time limit in seconds to build and test each variant. | 10 |
--required-solutions |
Terminates searching solutions when the specified number of solutions are found. | 1 |
--random-seed |
Specifies a random seed used by a random number generator. | 0 |
--scope |
Specifies the scope from which source code to be reused is selected. (PROJECT, PACKAGE, FILE). |
PACKAGE |
--fault-localization |
Specifies technique of fault localization. (Ample, Jaccard, Ochiai, Tarantula, Zoltar). |
Ochiai |
--mutation-type |
Specifies mutation type. (Simple, Heuristic). |
Simple |
--crossover-type |
Specifies crossover type. (Random, Single, Uniform, Cascade). |
Random |
--crossover-first-variant |
Specifies first variant selection strategy for crossover. (Elite, Random). |
Random |
--crossover-second-variant |
Specifies second variant selection strategy for crossover. (Elite, GeneSimilarity, Random, TestSimilarity). |
Random |
--patch-output |
Writes patch files to the output directory specified in -o option. |
false |
--history-record |
Records and writes generation process of all generated variants as JSON format. Note that, this feature significantly reduces overall performance. | false |
--version |
Prints the kGenProg version number. | false |
Use in your research
If you are using kGenProg in your research, please cite the following paper:
Y. Higo, S. Matsumoto, R. Arima, A. Tanikado, K. Naitou, J. Matsumoto, Y. Tomida, and S. Kusumoto, "kGenProg: A High-Performance, High-Extensibility and High-Portability APR System," 2018 25th Asia-Pacific Software Engineering Conference (APSEC), Nara, Japan, 2018, pp. 697-698. [available online]
@Inproceedings{8719559,
author={Y. {Higo} and S. {Matsumoto} and R. {Arima} and A. {Tanikado} and K. {Naitou} and J. {Matsumoto} and Y. {Tomida} and S. {Kusumoto}},
booktitle={2018 25th Asia-Pacific Software Engineering Conference (APSEC)},
title={kGenProg: A High-Performance, High-Extensibility and High-Portability APR System},
year={2018},
pages={697-698},
}
Awards
- Best Poster Award - APSEC 2018
kGenProg: A High-Performance, High-Extensibility and High-Portability APR System