Coverage Analyzer User Guide
This document will walk you through how to use the coverage analyzer by goin through an example.
Needed Artifacts: ProgramFiles.zip BuildProject.csh
Step 1:
The first thing you need to do is create an empty directory, (I’ll call mine covAnalyzer) and copy ProgramFiles.zip and BuildProject.csh into the empty directory. Your directory should look like this.
Step 2:
Run the shell script BuildProject.csh by typing the following command at the command prompt: csh BuildProject.csh. If this command gives you problems just unzip the ProgramFiles.zip file (unzip ProgramFiles.zip) Your directory should then contain these files.
Step 3:
The example file we are going to walk through is called code.txt, it should be located in the directory now. Open up code.txt and make sure it contains the following code.
public int DuplicatesM(int A[], int size)
{
int count=0;
int []seen=new int[size];
int next=0;
int flag=0;
for(int i=0; i<size; i++){
for(int k=0;k<next & k<size; k++){
if(A[i]==seen[k])
flag=1;
}
}
return count;
}//Duplicates
***Notice that the example code file only has one complete function/method in it. Your code files must follow the same format. Only one function can be instrumented at a time
Step 4:
Open up the config.properties file. It looks like this. This file contains vital information as it tells the coverageAnalyzer tool the name of the code file to be instrumented as well as give the names of all the generated artifacts of the coverageAnalyzer tool. You can change the CODE_FILE attribute to match your code file name and you can change the names of the generated artifacts to what you want as well. The INST_STMT attribute is instrument string that will be written in the instrumented code, you can change this dependant on your instrumentor class method. The default matches the Instrumentor class method I created for this tool in java(you will see later)
DEBUG_LEVEL=false
//DEBUG_LEVEL=true
CFG_FILE=cfg_file.txt
TRACE_FILE=wbt_trace.txt
RESULT_FILE=result.txt
INST_STMT=Instrumentor.rv
CODE_FILE=code.txt
ICODE_FILE=icode.txt
WBT_DRIVER_FILE=driver.java
The config.properties file must be updated in the coverageAnalyzer.jar file. The shell script setConfigFile.csh will update the coverageAnalyzer.jar file with the current config.properties file in the directory, while the shell script getConfigFile.csh file will copy the config.properties file from the coverageAnalyzer.jar file into the current directory(This will overwrite any copy already in the dir).
Step 5:
Once you have set up the config.properties file and updated it in the jar. You can run the shell script FrontEndrunscript.csh with the following command:
csh FrontEndrunscript.csh This will create the files icode.txt, cfg_file.txt and driver.java. Open up icode.txt and you should see the code in code.txt in its instrumented form. Open up the cfg_file.txt file and you should see this cfg where each pair of numbers represents an edge in the cfg:
1 2 2 3 2 10 3 4 4 5 4 9 5 6 6 7 6 8 7 8 8 4 9 2 10 11
The driver.java file is a java class wrapper that encapsulates the functions in code.txt and icode.txt. It uses the default Instrumentor class implementation located inside coverageAnalyzer.jar. In the next step I will show you how to use this file to create the wbt_trace.txt file.
Step 6:
Open up driver.java. Notice the two methods Duplicates() and iDuplicates(). These two methods respectively contain the same methods in code.txt and icode.txt. Scroll down to the main method of the java program. This is where you add test cases that will build your trace file. This is what the main code looks like:
public static void main(String[] args) throws FileNotFoundException {
driver testDriver = new driver();
/*** Add variables ***/
Instrumentor.openTraceFile("wbt_trace.txt");
//### Add Test Code Here ###
Instrumentor.closeTraceFile();
/*Instrumentor.openTraceFile("wbt_trace.txt");
//### Another Test Case it appends to file. Add as many as you want ###
Instrumentor.closeTraceFile();*/
}
Here is an example test case for this driver:
public static void main(String[] args) throws FileNotFoundException {
driver testDriver = new driver();
/*** Add variables ***/
int [] testA={2,3,4};
int size=3;
Instrumentor.openTraceFile("wbt_trace.txt");
//### Add Test Code Here ###
System.out.println("unInstrumented Method: "+testDriver.DuplicatesM(testA,size));
System.out.println("Instrumented Method: "+testDriver.iDuplicatesM(testA,size));
Instrumentor.closeTraceFile();
/*Instrumentor.openTraceFile("wbt_trace.txt");
//### Another Test Case it appends to file. Add as many as you want ###
Instrumentor.closeTraceFile();*/
}
Save the driver.java file and then run the shell script WBTrunscript.cshwith the following command: cshWBTrunscript.csh. This command compiles the driver.java class, creating the driver.class file and also creates the wbt_trace.txt file. This is screen shot below.
Step 7:
If you open the wbt_trace.txt file you will see the trace through the cfg produced by the driver program. It looks like this:
1 2 3 4 9 2 3 4 9 2 3 4 9 2 10 11
Step 8:
Now we are ready to run the backend and get our coverage results. Run the shell script BackEndrunscript.csh with the following command: cshBackEndrunscript.csh
This will create the result file, result.txt, that contains the coverage metrics.
That’s it, hope it worked!!!
All the source code for the analyzer is packed inside the coverageAnalyzer.jar. In order to view the source type the command jar xf coverageAnalyzer.jar. This will extract the entire jar file which contains src, class files, and other examples.