| Chapter 27. Creating a CDD Ranking Report | ||
|---|---|---|
 | Part IV. Graphical User Interface |  |
Table of Contents
Generating a ranking report (see Chapter 12, The rank Command for more information) can be accomplished in the GUI by
either selecting the Rank CDD Coverage button in the Wizard window (see
Chapter 30, Navigating the Wizard Window for details), selecting the File -> Generate -> CDD Ranking Report...
menu option, or using the keyboard shortcut Shift-Cntrl-C. Any of these actions will cause the CDD ranking report wizard
window to be started.
The following subsections describe the various windows used to create a CDD ranking report file. Note that the CDD ranking wizard uses several "pages" to describe the various options to set for creating a CDD ranking report file, using Back and Next buttons on each page for navigation. Clicking on the Back button will not cause previously filled in pages to be reverted to their default values but rather will remain populated with the user's data. Similarly, if a page has been filled in with data and the Back button is clicked and then the Next button is clicked, the page contents are retained. The only way to clear out fields is to click the Cancel button at the bottom of each page and startup the CDD ranking wizard again.
Clicking the Cancel button at any time will cause the CDD ranking wizard to immediately exit. Clicking on the help (?) button at any time will bring up the user documentation for the current page (context sensitive help).
Figure Figure 27.1, “CDD Ranking Option Selection Page” shows the look of this page of the CDD ranking wizard.
The first page of the CDD ranking wizard allows the user to select whether all options should be interactively selected within the GUI or if a file should be read in which contains command-line options to the rank command to use. If the latter is chosen, the contents of that file are read in and are populated in the GUI, but the CDD ranking wizard will continue in the same fashion as the first option, allowing the user to change, remove or add to the options found in that file.
If the Create CDD ranking by interactively selecting options entry is currently selected and the user wishes to not use a command-line file to populate the rest of the CDD ranking pages, simply click on the Next button at the bottom of the page to continue. If the Create CDD ranking by using option file entry is currently selected, the user must either type a valid filename or select one by clicking the Browse... button to the right of the file entry area and select a valid file. Once a valid filename is selected, the Next button will be enabled and the user may then click it to continue to the next page. Note that any filename can be selected (whether it's a valid command file or not). Only valid rank command options found in that file are used to populate the wizard entries. No error message will be displayed if the file does not contain this information.
This page of the CDD ranking wizard allows the user to specify certain options to the ranking command when it is run. The following subsections document each option within this window.
This option is a required field to fill in before the rank command can be run. Simply specify a filename in the entry box or use the Browse... button to help create a filename to save the ranking report file to.
![[Note]](img/note.gif) | Note |
|---|---|
| The Next button will not be enabled until a filename has been specified in the entry box. |
The checkboxes within this frame allow the user to specify an importance value for each coverage metric. The allowed values within the entry box for each metric is a value greater than zero, where all values are relative to each other. In other words, if the weight for line coverage is set to a value of 10 and the weight of toggle coverage is set to a value of 1, it indicates that line coverage should be considered 10x more important for coverage selection purposes than toggle coverage. Changing the various weight values can have an impact on which CDD files are chosen to be included in the "need to run" list and/or the order in which CDD files should be run to maximize the coverage obtained.
By default, all metrics are included (except for assertion coverage) and are given a weight value of 1 (all coverage metrics are considered to be equally important for ranking purposes). To remove a metric from ranking consideration, simply uncheck the checkbox to the left of the metric line.
When a CDD ranking report is generated, the report contains header information and a columnar list of accumulated and per CDD ranking information. If the user is only interested in creating a report that includes the names of the CDD files that are needed to run (and the order to run these CDD files in), checking this option will produce just that, allowing for easier usage in Makefiles or other commands needed to run regression runs.
When the ranking order is being generated, there is output from the rank command concerning the filenames that are being read and when the command is writing to the output file; however, if you would like to know more information about what's going on "under the hood", enabling this option will cause more verbose information to be reported in the output screen, including the amount of time spent executing each phase of the rank process, the number of files selected for ranking in each phase, the number of coverage points hit by selected CDD files for each phase and the number of files excluded from ranking. Leave this box unchecked if this information is not important/interesting to you.
This page allows the user to add all of the CDD files to rank. Since the GUI CDD ranking generation command can be run at any time (even when no CDD files have currently been loaded), the input files to the rank command can be any valid CDD file that can be merged with each other.
As can be seen in the following figure, the window is comprised of a filename listbox in the upper left-hand corner of the page, several buttons that allow for various file selection strategies on the right-hand side of the page, a current file count information bar beneath the listbox, a button to allowing saving the currently setup ranking options to be saved to a file, a button to save any selected "required" CDD files to a file, and a Generate button in the bottom navigation bar.
Adding CDD files to be ranked is performed by clicking on one or more of the buttons on the right-hand side of the page. When files are added to the input file listbox, the current number of CDD files in the listbox are reported in the information bar beneath the listbox.
Next to each filename specified in the input file listbox is a checkbutton that specifies if the associated CDD file should be considered a mandatory CDD file to be ranked (i.e., it cannot be excluded from the list of CDD files that should be run during regression to achieve full coverage). This checkbutton can be set/cleared at any time for any CDD file in the listbox.
The following are the various ways that CDD files can be added to or removed from the input file listbox.
Add File(s)
Clicking this button will bring up a file selection box that will allow the user to select one or more files that will will be added to the input file listbox with the "Required" field left unchecked. This option is useful for selecting certain files within one or more directories to rank.
Add CDDs from Directory
Clicking this button will bring up a directory selection box that will allow the user to specify a directory to load CDD files from. Only files with the ".cdd" extension that exist in this directory will be added to the input file listbox.
Add Currently Opened
Clicking this button will add any CDD files that are currently opened within the GUI into the input file list.
Add Required CDD File(s)
Clicking this button will bring up a file selection box that will allow the user to select one or more files that will be added to the input file listbox with the "Required" field checked.
Add Required CDDs from List
Clicking this button will bring up a file selection box that will allow the user to select a file that contains a list of CDD files to be required for ranking (files will be added into the input file listbox with the "Required" field checked).
Delete
When one or more CDD files are selected in the input file listbox, the Delete button will be enabled. Clicking this button will remove the selected files from the input file listbox. The information bar displaying the number of currently selected CDD files will be updated accordingly.
If desired, any CDD files listed in the input file listbox can be moved to change the order of the input files. However, it should be noted that the input file order will not necessarily have any impact on the CDD ranking order list.
If the user wishes to save the current option/file list setup, click on the Save Options to File... button. This will cause a file save window be displayed where a filename can be chosen and saved to by clicking on the Save button in this window. To cancel the option save, click on the Cancel button in that window.
The generated options file can be used in the Section 27.1, “CDD Ranking Option Selection Page” window or in the command-line call to the rank command's -f option.
If one or more files are labeled as "Required" in the input file listbox, this button will be enabled. Clicking on this button will bring up a "Save As" file selection box. Specifying a filename and clicking on the "Save" button will cause a file by that name to be created that contains a list of all of the CDD files listed as "Required". This file may be used at a later time via the -required-list option to the rank command (if using the rank command on the command-line) or by clicking on the Add Required CDDs from List button in the rank command wizard input file selection page.
After all of the input files have been included (you must include more than one to create a CDD ranking report), the Generate button will be enabled, click on this button to advance to the next page in the CDD ranking wizard where the CDD ranking report command will be run and its output displayed.
The above figure shows an example of output displayed to the CDD ranking command output page. The purpose of this page is to show you the results of the rank command run. If any errors occurred during this run, the output from those errors will be displayed within this page. If the command ran successfully, the Finish button will be enabled at the bottom of the screen.
Additionally, the View the ranking report in the GUI button will be enabled. When clicked, this button will display the created report file in a file viewer which may be read and searched. Click on the window manager "X" button to close the file viewer window. The following figure shows an example of the file viewer window and an example of the report output.
When the user has successfully generated a CDD ranking report, clicking the Finish button will close the CDD ranking report window.
| |  | |
| Chapter 26. Creating an ASCII report file |  | Chapter 28. Navigating the Preferences Window |
