"Changes to documentation of scripts and tarantula files and README.md"

Fault Localization Research 

---------------------------

This repo contains the implementations of two fault localization tools (GZoltar and Tarantula), 

as well as a test program (Triangle).

Test Program: Triangle

----------------------

Triangle.java is a short java program, there is a fault in line 18 of the program.

TestSuite.java is a suite with 33 tests for triangle, the command mvn test should report 4 failed tests.

TestSuite.java is a suite with 33 tests for triangle, running the tests should report 4 failed tests.

GZoltar

-------

GZoltar is one of the fault localization tool in this repo, it can be used as a plugin on Eclipse, for this project 

the GZoltar jar file which will calculate the suspiciousness of lines, it is found in the lib dir. 

GZoltar is one of the fault localization tool in this repo, it can be used as a plugin on Eclipse(which includes the visualization component), 

for this project the GZoltar jar file calculates the suspiciousness of lines, it is found in the lib dir. 

Tarantula

---------

Tarantula is the second fault localization tool in this repo. For this project tacoco is used to obtain a Json format cov matrix of the program

and then calculate suspiciousness of lines using TarantulaMain.java.

Tarantula is the second fault localization tool in this repo. For this project, tacoco is used to obtain a json format coverage matrix of the program.

Next TarantulaMain.java uses the coverage matrix and the test results to calculate suspiciousness of lines.

(Note: Test programs should have their test headers named using the following format test1, test2, test3 ...test33 ect. The Runner.java class in the tarantula

dir will not be able to work unless the headers have the format test#, see the src code in Runner.java for more information)

The github projects for tacoco and primitive hamcrest can be found at https://github.com/spideruci/tacoco & https://github.com/inf295uci-2015/primitive-hamcrest respectively

The github projects for tacoco and primitive hamcrest can be found at https://github.com/spideruci/tacoco & https://github.com/inf295uci-2015/primitive-hamcrest 

respectively although the repos are copied into this project for convenience

TarantulaMain requires several arguments to be run:

	- (1) The cov-matrix in Json format

1. Enter the gzoltar directory

	- cd gzoltar

2. Run Gzoltar: the Gzoltar jar file can be run with the following command

2. Run Gzoltar: the Gzoltar script can be run with the following command

	- ./run-gzoltar ../triangle triangle target/classes/:target/test-classes

	- (Optional) ./run-gzoltar ../triangle triangle target/classes/:target/test-classes | grep "Triangle.java" will print only the suspiciousness for lines in Triangle

3. Generalize; the general form is 

	- ./run-gzoltar project dir test package to execute class/path

	- ./run-gzoltar project dir test-package-to-execute class/path

Evaluating bugs using Tarantula

-------------------------------

1. Enter the fl-scripts dir: All the scripts to run tacoco are held here

	- cd fl-scripts

1. Enter the tacoco-scripts dir: All the scripts to run tacoco are held here

	- cd tacoco-scripts

2. Run Tacoco: The run-tacoco script runs tacoco and creates cp.txt files in both the system-under-test dir and the tacoco dir the script requires the absolute paths of the

the dir to be evaluated and the tacoco directory, see the script for more information 

1. Run Tacoco: The run-tacoco script runs tacoco and creates cp.txt files in both the system-under-test dir and the tacoco dir 

	- ./run-tacoco /absoluteolute/path/to/repo/triangle /absolute/path/to/repo/tacoco

2. Run Jacoco.exec Analyzer: The run-jacoco script creates the jacoco.exec file and the .json files in the tacoco dir, the script will have to be run inside the tacoco dir so you can copy it into the tacoco directory

3. Run Jacoco.exec Analyzer: The run-jacoco script creates the jacoco.exec file and the .json files in the tacoco dir, the script will have to be run inside the tacoco dir so you can copy it into the tacoco directory, see the script for more information 

	- cp -i run-jacoco ../tacoco

	- cd /tacoco/

	- ./run-jacoco /absolute/path/to/repo/triangle triangle /absolute/path/to/repo/tacoco

3. Run TarantulaMain: TarantulaMain requires two args(see the file for more details), the first is the absolute path to the cov-matrix.json file, the second is the name of the Test class, if the test program belongs to a package make sure to specify the package, ex: Triangle.TestSuite

4. Run TarantulaMain: TarantulaMain requires two args(see the file for more details), the first is the absolute path to the cov-matrix.json file, the second is the name of the Test class, if the test program belongs to a package make sure to specify the package, ex: Triangle.TestSuite.

	- java TarantulaMain /absolute/path/to/repo/tacoco/triange-compact-cov-matrix.json TestSuite

	- TarantulaMain can also be run in eclipse simply, copy all the code tarantula dir into a new java project and use the Run Configurations option to allow for command line arguments, another option is to hard code the files and classes, it is also easier (in my opinion) to set the build path since Runner and covMatrixReader both require imports 

	- TarantulaMain can also be run in eclipse simply, copy all the code tarantula dir into a new java project and use the Run Configurations option to allow for command line arguments, another option is to 	     hard code the files and classes, it is also easier (in my opinion) to set the build path since Runner and covMatrixReader both require imports. The needed jars, (junit and json-simple) are found in the 		lib repo or eclipse can easily add them. 

4, Clean the tacoco dir: Run clean-tacoco in order to clean the dir so it can be reused, this means tacoco will have to be recompiled

5. Clean the tacoco dir: Run clean-tacoco in order to clean the dir so it can be reused, this means tacoco will have to be recompiled

	- ./clean-tacoco

	- mvn compile (in tacoco)

	- mvn clean package (in tacoco dir)

Directory Structure

-------------------

	fault-localization-research

		|

		|--- fl-scripts:		Scripts that run tacoco and create the jacoco.exec

		|--- tacoco-scripts:		Scripts that run tacoco and create the jacoco.exec

		|

		|--- gzoltar:			Scripts that run the gzoltar jar file

		|

		|--- lib:			Libraries used in the repo

		|--- lib:			Additional jars or files used in the repo

		|

		|--- primitive-hamcrest:	Repo, used by tacoco

		|

		|

		|--- tarantula:			Source files to obtain the suspiciousness for lines in a program

		|

		|---triangle:			Test program

		|---triangle:			Test program, maven build

#!/bin/bash

# This script removes the files that run-tacoco and clean-tacoco create

# re-compile the tacoco dir after cleaning; mvn compile

# This script removes the files that the run-tacoco and clean-tacoco scripts create

# the user should re-compile the tacoco dir after cleaning; mvn compile or mvn clean package

cd ../tacoco

rm cp.txt jacoco.exec *.json

rm -r target

#!/bin/bash

# This script creates the compact.json file and the compact-cov-matrix.json file, execute this script after run-tacoco

# to be run from within the tacoco dir

# This script needs to to be run from within the tacoco dir, the script can be copied into the tacoco dir

# (Note: do not include an ending backslash for any of the command line arg)

# The command line arg descriptions are as follows: 

# NOTE do not include an ending backslash for any of the command line arg

# $1 command line arg, absolute path of system-under-test's root 

# $2 command line arg, refers to the name of the file/program that is going to be compacted

# $3 command line arg, refers to the absolute path file of the coverage-data-file 

# $2 command line arg, name for the compacted json file, format of ${2}-compact.json 

# $3 command line arg, absolute path file of the coverage-data-file 

# See the tacoco github page for more options on creating the json coverage file

mvn -q exec:java -Panalyzer -Dtacoco.sut=$1 -Dtacoco.json=${2}-compact.json -Dtacoco.exec=jacoco.exec -Dtacoco.pp -Dtacoco.fmt=COMPACT

echo ${2}-compact.json

#!/bin/bash

# This script runs tacoco and creates the neccessary files in both the 

# System-under-test dir and the tacoco dir, this is a copy of the run-tacoco

# script already found in the tacoco dir, placed with the other scripts for 

# convenience since changes cannot be made to the tacoco repo without permission

# This script runs tacoco, the command line arg are as follows:

# NOTE how there are no ending forward slashes at the end of the paths

# $1 command line argument refers to absolute class path of the dir under test

# $2 command line argument refers to absolute class path of the tacoco dir

# run as ./run-tacoco absolute/path/of/your/project/root absolute/path/of/tacoco/root

# (Note: there are no ending forward slashes at the end of the paths)

# the command line arg are as follows:

# $1 - absolute class path of the dir under test

# $2 - absolute class path of the tacoco dir

# example: ./run-tacoco absolute/path/of/your/project/root absolute/path/of/tacoco/root

cd $1

mvn dependency:build-classpath -Dmdep.outputFile="cp.txt"

tarantula

---------

The classes in the tarantula directory are used to take the information from the json file produced by tacoco and from JUnit then

use the information to caculate the supsciousness for the lines of a program using the tarantula technique. Refer to the documentation

The classes in the tarantula directory are used to take the information from the json file produced by tacoco and junit tests on the program and 

then use the information to caculate the supsciousness for the lines of a program using the tarantula technique. Refer to the documentation

in the classes for more information.

TarantulaSuspiciousnessCalculation

Runner

------

This program stores the results from a JUnit test and holds an array of the test case numbers that fail. All

test headers should be as follows test1, test2, test3 ect. Otherwise the runner class will not work properly.

This program stores the results from a junit tests and holds an array of the test case numbers that fail. All

test headers should be as follows test1, test2, test3 ect. Otherwise the Runner will not work properly.

covMatrixReader

---------------

This program reads the json file produces by tacoco and parses the information into the boolean arrays needed by 

TarantulaSuspiciousnessCalculation. The covMatrixReader is used only to parse information from the compact version of the json

file, this is the default when running tacoco.

file, this is the default json format when running tacoco.

TarantulaMain

--------------