This topic explains how to use C++test to calculate metrics.
|Table of Contents|
C++test 's metrics analysis calculates various code metrics for your code , such as code complexity, coupling between objects, and lack of cohesion, to help you assess your code base and monitor changes. More specifically, calculating and tracking metrics helps you to:
- Better understand code complexity and what other classes a change in the code may affect. This helps you make more informed decisions as to how to modify, refactor, and test it.
- Identify some of the symptoms of poor design and understand potential weak points in the code.
To calculate metrics:
- Review the Built-in> Metrics Test Configuration. If you want to customize the metrics that are checked or their acceptable ranges, create a Test Configuration with your preferred metrics settings.
- For general procedures related to configuring and sharing Test Configurations, see Configuring Test Configurations and Rules for Policies.
- For details on customizing metrics settings, see Customizing Metrics Settings.
- To see the description of a specific metric, right-click it and choose View Documentation from the shortcut menu.
- Start the test using the preferred Test Configuration.
- Review and respond to the metrics calculations.
- Project-level metrics will be reported in the UI and in reports. For more details, see Generating an XML Report with Metrics Data.
- If you configured C++test to report tasks for out of range metrics (by enabling the Test Configuration’s Static> Metrics tab Report tasks for metrics values out of acceptable ranges option), any out of range metrics will be reported in the Fix Static Analysis Violations category of the Quality Tasks view.
- For details, see Reviewing and Responding to Metrics Measurements.
C++test Server edition can generate an XML report with metrics summary information, as well as individual class and method detail data where applicable.
From the GUI
To configure XML metrics reporting from the GUI:
- In the report preferences dialog, enable Add metric details to XML data.
From the Command Line
To configure XML metrics reporting from the command line:
- Modify your local settings file to use the option
- For details on local settings files, see Local Settings (Options) Files.
This topic covers how to analyze C++test’s metrics calculations.
- Accessing Metric Measurements
- Identifying Metrics Out of the Acceptable Range
- Reviewing an Extreme Element
- Learning About the Available Metrics
For tests run in the GUI, metric measurements are reported in the Metrics view. If this is not displayed, choose Parasoft> Show View> Metrics.
In the Metrics view, you can use the project tree to determine what metrics are shown in the Metrics view (project, file, method, etc.). When applicable (e.g., at the file level), you can expand the tree to view children.
Shortcut menu items vary based on the level of metric you are viewing.
Customizing the Metrics View
You can customize the Metrics view in terms of:
- Items shown (all items, items out of recommended ranges, extreme items, items out of standard deviation).
- Resources shown (any resource, any resource in the same project, selected resources only, selected resource and its children).
- Columns displayed (sum, number of items, mean, standard deviation, maximum, extreme, extreme item name).
To customize these options, click the Filters button in top right of the Metrics view, then customize the options available in the dialog that opens.
If you configured C++test to report tasks for out of range metrics (by enabling the Test Configuration’s Static> Metrics tab Report tasks for metrics values out of acceptable ranges option), out of range metrics will be reported in the Fix Static Analysis Violations category of the Quality Tasks view.
Additionally, any metric that is outside of the recommended range will be marked in red in the Metrics view.
For tests run from the command line interface, out of range metrics are reported in the Static Analysis section of the report. If results were sent to Team Server, results can be imported into the GUI as described in Importing Results into the UI. They will then be available in the Fix Static Analysis Violations category of the Quality Tasks view.
For results in the Metrics view, you can focus on the class or method that is reported as an "extreme element" by right-clicking a metric name, then choosing Show extreme items from the shortcut menu.
You can then open the related file by right-clicking the element and choosing Open File.
To see the description of a specific metric, right-click it in the Test Configuration’s Static> Metrics tab, then choose View Documentation from the shortcut menu.
This topic explains how to control metrics calculation and reporting.
Metrics settings can be set in the Test Configuration’s Static> Metrics tab. You can customize options such as:
- The types of metrics checked.
- The acceptable range for metrics.
- Whether metrics results are included in reports and uploaded to Team Server.
- Whether tasks are reported when metrics are found to be outside of the acceptable range.
For details on how to change these settings, see Metrics tab.
Run the Metrics built-in test configuration during analysis to execute metrics analysis rules.
Reviewing Metrics Results
Metrics analysis results are available on DTP server; see Connecting to Development Testing Platform for information how to connect with DTP. Metrics results are not included in local HTML or XML reports generated by C++test.
Customizing Metrics Settings
You can configure metrics using Metrics tab in the DTP test configuration interface. Go to DTP> Report Center> Test Configurations and select a test configuration. Then click the Metrics tab to customize metrics and view metrics documentation. See the Development Testing Platform manual for details.
Setting Metrics Thresholds
You can set upper and lower boundaries so that a static analysis violation is reported if a metric is calculated outside the specified value range. For example, if you want to restrict the number of logical lines in a project, you could configure the Metrics test configuration so that a violation is reported if the Number of Logical Lines metric exceeds the limit.
The Metrics test configuration shipped with C++test includes default threshold values. There are some rules, such as Number of Files (METRIC.NOF), for which thresholds cannot be set.
Metric thresholds can be set using the following methods:
- By using the test configuration interface in DTP.
- By manually editing the test configuration file:
1. Go to Parasoft> Test Configurations> Builtin, right-click a selected test configuration and choose Export... to save the configuration as a .properties file.
2. Open the exported .properties file in an editor and set the
[METRIC.ID].ThresholdEnabledproperty to true.
3. Configure the lower and upper boundaries in the
[METRIC.ID].Threshold propertyaccording to the following format:
[METRIC.ID].Threshold=l [lower boundary value] g [upper boundary value]
4. Save the file and go to Parasoft> Test Configurations.
5. Right-click the User-defined folder, choose the Import... option, browse for the modified test configuration file and click Open.
The following metrics are available:
- Coupling Between Objects [METRIC.CBO]
- McCabe Cyclomatic Complexity [METRIC.CC]
- Ratio of Comments to Number of Logical Lines in files [METRIC.CLLOCRIF]
- Ratio of Comments to Number of Logical Lines in methods [METRIC.CLLOCRIM]
- Ratio of Comments to Number of Logical Lines in types [METRIC.CLLOCRIT]
- Nested If Statements [METRIC.DIF]
- Essential Cyclomatic Complexity [METRIC.ECC]
- Fan Out [METRIC.FO]
- Halstead Difficulty [METRIC.HDIFM]
- Halstead Effort [METRIC.HEFM]
- Halstead Intelligent Content [METRIC.HICM]
- Halstead Program Length [METRIC.HLENM]
- Halstead Program Level [METRIC.HLEVM]
- Halstead Number of Bugs [METRIC.HNOBM]
- Halstead Time to Program [METRIC.HTTPM]
- Halstead Program Vocabulary [METRIC.HVOCM]
- Halstead Program Volume [METRIC.HVOLM]
- Inheritance Depth of Class [METRIC.IDOC]
- Lack of Cohesion [METRIC.LCOM]
- Modified Cyclomatic Complexity [METRIC.MCC]
- Maintainability Index [METRIC.MI]
- Nested Blocks Depth [METRIC.NBD]
- Number of Blank Lines in Files [METRIC.NOBLIF]
- Number of Blank Lines in Methods [METRIC.NOBLIM]
- Number of Blank Lines in Types [METRIC.NOBLIT]
- Number of Classes [METRIC.NOC]
- Number of Comment Lines in Files [METRIC.NOCLIF]
- Number of Comment Lines in Methods [METRIC.NOCLIM]
- Number of Comment Lines in Types [METRIC.NOCLIT]
- Number of Files [METRIC.NOF]
- Number of Logical Lines in Files [METRIC.NOLLOCIF]
- Number of Logical Lines in Methods [METRIC.NOLLOCIM]
- Number of Logical Lines in Types [METRIC.NOLLOCIT]
- Number of Methods in Types [METRIC.NOMIT]
- Number of Parameters of Methods [METRIC.NOPAR]
- Number of Physical Lines in Files [METRIC.NOPLIF]
- Number of Physical Lines in Methods [METRIC.NOPLIM]
- Number of Physical Lines in Types [METRIC.NOPLIT]
- Number of Private Members of Types [METRIC.NOPRIVMIT]
- Number of Protected Members of Types [METRIC.NOPROTMIT]
- Number of Public Members of Types [METRIC.NOPUBMIT]
- Number of Returns in Methods [METRIC.NORET]
- Number of Source Lines in Files [METRIC.NOSLIF]
- Number of Source Lines in Methods [METRIC.NOSLIM]
- Number of Source Lines in Types [METRIC.NOSLIT]
- Number of Types [METRIC.NOT]
- Response for Class [METRIC.RFC]
- Strict Cyclomatic Complexity [METRIC.SCC]
- Weighted Methods of Class [METRIC.WMC]