Page tree

Skip to end of metadata
Go to start of metadata

In this section:

Overview

Jtest runs on jtest.data.json data files that are automatically generated by the build system plug-ins. Alternatively, you can manually create a JSON file; see Creating Custom .json Data Files for details.

The JSON file determines the primary testing scope. You can narrow down that scope by using the resource, include, and exclude options.

If a pattern is specified with the resource or include option, resources that do not match this pattern are automatically excluded from analysis.

Modifying the Scope with the resource option

You can modify the scope by specifying the resource pattern with one of the following:

  • the -resource command line option (you can use multiple -resource switches to specify multiple resources)

    -resource [pattern]
  • the jtest.resource setting in the .properties file (separate multiple resources with a comma); see Configuration Overview for details.

    jtest.resource=pattern1,pattern2
  • the Maven or Ant <resource> pattern:

    <resources>
        <resource>pattern1</resource>
        <resource>pattern2</resource>
    </resources>

Syntax of the Resource Pattern

The general syntax of the resource pattern is:

[project name]/[resource path relative to the project]

You can use Ant-style wildcards and other parameters to specify patterns:

ParameterDescription
?Wildcard that matches one character (any character except path separators)
*Wildcard that matches zero or more characters (not including path separators)
**Wildcard that matches zero or more path segments.
/Separator for all operating systems
"[non-alphanumeric characters]"Use quotation marks when resource paths contain spaces or other non-alphanumeric characters.

Examples

If the -resource argument only contains one value, the value is matched against the project name and a wildcard (*) will be used. The following table shows examples of -resource switch usage.

ExpressionResult
-resource ProjectName/srcAnalyzes every file in the selected directory and subdirectories (without wildcards, the complete name of the folder has to be specified).
-resource ProjectName/**/*.javaAnalyzes every Java file from selected project.
-resource **/src/main/java/my/company/*.javaAnalyzes every Java file from the specific subdirectory of every project in current build.
-resource ProjectName/src/main/java/my/company/File.javaAnalyzes the single specified resource.
-resource c:/resource.lst

Analyzes the projects listed in the resource.lst file. Specify one project name per line:
ProjectName1
ProjectName2
Provide the path to the file as a value to the -resource argument.

Resolving the Project Name

The ProjectName value is generated according to following rules:

  • The Ant project name is taken from name property of project tag
  • The Maven project name takes form of groupId:artifactId
  • The Gradle project name is taken from gradle.settings file
  • Project names configured in IDEs are fully maintained

You can customize the Maven and Gradle project names with the projectNameTemplate parameter. See Jtest Goals Reference for Maven and Jtest Tasks Reference for Gradle.

Handling External Resources

Generated paths include the EXT string if the specified scope includes external resources. For example, an analyzed project may include source files from another location that are linked to the project. In the following example the Simple.java file is located within the Demo project, whereas the Money.java file has been added by linking and its location is outside of the project: 

Demo/src/main/java/examples/eval/Simple.java
Demo/EXT/examples/bank/Money.java

Modifying the Scope with the include and exclude Options

You can modify the scope by specifying the include and/or pattern with one of the following:

  • the -include and -exclude command line options

    -include pattern
    -exclude pattern
  • the jtest.include and jtest.include settings in the .properties file; see Configuration Overview for details.

    jtest.include=pattern
    jtest.exclude=pattern
  • the Maven or Ant <resource> pattern

    <include>pattern</include>
    <exclude>pattern</exclude>

(info) If both include and exclude patterns are specified, Jtest analyzes the resources specified with the include option, except the resources that match the exclude pattern.

Syntax of the Include and Exclude Patterns

The inculde or exluce pattern can be defined by specifying one of the following:

  • fully-qualified name of the resource(s)
  • path: [absolute path on disc]

You can use Ant-style wildcards and other parameters to specify patterns:

ParameterDescription
?Wildcard that matches one character (any character except path separators)
*Wildcard that matches zero or more characters (not including path separators)
**Wildcard that matches zero or more path segments.
/Separator
path:Prefix for matching absolute disk path

You can specify a file system path to a list file (*.lst) to include or exclude files in bulk. Each item in the *.lst file is treated as a separate entry.  

Examples

UsageDescription
-include com/**Tests everything in packages that begin with "com".
-include path:**/Bank.javaTests only Bank.java files
-include path:C:/Project/src/**Tests all subfiles and subdirectories of C:/Project/src
-include path:C:/Project/src/*Tests all files in C:/Project/src, but not subdirectories
-include c:/include.lst

Tests all files listed in include.lst. Each line is treated as a single pattern.
Example:
If include.lst contains the following lines:
**/*Account
path:**/Bank.java
It has the same effect as the following command:
-include **/*Account
-include path: **/Bank.java

-exclude **/internal/**Tests everything except classes that have "internal" as part of the package name.

Creating Custom .json Data Files

In typical scenarions, Jtest runs on jtest.data.json data files that are automatically generated by build system plugins. Alternatively, you can manually create a .json file and provide Jtest with the path to that file using the -data command line option (see Running Static Analysis).

To manually create a data file Jtest will use for analysis, run jtestcli with the -project options. By default, an example.data.json file is created in the root of the project configured with the -project.location option, but you can customize the location and name of the .json file using -project.jsonpath.

See Creating a Custom JSON for the list of available options.

Defining File Filters Based on Source Control Data

You can restrict the scope of analysis to locally modified files or to files modified on the current working branch by setting up additional file filters. This allows you to focus on identifying and fixing bugs introduced by your recent code changes before the code is checked in your source control system or merged with the main development stream.

While modifying the default scope allows you to speed up analysis, it may impact violations reported by rules that require information about other resources included in the project. In particular, rules that analyze execution paths, calculate metrics, or check for duplicate code may be prone to reporting false positives or negatives if they have no access to files excluded from the scope.

For this reason, we recommend that you regularly perform full-scope analysis to ensure that all rule violations are detected. One example scenario is that a limited scope is analyzed when working with Jtest on the desktop, while a full-scope analysis is performed during automated builds on a server.

Prerequisites

Analyzing Locally Modified Files

To narrow down the scope of analysis to files that are locally modified, add the following option in your .properties configuration file:

scope.scontrol.files.filter.mode=local

Analyzing Files Modified on the Current Working Branch

To narrow down the scope of analysis to files on the current working branch that differ from the main integration stream, such as "master" or "trunk", add the following option in your .properties configuration file:

scope.scontrol.files.filter.mode=branch

If you want to compare your working branch with another branch or with a specific revision rather than the main integration stream, you need to provide the name or ID of the branch or revision you want to use as reference. The following configuration narrows down the scope of analysis to files on the current working branch that differ from a custom branch/revision:

scope.scontrol.files.filter.mode=branch
scope.scontrol.ref.branch=[name/ID of the custom reference branch/revision]

The scope filter settings configured in the .properties file affect all test configurations.

See Scope and Authorship Settings.

Alternatively, you can define additional scope filters in the test configuration by creating a custom test configuration and specifying the filter you want to apply, see Creating Custom Test Configurations. The scope filter settings configured in the GUI only affect the given test configuration and are overridden by scope filter settings configured in .properties file.


  • No labels