This page give a step-by-step tutorial how to run DebugPilot

To begin, download eclipse-committers.

1. Open Eclipse and import Microbat:

   • Navigate to File - Import - Git - Projects from Git - Clone URI.

     

   • Copy https://github.com/llmhyy/microbat.git to the URI field.

     

   • Continue with the import process.

     

   • Switch to the branch stepwiseProp.

     

   • Proceed with the import until successful.

2. Configure Microbat:

   • Set up the Java path in Windows - Preferences - Java - Installed JREs.

     

   • In Run - Run Configurations - Java Application - Deploy Instrumentator to Eclipse junit_lib [LinYun] - Environment, change the deploy_dir value to the absolute path of your eclipse\dropins\junit_lib\.

     

   • Open /microbat_instrumentator/src/test/java/microbat/tools/JarPackageTool.java in the Project Explorer, right-click on the main entry function, and run as - java application.

     

     If successful, an instrumentator.jar is generated in your eclipse\dropins\junit_lib\, indicating a successful run.

   • Download and extract files from https://github.com/llmhyy/tregression/tree/master/tregression/dependent_lib, excluding instrumentator.jar. Copy these files to your eclipse\dropins\junit_lib\ path.

   • Copy the generated instrumentator.jar to /microbat/lib.

     

3. Run Microbat:

   • Right-click on Microbat in the Project Explorer - Run as - Eclipse.

     

     This Eclipse instance is referred to as the "child eclipse," while the original Eclipse is the "main eclipse."

   • Add the project you want to use Microbat with in the child eclipse.

   • In the child eclipse, navigate to Windows - Preferences - Microbat Debugging. Configure target project and launch class based on the file you want to debug. Adjust java home path to your Java path and apply the changes.

     

   • Click the icon above to start debugging. Successful execution will display the console and trace as shown below:

     

DebugPilot take one failing tase case and the corresponding output, which assumed to be wrong, as input. After the execution trace of failing test case is generated in Step 1, user are required to provide the output of the program in this step.

First, user need to locate the Output Node of the Program. Output node mean the last executed step of the program and it usually contains the program output varaible or, in other case, throws exception. User need to determine which case it is.

User are expected to provide the above information in Program Output section of DebugPilot Feedback View

First, locate the output node by clicking it in Trace View. The corresponding trace node order will be display in Program Output section of DebugPilot Feedback View:

If the case is that the program generate a wrong variable as output, you should find it from the variable table above. Please drag it into the box in Program Output section:

Important Node: Please make sure that you only make one variable as output

You can also remove the variable by double clicking it

If the case is that the output node should not be executed, such as throwing exception, user can just check the Wrong Branch button to indicate that:

Important Node: Please make sure that you don't include any variable in the Program Section in this case

After you have filling the form in Program Output, you may click the Start DebugPilot button on toolbar to start

DebugPilot will propose a root cause and generate a path in Path View start from the selected output node to the proposed root cause. The path contain a chain of data/control dependency:

1. Data Dependency: If variable a is wrong, then next step to look at will the step where a is defined.
2. Control Dependency: If the step s should not be executed, then next step to look at will be the branch step that determine step s should be executed or not.

User can follow that path to trace back step by step to investigate how the root cause affect program behvior

When using the path, you can find out what to explore by clicking the corresponding row in the avaliable feedbacks table

For example, if we click on the row telling that variable numerator is wrong, then you can go to the step where numerator is defined.

User can debug the program by following the path step by step:

1. If the given prediction is correct, you can go to the next step.

2. If the given prediction is wrong, you can give your own feedback.

DebugPilot is not perfect and it may give wrong predictions. Users may give their own feedback to DebugPilot. It can adapt the information to give a more accurate path. When you are following the path and find out that a wrong prediction is given, you may correct it by making your own feedback in Avaliable Feedbacks section in DebugPilot Feedback View:

For example, DebugPilot make a wrong feedback on Path 4, where it think that trace node 25 should not be executed. You find out that this step should be executed but there is one varaible lastChar is wrong, then you can navigate to Avaliable Feedbacks section, check the corresponding feedback and send this message to DebugPilot by clicking the Give Feedback button at the top-right coner.

As a result, DebugPilot take your advice and generate another path that align with your expectation:

Note: DebugPilot assume user give their feedback whenever they encounter wrong prediction as they follow the path. That mean if user give a correcting feedback on Path 4, DebugPilot will assume the prediction on Path 1,2,3 are accurate.

Here are all kind of feedback user can give:

Feedback Type	Meaning
CORRECT	This step is correct, meaning that the read variables and the control dominator are correct
WRONG PATH	This step should not be exected such that user cannot evaluate whether the variable is correct or not
WRONG VARIABLE	This step contain wrong read variable
ROOT CAUSE	This step is the root cause of the bug

Feel free to explore different possibility of path by trying out different feedback! Because you can always change the feedback back:

For example, user later find out that DebugPilot is already wrong at Path 2, users are able to correct it anytime. So that don't be afraid that you give a wrong feedback.

If you find out the root cause, please give a Root Cause feedback on that step, that will call an end to the debugging process

It is possible to have omission bug, which means the underlying root cause is code missing. In this case you may not find the root cause because it does not exist. When omission bug is encountered, DebugPilot will change to Omission mode.

Omission bug is detected whenever user give a CORRECT feedback. It is because when user is tracing the wrong variable via dependency and suddenly it becomes correct, it means something is missing. DebugPilot will display the range of possible location that the missing code should be located:

For example, trace node 12 is the control dominator of trace node 15, when user give a WRONG BRANCH feedback on trace node 15 and CORRECT feedback on trace node 12. DebugPilot determine that there is a missing code within the range (12, 15) and it is trying help you narrow down the range by proposing possible root cause within the range. In this example, DebugPilot proposed node 14. Please give the feedback accordingly until you find out the place where the code is missing. Range will be narrowed down based on your feedback. When you locate the missing code, please give ROOT CAUSE feedback to end the process.

You can always stop the debugging process by clicking stop button on toolbar