Running the Σοφία Viewers

The viewers are used to display and save interpretable forms of the various output files generated by Σοφία tools. They are provided to facilitate understanding and reporting of the various analyses supported by Σοφία.

CFViewer

This viewer is used to view the control flow graphs produced for the methods in a class. You must first run the control flow graph builder on the class for which you want to view control flow information. Then run the command:

java sofya.viewers.CFViewer [-tag tag] <classname>.java [output_file]

Note that you should include the .java extension. The CFViewer will automatically locate the control flow file in the Σοφία database and display the formatted contents. If you specify a value for output_file, the data will be written to the specified file.

MapViewer

This viewer is used to view the mapping information produced for the methods in a class. This includes a list of the basic blocks in each method, their types, subtypes, bytecode start offsets and bytecode end offsets. You must first run the control flow graph builder on the class for which you want to view map information. Then run the command:

java sofya.viewers.MapViewer [-tag tag] <classname>.java [output_file]

Note that you should include the .java extension. The MapViewer will automatically locate the map file in the Σοφία database and display the formatted contents. If you specify a value for output_file, the data will be written to the specified file.

TraceViewer

This viewer is used to view the trace information collected from the execution of an instrumented program by a coverage tracer. If will display the trace events that were recorded during execution of the program. The type of the trace (currently either basic block or branch) is automatically detected and displayed appropriately. The viewer is run with the following command:

java sofya.viewers.TraceViewer <tracefile> [output_file]

The .tr extension and any qualifying path information should be included. This viewer does not automatically find the trace file in the database directory. It will display the formatted contents of the trace file, unless you specify a value for output_file, in which case the data will be written to the specified file instead.

TestHistoryViewer

This viewer is used to view a test history file generated by the test history builder. There are two possible ways to view a test history file. The first lists each block and the set of tests that exercised it during execution. The second lists each block, the number of tests that exercised it during execution, and the percentage of the total number of tests that exercised it. To use it, run the command:

java sofya.viewers.TestHistoryViewer <histfile> [LIST | COUNT] [output_file]

The LIST option produces the first view of the history file, whereas the COUNT option produces the second view. If specified, the output will be stored to output_file.

TestSelectionViewer

This viewer is used to display the stored results of test selection performed by DejaVu. There are three possible ways to view a test selection file. The first displays each method in the program contributing at least one test selection with a tabular list of all the test selections resulting the changes to that method. The second gives a "statistical" view that lists each method with the total number of tests and the corresponding percentage of the test suite selected as a result of the changes to that method. The final view simply lists all of the selected tests, and is intended primarily as an input to other tools. To use this viewer, run the command:

java sofya.viewers.TestSelectionViewer <selectionfile> [-t <t|s|l>] [output_file]

The parameter -t selects the output format, where t is the tabular format, s is the statistical format, and l is the list format. If you specify a value for output_file, the data will be written to the specified file.

ByteSourceViewer

This viewer is used to view the byte code instructions of a Java class. To use it, run the command:

java sofya.viewers.ByteSourceViewer <classname> [output_file]

If the .class extension is included, the viewer will treat the given name as an absolute path, otherwise it will attempt to load the class from the classpath. It will display the byte code instructions for each method in the class in a readable format. If you specify a value for output_file, the data will be written to the specified file.

SourceViewer

This viewer is used to display the contents of a Java source code file, annotated with line numbers. To use it, run the command:

java sofya.viewers.SourceViewer <sourcefile> [output_file]

The .java extension and any qualifying path information should be included. This viewer does not automatically find the file in the database directory. It will display the contents of the source file, annotated with line numbers. If you specify a value for output_file, the data will be written to the specified file.

Mutation Table Viewer

This viewer is used to display the contents of a Sofya mutation table (.mut or .mut.apl) file. Mutation table files are created by the sofya.mutator.MutationGenerator class. The usage of the MutationTableViewer class is as follows:

java sofya.viewers.MutationTableViewer <mutation_table_file> [-t l/d] [OutputFile]

The mutation_table_file is binary file containing information on one or more Sofya mutation operations that apply to a Java class. The sofya.mutator.MutationGenerator class generates a mutation table (a file with the '.mut' file extension to the class file name, e.g. java.lang.String.mut) in the working directory where MutationGenerator is executed. This viewer allows examination of these mutation table files which report what mutations exist in the class upon which Sofya can perform bytecode mutation. When a mutation is applied using the sofya.mutator.Mutator class, a secondary mutation table file (with the .mut.apl file extension) is created in the working directory. This file contains only information on the mutation applied. The name of this file indicates which class has had the mutation applied. As with other viewers, the OutputFile option is provided for saving the viewer output to the specified file.

The -t flag specifies the type of output desired. Specifying -t l informs the MutationTableViewer to print the specified mutation_table_file in machine readable format, e.g.

$ java sofya.viewers.MutationTableViewer example.ModelParserImpl.mut.apl -t l

31:-:ROP:example.ModelParserImpl:write:(Lexample/VariabilityModel;Ljava/lang/String;Ljava/lang/String;)V:17:0:ifnull[==]:ifnonnull[!=]:1,!=

The output displayed is a script/machine readable format of the fault inserted. For a more human-readable form use the -t d option, e.g.

$ java sofya.viewers.MutationTableViewer example.ModelParserImpl.mut.apl -t d

ROP {
        id: 31
        class: example.ModelParserImpl
        method: write
        signature: (Lexample/VariabilityModel;Ljava/lang/String;Ljava/lang/String;)V
        original code offset: 17
        relative position offset: 0
        opcode mutation: ifnull[==] -> ifnonnull[!=]
        variants: { 1: != }
}

The output displayed gives a more human-readable format to what mutation was (will be) inserted. More information about mutation and mutation viewing is provided in the Toolkit for Generating Java Mutation Faults page.