Page tree

Skip to end of metadata
Go to start of metadata

This topic explains how to run a test from the C/C++test command line interface (cpptestcli), which is described in Command Line Interface (cli).

Sections include:

Prerequisites

The command line mode requires a command line interface license (available with C/C++test Automation Edition).

Extended Command Line Mode vs. Desktop Command Line Mode

There are two command line interface licenses available for C/C++test:

  1. Extended Command Line Mode is provided in Automation Edition and available for Custom Editions.
  2. Desktop Command Line Mode is available for Custom Editions. The Desktop Command Line Mode provides similar functionality to the Extended Command Line Mode, except that parallel processing is limited to simultaneously executing 8 parallel threads for a given task (e.g. static analysis) in the Desktop Command Line Mode.
  • To access the full functionality available with the Automation Edition, you also need to install and configure Parasoft Team Server. 
  • We strongly recommend that you configure C/C++test preferences and team Test Configurations as described in the Configuration before you start testing.
  • For command line execution, you will need to ensure that the installation directory is on the path, or launch cpptest with the full path to the executable (for example, c:\parasoft\c++test\cpptestcli.exe).Before you can test code with C/C++test, it must be added to an Eclipse C/C++ project. For instructions on creating a new project, see Creating a Project.

  • Before you perform the initial test, we strongly recommend that you review and modify project options. For details on how to do this, see Local Settings (Options) Files.
  • For cpptestcli to email each developer a report that contains only the errors/results related to his or her work, one of the following conditions must be true:

    • You have configured C++test to compute code authorship based on source control data AND your project is under a supported source control system AND each developer’s source control username + the mail domain (specified using an options file and the -localsettings option described in -localsettings %LOCALSETTINGS_FILE%) matches the developer’s email address.

    • You have configured C++test to compute code authorship based on local user AND each user name + the mail domain (specified using an options file and the -localsettings option described in -localsettings %LOCALSETTINGS_FILE%) matches the developer’s email address.

Setup Overview

Parasoft C/C++test Professional has two user modes: interactive desktop usage in the GUI and command line mode via the command line interface (CLI). The CLI interface is a standard feature of the Automation Edition. 

CLI mode is typically used to perform regular or continuous code analysis and test in conjunction with regular/continuous builds or as a part of an automatic regression test infrastructure. C/C++test CLI can be invokedon the specified project resourcesAs part of the CLI execution, C/C++test can perform one or more of the following:

  • Static analysis of code, including checks against a configured coding policy, analysis of possible runtime bugs, and metrics analysis.
  • Execution of unit tests

  • Analysis of SCM code repository to identify code changes since the last run and initiate code review sessions on updated code.
  • Generation of reports and their distribution to a central report server and/or to individual developers and managers, according to specified reporting configurations.

As part of the execution, C++test can use your SCM client (if supported) to automatically retrieve file modification information from the SCM system and generate tasks for specific individuals based on results of code analysis and executed tests.

Specific execution options for C/C++test are controlled via Test Configurations and Preferences.

Test Configurations can be sourced from the built in set, or created using C/C++test interactive mode in the GUI. We suggest using the built-in configurations as starting templates for customer-specific configurations.

Preferences can be configured from the C/C++test GUI. Most of the preference settings can also be supplied with a configuration file that is provided as a parameter to a CLI call. A table of the configuration file preference settings is available in Local Settings (Options) Files. C/C++test preferences set from the GUI are applied by default. These can be overridden — on an individual basis—by preference values contained in the configuration file used with a given run. This enables you to have a basic set of preferences configured for all CLI runs, and then vary individual settings as necessary by providing an additional configuration file for a specific run with a given Test Configuration. This can be useful, for example, to include different information in reports for different runs, or to change options for email distribution of reports, including report names, email headings, etc.

Step 1: Configure Preferences

C/C++test preferences are accessed through the Parasoft> Preferences menu. Start by configuring the following preferences:

  • License: Specify the license or License Sever settings.
  • DTP: Specify your DTP server settings.
  • (Optional) Team: Check Enable Team Server. If Team Server is not autodetected, enter the Team Server’s IP address in Server Information> Host Name. If you are running Team Server on the same machine as your C/C++test, enter localhost . Unless you changed the Team Server default port (18888) when it was installed, do not change the port here. Click Test Connection to verify the correct settings.
  • Source Controls: These settings enable automatic mapping of the tool results to the individuals who last changed the affected code or test artifact. Check your source control system, and use the instructions in Connecting to Source Control to set the options appropriate for your SCM.
  • Scope and Authorship: Check the appropriate options for your environment as described in Configuring Task Assignment and Code Authorship Settings.
  • Reports: The following options are enabled by default and are a good starting point:

    • Detailed report for developers (includes task breakdown with details).

    • Overview of tasks by authors (summary table).

    • Generate formatted reports in command line mode.

    • Suppressions Details (applies to static analysis only).

  • E-mails: Enter settings that will be used to send emails with reports. This needs to be an existing email account on an email server accessible from the C++test test machine.

  • Reports> Email Notifications:

    • If desired, enable Send Reports by Email. Regardless of this setting, reports will always be uploaded to Parasoft Team Server for later viewing (controlled by the CLI option). Email distribution will use the settings for E-mails above.

    • Manager reports contain a rollup of all test results generated by C++test Developer reports contain only results for individual developers. Enable options and specify email addresses accordingly.

Step 2: Customize Test Configurations

Create a custom Test Configuration as described in Configuring Test Configurations.

Step 3: Create a localsettings File

Create a localsettings file as described in Local Settings (Options) Files.

Step 4: Activate CLI in the Currently-Running Build System (e.g., batch script)

For example, your command line may resemble the following:

  • cpptestcli -data "c:\MyWorkspace" -resource "ProjectToTest" -config builtin://ShouldHaveRules -publishteamserver -localsettings acme_policy.settings
The reports will be sent after each batch run, and trend reports will be populated with data. The reports will also be available for viewing via Parasoft> Explore> Team Server Reports.

cli Usage

The general procedure for testing from the command line is as follows:

  • Use the cpptestcli utility, with appropriate options, to launch analysis in the command-line mode. A complete list of options is provided in cli Options. Key options are:
    • -data: Specifies the Eclipse workspace location.

    • -config: Specifies Test Configuration.
    • -resource: Specifies the resource (e.g., project, folder, file) to be tested.
    • -publish: Publishes test results to DTP.
    • -publishteamserver: Publishes test results to Team Server.
    • -report: Generates a report.
    • -localsettings: Passes advanced settings for Team Server/Parasoft DTP/mail reporting. Options are described in Local Settings (Options) Files.

Testing Headers

C/C++test does not directly test headers unless they are included by a source file under test. See How do I analyze header files/what files are analyzed? for details.

Testing Template Functions

C/C++test does perform static analysis and unit testing of instantiated function templates and instantiated members of class templates. See Support for Template Functions for details.

Notes for Command Line Testing on Windows

  • C++test does not support file paths specified using Cygwin's "/cygdrive/DISK/PATH" format; instead, use the standard Windows path format.
  • Depending on the shell/console, backslashes in file paths should be escaped/doubled; e.g.,"C:\\MyLocation\\MyFile"
  • All backslashes in file paths must be escaped/doubled when used in options files (with the -localsettings option). Alternatively, you can use forward slashes; e.g., "C:/MyLocation/MyFile".

cli Invocation

The general form of invocation for cpptestcli is:

  • cpptestcli [OPTIONS]

Typically, invocations follow this pattern:

  • cpptestcli -data "c:\MyWorkspace" -resource "ProjectToTest" -config builtin://ShouldHaveRules -publish

Excluding Specific Project Resources from Analysis/Testing

If you want to exclude some files from analysis/testing (for instance, to prevent static analysis of automatically-generated files), you can indicate which project resources should not be tested as described in Excluding Project Resources from Testing. Perform this configuration in the GUI, then the settings will be applied for all tests on this project—from the GUI or from the command line.

Using -data to Specify Your Eclipse Workspace

If you are not in the same directory as the Eclipse workspace that you want to test, you need to use cpptestcli with the -data option. For example, this Windows command tests the C++test Example project by applying the "My Configuration" Test Configuration, generates a report of results, and saves that report in the c:\reports\Report1 directory

cpptestcli -data "c:\Documents and Settings\cynthia\ApplicationData\Parasoft\C++test\workspace" -resource "C++test Example" -config user://"My Configuration" -report c:\reports\Report1

If you are in the same directory as the workspace that you want to test, you can call cpptestcli without the-data option. For example, this Windows command tests the C++test Example project by applying the My Configuration Test Configuration, generates a report of results, and saves that report in the c:\reports\Report1 directory:

cpptestcli -resource "C++test Example" -config user://"My Configuration" -report c:\reports\Report1

cli Options

Available cpptestcli options are listed in the following tables.

General Options

  • -config %CONFIG_URL% - Specifies that you want to run the Test Configuration available at %CONFIG_URL%.
     
    This parameter is required except when importing projects. %CONFIG_URL% is interpreted as a URL, the name of a Test Configuration, or the path to a local file. Examples:
    • By filename:
      -config "mylocalconfig.properties"
    • By URL:
      -config "http://intranet.acme.com/cpptest/team_config.properties"
    • Built-in configurations:
      -config "builtin://Demo Configuration"
      -config "Demo Configuration"
    • User-defined configurations:
      -config "user://My First Configuration"
    • Team configurations:
      -config "team://Team Configuration"
      -config "team://teamconfig.properties"
  • -helpDisplays help information. Does not run testing.
  • -localsettings %LOCALSETTINGS_FILE% - Reads the options file %LOCALSETTINGS_FILE% for global preferences. These settings specify details such as Parasoft DTP settings, email settings, and Team Server settings.
    The options file is a properties file. These files can control reporting preferences (who should reports be sent to, how should those reports be labelled, what mail server and domain should be used, etc.) Team Server settings, Parasoft DTP settings, email settings, and more. For details on creating options files; see Local Settings (Options) Files.
  • -nobuildPrevents C++test from rebuilding the project before testing it. Use this option if the project is already built before the test run.
  • -failFails the build by returning a non-zero exit code if any violations are reported.
  • -publish - Publishes the report to DTP. You can enable sending reports to DTP in the GUI or in the command line mode; see Connecting to DTP.
  • -publishteamserverPublishes the report to the Team Server. The Team Server location can be specified in the GUI or in the options file (described in the -localsettings %LOCALSETTINGS_FILE% entry).
  • -report %REPORT_FILE% - Generates an XML report to the given file %REPORT_FILE% and adds an HTML (or PDF or custom format—if specified using the report.format option) report with the same name (and a different extension) in the same directory.
    All of the following commands will produce an HTML report filename.html and an XML report filename.xml.
    • -report filename.xml
    • -report filename.htm
    • -report filename.html

    If the specified path ends with an ".html"/".htm"/".xml" extension, it will be treated as a path to the report file to generate. Otherwise, it will be treated as a path to a directory where reports should be generated.
    If the file name is explicitly specified in the command and a file with this name already exists in the specified location, the previous report will be overwritten. If your command doesn’t explicitly specify a file name, the existing report file will not be overwritten—the new file will be named repXXXX.html, where XXXX is a random number.
    If the -report option is not specified, reports will be generated with the default names "report.xml/html" in the current directory.

  • -dtp.autoconfig %[email protected]_NAME:port% - Pulls settings stored on the DTP server (recommended for ease of maintenance — especially if you do not already have a locallocally stored settings file). 
    For example:
    -dtp.autoconfig [email protected]:8080

  • -encodepass <plainpassword> - Generates an encoded version of a given password. Prints the message 'Encrypted password: <encpass>' and terminates the cli application.
    If your nightly process will 1) login to Team Server and b) send emails, you can use this option to encrypt the required passwords.

  • -showdetailsPrints detailed test progress information.
  • -buildscript %SCRIPT_FILE% - Executes the specified build script prior to any testing. See Using the cli with an Eclipse-Based Builder.

  • -appconsole stdout|% OUTPUT_FILE%Redirects C++test's console output to standard output or an %OUTPUT_FILE% file. 
    Examples:
    -appconsole stdout (console redirected to the standard output)
    -appconsole console.out (console redirected to console.out file)
  • -list-compilersPrints a list of valid compiler family values. 

  • -list-configs - Prints a list of valid Test Configuration values. 

  • -include %PATTERN%, -exclude %PATTERN% - Specifies files to be included/excluded during testing. 
    You must specify a file name or path after this option.
    Patterns specify file names, with the wildcards *and ? accepted, and the special wildcard ** used to specify one or more path name segments. Syntax for the patterns is similar to that of Ant filesets.
    Examples:
    -include **/Bank.cpp (test Bank.cpp files)

    -include **/ATM/Bank/*.cpp (test all .cpp files in folder ATM/Bank)

    -include c:/ATM/Bank/Bank.cpp (test only the c:/ATM/Bank/Bank.cpp file)

    -exclude **/internal/** (test everything except classes that have path with folder "internal")

    -exclude **/*Test.cpp (test everything, but files that end with Test.cpp)

    Additionally if a pattern is a file with a .lst extension, it is treated as a file with a list of patterns.
    For example, if you use -include c:/include.lst and include.lst contains the following (each line is treated as single pattern):
    **/Bank.cpp

    **/ATM/Bank/*.cpp

    c:/ATM/Bank/Bank.cpp

    then it has same effect as specifying:
    -include **/Bank.cpp -include **/ATM/Bank/*.cpp

    -include c:/ATM/Bank/Bank.cpp"


Options for Importing and Creating Projects

OptionPurposeNotes

-import %ECLIPSE_PROJECT%

Imports the specified Eclipse project(s) into the Eclipse workspace.

If %ECLIPSE_PROJECT% is a .project file, the selected project will be imported

If it is a directory, all Eclipse projects found in the selected directory and subdirectories will be imported.

Examples:

-import \".project\"

-import \"c:\\DevelRootDir\"

The -config option is not necessary while using -import. If the -config option is specified, then the workspace with the imported project(s) will be tested; otherwise, the project will be imported, but no testing will be performed.

-bdf <cpptestscan.bdf>

Creates C++test projects from build data files (.bdf). To prepare a build data file, perform a build of the project with the cpptestscan utility as the prefix for the compiler / linker executable.

Example:

-bdf "cpptestscan.bdf"

See Creating a Project Using an Existing Build System for details. Options can be specified in the options file. See Local Settings (Options) Files for details.

The -config option is not necessary while using -import. If the -config option is specified, then the workspace with the imported project(s) will be tested; otherwise, the project will be imported, but no testing will be performed.

-ccs %CCS_PROJECT%

Imports TI Code Composer Studio projects, If %CCS_PROJECT% is:

pjt project file - the selected project will be imported
directory - all .pjt projects found in selected directory and subdirectories will be imported

Examples:

-ccs "MyProject.pjt"

-ccs "c:\DevelRootDir"

The -config option is not necessary while using -import. If the -config option is specified, then the workspace with the imported project(s) will be tested; otherwise, the project will be imported, but no testing will be performed.

-dsp <.dsp file | .dsw file | root location>

Creates C++test projects from Microsoft Visual Studio projects. Specify a 6.0 project file (.dsp), Microsoft Visual Studio 6.0 workspace file (.dsw), or root directory.

Visual Studio 6.0 project import options can be specified in the options file. See Local Settings (Options) Files for details.

The -config option is not necessary while using -import. If the -config option is specified, then the workspace with the imported project(s) will be tested; otherwise, the project will be imported, but no testing will be performed.

-ewp %EWP_PROJECT%

Imports IAR Embedded Workbench projects. If %EWP_PROJECT% is:
.ewp project file - the selected project will be imported

.eww workspace file - all projects from the workspace will be imported

directory - all .ewp projects found in selected directory and subdirectories will be imported

Examples:

-ewp "MyProject.ewp"

-ewp "MyWorkspace.eww"

-ewp "c:\DevelRootDir"

The -config option is not necessary while using -import. If the -config option is specified, then the workspace with the imported project(s) will be tested; otherwise, the project will be imported, but no testing will be performed.

-gpj <.prj_root_file>

Creates C++test projects from Green Hills .gpj projects.

Green Hills .gpj project import options can be specified in the options file. See Local Settings (Options) Files for details.
The -config option is not necessary while using -import. If the -config option is specified, then the workspace with the imported project(s) will be tested; otherwise, the project will be imported, but no testing will be performed.

-hew %HEW_PROJECT%

Imports Highperformance Embedded Workshop projects. The following can be specified as %HEW_PROJECT%:
.hwp project file: The selected project will be imported.
.hws workspace file: All projects from the workspace will be imported.
directory: All .hwp projects found in the selected directory and subdirectories will be imported

The -config option is not necessary while using -import. If the -config option is specified, then the workspace with the imported project(s) will be tested; otherwise, the project will be imported, but no testing will be performed.

Examples:

-hew "MyProject.hwp"

-hew "MyWorkspace.hws"

-hew "c:\DevelRootDir"

-uv %KEILUV_PROJECT%

Imports Keil uVision3 projects. If %KEILUV_PROJECT% is:

.uv2 project file - the selected project will be imported

directory - all .uv2 projects found in selected directory and subdirectories

The -config option is not necessary while using -import. If the -config option is specified, then the workspace with the imported project(s) will be tested; otherwise, the project will be imported, but no testing will be performed.

Examples:

-uv "MyProject.uv2"

-uv "c:\DevelRootDir"

-vcp %VCP_PROJECT%

Imports Microsoft eMbedded Visual C++ 4.0 projects. If %VCP_PROJECT% is:

.vcp project file - the selected project will be imported

.vcw workspace file - all projects from the workspace will be imported

directory - all .vcp projects found in selected directory and subdirectories will be imported

The -config option is not necessary while using -import. If the -config option is specified, then the workspace with the imported project(s) will be tested; otherwise, the project will be imported, but no testing will be performed.

Examples:

-vcp "MyProject.vcp"

-vcp "MyWorkspace.vcw"

-vcp "c:\DevelRootDir"

-wpj %WPJ_PROJECT%

Imports Wind River Tornado project. If %WPJ_PROJECT% is:

the .wpj project file - selected project will be imported

.wsp workspace file - all projects from the workspace will be imported

directory - all .wpj projects found in selected directory and subdirectories will be imported

The -config option is not necessary while using -import. If the -config option is specified, then the workspace with the imported project(s) will be tested; otherwise, the project will be imported, but no testing will be performed.

Examples:

-wpj "MyProject.wpj"

-wpj "MyWorkspace.wsp"

-wpj "c:\DevelRootDir"

Options for Testing Projects Available in the C++test/Eclipse Workbench

OptionPurposeNotes

-data %WORKSPACE_DIR%

Specifies the location of the Eclipse workspace directory to use.

Defaults to the current user’s dependent directory.

-resource %RESOURCE%

Specifies the path to the workspace resource %RESOURCE% to test.

Use multiple times to specify multiple resources.

Use quotes when the resource path contains spaces or other non-alphanumeric characters.

If %RESOURCE% is a .properties file, the value corresponding to com.parasoft.xtest.checkers.resources will be interpreted as a colon(:)-separated list of resources. Only one properties file can be specified in this way. If %RESOURCE% is a .lst file, each line will be treated as a resource. If no resources are specified on the command line, the complete workspace will be tested.

Team Project Set File (PSF) files are supported for CVS, SVN, Star Team, and other source control systems (depending on the Eclipse plugin capabilities installed).

Paths (even absolute ones) are relative to the workspace specified by the -data parameter.

Examples:

-resource "Acme Project"

-resource "/MyProject/src/com/acme/MyClassTest.java"

-resource "/MyProject/src/com/acme"

-resource testedprojects.properties

Notes

  • To see a list of valid command line options, enter for cpptestcli -help.
  • cpptestcli automatically emails designated group managers and architects a report that lists all team/project errors and identifies which developer is responsible for each error. If no errors are reported, reports will be sent unless the options file contains the report.mail.on.error.only=true option.
  • If the appropriate prerequisites are met, cpptestcli automatically emails each developer a report that contains only the errors/results related to his or her work. If no errors are reported for a particular developer, a report will not be emailed to that developer.

Local Settings (Options) Files

Localsettings files can be passed at the command line to control options for reporting, task assignment, licensing, and more. This allows you to:

  • Configure and use different setting configurations for different projects.
  • Extend or override team-wide settings as needed (for example, for settings that involve local paths).
  • Adjust settings without having to open the GUI.

You can create different options files for different projects, then use the -localsettings option to indicate which file should be used for the current command line test.

See Configuring Localsettings for information about localsettings files and the list of available settings.


Using the cli with an Eclipse-Based Builder

The -buildscript %SCRIPT_FILE% option executes the specified Eclipse build script prior to testing.

In some cases, this may bring up the Eclipse UI. It depends on the Eclipse component capabilities and 3rd party Eclipse source control plugins. Note that if the UI is not opened and the source control is not fully configured, then the 3rd party Eclipse source control plugins may fail in headless mode. They may fail silently or throw various exceptions while trying to access a UI that is not available. To prevent this, have source control fully configured and ensure that it does not need to ask the user for any additional information (username, passwords, etc.)

The following scripting language can be used to define the script...

Syntax

Commands are entered one per line. Whitespace at the beginning or end of the line is trimmed. Any blank line is ignored. Everything following a # comment symbol in a line is ignored. Commands consist of a command name and one or more arguments.

Substrings of the form $(key) are recursively expanded as macros in arguments.

Commands

CommandDescription

var <name> <value>

Defines a variable that will be used in macro expansion.

co </path/to/file.psf>

Checks out projects specified in an Eclipse team project set exported file. Relative paths are resolved relative to the current file (important for included files).

up </path/to/file.psf>

Exactly like co, but if a project is already in the workspace, it will update it rather than checking it out from scratch. Tries to do this "headlessly" but may open a dialog, suspending the checkout until user interaction is given via the UI to resolve the conflict, if local changes are detected.

NOTE: Updating is only supported with CVS and SVN repositories. If the team project set refers to another kind of repository, only checkout is supported at this time.

upb </path/to/file.psf>

Exactly like co, but if a project is already in the workspace, it will update it rather than checking it out from scratch. Same advantages and limitations as "up". Builds all projects in the PSF file after checkout and/or update is complete.

rep </path/to/file.psf>

Exactly like up, but if a project already in the workspace is being updated, it uses a replace operation rather than an update operation. This should overwrite local changes silently.

NOTE: Updating/replacing is only supported with CVS and SVN repositories. If the team project set refers to another kind of repository, only checkout is supported at this time.

repb </path/to/file.psf>

Exactly like upb, but if a project already in the workspace is being updated, it uses a replace operation rather than an update operation. This should overwrite local changes silently. Builds all projects in the PSF file after checkout and/or update is complete.

build [project1[project2[...]]]

Builds the projects whose names are given in the arguments. If no argument is given, builds all projects in the workspace. If the first argument is the string "-", builds all projects in the workspace except the ones listed.

include </path/to/script>

The specified script file will be run. Relative paths are resolved relative to the current file (important for recursive include commands).

ant </path/to/build.xml> [target1[target2 [...]]]

The specified targets (or the default target, if no targets are specified) in the specified ant build file will be run. Relative paths are resolved relative to the current file. Refresh of entire workspace is done after the ant build file is run.

refreshPerforms an Eclipse "refresh" of the entire workspace.

Macros

Strings of the form $(key) in command arguments are expanded. The values used can be from previous var commands or from System properties. System properties can be predefined by Java (e.g. user.home) or passed into the build by running Eclipse with the -vmargs -Dkey=value parameter.

  • No labels