To provide an easy way to get familiar with our projects, we provided a virtual machine image for testing purposes. This virtual machine images are built with all the required dependencies and will be able to work out of the box.
The username and password for the account is regminer, but the virtual machine does not require a password to log in. In addition, the image is currently small to ensure the virtual machine can be downloaded quickly. To test out more projects, it is advisable to expand the storage of the virtual machine so that it is able to store and checkout the projects.
Entering the desktop, the two tools (regminer and CLI) can be found under /home/regminer/Documents. More details on how to use the tools can be found under their respective sections.
Our tools have been tested on the following environments and it is recommended to test it out on a similar environment to ensure that it works as intended.
Ubuntu 18.04 or Ubuntu 20.04 or CentOS 7.9
JDK 8
JDK 11
Maven 3.6+
Python 3+
Both versions of JDK needs to be installed. JDK 8 needs to be the default JDK version. (Instructions)
After setting up the environment, you can download the required files from here:
Regression data (optional)
We provided two projects(univocity-parsers and jsoup) to demo our tool.
RegMiner can be run automatically with just two simple steps.
Step1: Configure the JDK11 path in regminer/miner_jar/run.sh.
<your_JDK11_path> -jar ./miner.jar
Step2: Run tool by start command.
python3 Automation.py
More runtime details could find in logmain file under each project, and regressions out in regression.csv.
Configure further projects list in regminer/project.in. For example,
jsoup
univocity-parsers
fastjson
....
You can use MySql for persistence and statistics by configuring the database in regminer/Automation.py. For example,
append("sql_enable=1")
append("sql_url=jdbc:mysql://10.177.21.179:3306/regression?useSSL=false&allowPublicKeyRetrieval=true&characterEncoding=UTF8")
append("username=root")
append("passwd=123456")
To showcase the possible use cases of the tool, we have also provided a command line interface tool that can help to retrieve and checkout the bugs. The tool can be run with 2 simple steps.
Step 1: Configure the JDK 11 path in CLI/CLI.sh
<your_JDK11_path> -jar ./CLI.jar
Step 2: Run the tool by running CLI.sh
bash CLI.sh
Once the tool is started, it can accept 7 different commands. The commands are as follows:
help - print out a help message containing all the available commands
projects - list out all the projects in the database with known regression bugs
use [project] - use the specified project as the basis for all the other operations
list - list the known regression for the specified project
checkout [idx] - checkout the regression at index idx in the list
similarity - get the similarity score for the regression that has been checked out
exit - exit the tool
A classic flow of how to use the tool is as follows.
Step 1: The user will run the projects command to retrieve an up-to-date list of all the projects that have regression bugs in it. This will allow the user to know which project to operate on.
RegMiner > projects
Retrieving projects... Done
uniVocity/univocity-parsers apache/commons-lang
jhy/jsoup jmrozanec/cron-utils
...
Step 2: After finding an appropriate project to operate on, the user will then specify to the tool to use that project. This will also tell the user how many regression bugs there are for this project.
RegMiner > use uniVocity/univocity-parsers
Using project: univocity/univocity-parsers
Retrieving regressions... 25 regressions found
Step 3: The user can choose to list the regression bugs to see which bug they are interested in. This also provide the testcase which allows the user to know the features that are affected by the regression bug.
RegMiner > list
1. rfc: XXXXX | ric: XXXXX | testcase: XXXXX
2. rfc: XXXXX | ric: XXXXX | testcase: XXXXX
...
Step 4: The user can now checkout one of the bug in the list. This checkout process may take a while, if the repository needs to be cloned. At the end of the checkout process, two paths will be output, where the former is the regression fixing commit directory and the latter is the regression inducing commit directory. These two directories can then be used for further testing if need be.
RegMiner > checkout 10
Checking out univocity/univocity-parsers regression 10
... <git messages> ...
rfc directory: /home/regminer/Documents/miner-space/transfer_cache/univocity_univocity-parsers/rfc
ric directory: /home/regminer/Documents/miner-space/transfer_cache/univocity_univocity-parsers/ric
Step 5: Lastly, the user can run the similarity command to calculate the similarity between the two commits. This is done by recording the code coverage of the two commits and comparing the two runs. More details of this calculation can be found in our paper.
RegMiner > similarity
Calculating similarity score for univocity/univocity-parsers regression bug 10...
Similarity score: 0.6949152542372882