Package org.sonar.java.checks.verifier

Interface CheckVerifier

All Known Implementing Classes:

InternalCheckVerifier, JavaCheckVerifier

public interface CheckVerifier

This interface defines how to use checks (rules) verifiers. Its goal is to provide all the required information to the analyzer to verify the checks' expected behavior.

The starting point to define a verifier is newVerifier(). Then, a configuration can be specified.

It is required to provide to the verifier at least the following:

• A rule, by calling withCheck(JavaFileScanner), or withChecks(JavaFileScanner...)
• A test file, by calling onFile(String), onFiles(String...), or onFiles(Collection)

Methods starting with "verify..." (e.g verifyIssues() ) are the methods which effectively validate the rule. Any of them must be called at the end of the verifier's configuration to trigger the verification. Nothing will happen if one of these method is not called. It uses MultiFileVerifier from sonar-analyzer-commons - test-commons library to verify issues on file.

Method Summary

Modifier and Type	Method	Description
CheckVerifier	addFiles(org.sonar.api.batch.fs.InputFile.Status status, String... filenames)	Adds a collection of files with an expected status to be verified by the given rule(s).
CheckVerifier	addFiles(org.sonar.api.batch.fs.InputFile.Status status, Collection<String> filenames)	Adds a collection of files with an expected status.
static CheckVerifier	newInternalVerifier()	Deprecated, for removal: This API element is subject to removal in a future version. in favor of newVerifier(), which uses the analyzer-commons-test-commons library to verify issues on checks.
static CheckVerifier	newVerifier()	Entry point of check verification.
CheckVerifier	onFile(String filename)	Defines the filename to be verified with the given rule(s).
CheckVerifier	onFiles(String... filenames)	Defines the filenames to be verified with the given rule(s).
CheckVerifier	onFiles(Collection<String> filenames)	Defines a collection of filenames to be verified with the given rule(s).
void	verifyIssueOnFile(String expectedIssueMessage)	Verifies that an issue (only one) is raised directly on the file and not within the content of the file.
void	verifyIssueOnProject(String expectedIssueMessage)	Verifies that an issue (only one) is raised directly on the project, which would include this file, and not within the content of the file.
void	verifyIssues()	Verifies that all the expected issues are correctly raised by the rule(s), at their expected positions and attributes.
void	verifyNoIssues()	Verifies that no issues are raised by the rule(s) on the given file(s).
CheckVerifier	withCache(org.sonar.api.batch.sensor.cache.ReadCache readCache, org.sonar.api.batch.sensor.cache.WriteCache writeCache)	Tells the verifier to feed the check with cached information in its preScan phase.
CheckVerifier	withCheck(JavaFileScanner check)	Defines the check to be verified against at least one test file.
CheckVerifier	withChecks(JavaFileScanner... checks)	Defines the check(s) to be verified against at least one test file.
CheckVerifier	withClassPath(Collection<File> classpath)	Defines the classpath to be used for the verification.
CheckVerifier	withinAndroidContext(boolean inAndroidContext)	Defines whether the current file is an analyzer in an Android context.
CheckVerifier	withJavaVersion(int javaVersionAsInt)	Defines the java version syntax to be used for the verification.
CheckVerifier	withJavaVersion(int javaVersionAsInt, boolean enablePreviewFeatures)	Defines the java version syntax to be used for the verification.
CheckVerifier	withoutSemantic()	Tells the verifier that no bytecode will be provided.

Method Details

newVerifier

static CheckVerifier newVerifier()

Entry point of check verification. Will return a new instance of verifier to be configured.

Returns:

the newly instantiated verifier

newInternalVerifier

@Deprecated(since="7.35",
            forRemoval=true)
static CheckVerifier newInternalVerifier()

Deprecated, for removal: This API element is subject to removal in a future version.

in favor of newVerifier(), which uses the analyzer-commons-test-commons library to verify issues on checks.

In the test file(s), lines on which it is expected to have issues being raised have to be flagged with a comment prefixed by the "Noncompliant" string, followed by some optional details/specificity of the expected issue.

It is possible to specify the absolute line number on which the issue should appear by appending "@<line>" to "Noncompliant". But it is usually better to use the line number relative to the current; this is possible by prefixing the number with either '+' or '-'.

For example, the following comment says that an issue is going to be raised on the following line (@+1) with the given message:

   // Noncompliant@+1 {{do not import "java.util.List"}}
   import java.util.List;
 

Full syntax:

   // Noncompliant@+1 [[startColumn=1;endLine=+1;endColumn=2;effortToFix=4;secondary=3,4]] {{issue message}}
 

Some attributes can also be written using a simplified form, for instance:

   // Noncompliant [[sc=14;ec=42]] {{issue message}}
 

Finally, note that attributes between [[...]] are all optional:

• startColumn (sc): column where the highlight starts
• endLine (el): relative endLine where the highlight ends (i.e. +1), same line if omitted
• endColumn (ec): column where the highlight ends
• effortToFix: the cost to fix as integer
• secondary: a comma-separated list of integers identifying the lines of secondary locations if any

withCheck

CheckVerifier withCheck(JavaFileScanner check)

Defines the check to be verified against at least one test file.

Parameters:

check - the rule to be verified

Returns:

the verifier configured to use the check provided as an argument

withChecks

CheckVerifier withChecks(JavaFileScanner... checks)

Defines the check(s) to be verified against at least one test file.

Parameters:

checks - the rules to be verified

Returns:

the verifier configured to use the checks provided as argument

withClassPath

CheckVerifier withClassPath(Collection<File> classpath)

Defines the classpath to be used for the verification. Usually used when the code of the test files require the knowledge of a particular set of libraries or java compiled classes.

Parameters:

classpath - a collection of files which defines the classes/jars/zips which contains the bytecode to be used as a classpath when executing the rule

Returns:

the verifier configured to use the files provided as argument as classpath

withJavaVersion

CheckVerifier withJavaVersion(int javaVersionAsInt)

Defines the java version syntax to be used for the verification. Usually used when the code of the test files explicitly target a given version (e.g. java 7) where a particular syntax/API has been introduced. Preview features for the specified java version will be disabled by default; use withJavaVersion(int, boolean) to enable or disable preview features associated with the specified java version.

Parameters:

javaVersionAsInt - defines the java language syntax version to be considered during verification, provided as an integer. For instance, for Java 1.7, use '7'. For Java 12, simply '12'.

Returns:

the verifier configured to consider the provided test file(s) as following the syntax of the given java version

withJavaVersion

CheckVerifier withJavaVersion(int javaVersionAsInt,
 boolean enablePreviewFeatures)

Defines the java version syntax to be used for the verification. Usually used when the code of the test files explicitly target a given version (e.g. java 7) where a particular syntax/API has been introduced.

Parameters:

javaVersionAsInt - defines the java language syntax version to be considered during verification, provided as an integer. For instance, for Java 1.7, use '7'. For Java 12, simply '12'.

enablePreviewFeatures - defines if preview features from the specified java version should be enabled or not

Returns:

the verifier configured to consider the provided test file(s) as following the syntax of the given java version

Throws:

IllegalArgumentException - If the enablePreviewFeatures parameter is set to true but javaVersionAsInt is not the latest supported version

withinAndroidContext

CheckVerifier withinAndroidContext(boolean inAndroidContext)

Defines whether the current file is an analyzer in an Android context.

Returns:

the verifier currently configured

onFile

CheckVerifier onFile(String filename)

Defines the filename to be verified with the given rule(s). This file should contain all the "Noncompliant" comments defining the expected issues.

Parameters:

filename - the file to be analyzed

Returns:

the verifier configured to consider the provided test file as the source for the rule(s)

onFiles

CheckVerifier onFiles(String... filenames)

Defines the filenames to be verified with the given rule(s). These files should all contain "Noncompliant" comments defining the expected issues.

Parameters:

filenames - the files to be analyzed

Returns:

the verifier configured to consider the provided test file(s) as source for the rule(s)

onFiles

CheckVerifier onFiles(Collection<String> filenames)

Defines a collection of filenames to be verified with the given rule(s). These files should all contain "Noncompliant" comments defining the expected issues.

Parameters:

filenames - a collection of files to be analyzed

Returns:

the verifier configured to consider the provided test file(s) as source for the rule(s)

addFiles

CheckVerifier addFiles(org.sonar.api.batch.fs.InputFile.Status status,
 String... filenames)

Adds a collection of files with an expected status to be verified by the given rule(s). An exception is thrown if a file by the same filename is already listed to be analyzed.

Parameters:

status - The status of the files to be analyzed

filenames - a collection of files to be analyzed

Returns:

the verifier configured

Throws:

IllegalArgumentException - if a file by the same filename has already been added

addFiles

CheckVerifier addFiles(org.sonar.api.batch.fs.InputFile.Status status,
 Collection<String> filenames)

Adds a collection of files with an expected status. An exception is thrown if a file with the same filename is already listed to be analyzed.

Parameters:

status - The status of the files to be analyzed

filenames - a collection of files to be analyzed

Returns:

the verifier configured

Throws:

IllegalArgumentException - if a file by the same filename has already been added

withoutSemantic

CheckVerifier withoutSemantic()

Tells the verifier that no bytecode will be provided. This method is usually used in combination with verifyNoIssues(), to assert the fact that if no bytecode is provided, the rule will not raise any issues.

Returns:

the verifier configured to consider that no bytecode will be provided for analysis

withCache

CheckVerifier withCache(@Nullable
 org.sonar.api.batch.sensor.cache.ReadCache readCache,
 @Nullable
 org.sonar.api.batch.sensor.cache.WriteCache writeCache)

Tells the verifier to feed the check with cached information in its preScan phase.

Parameters:

readCache - A source of information from previous analyses

writeCache - A place to dump information at the end of the analysis

Returns:

the verifier configured with the caches to use.

verifyIssues

void verifyIssues()

Verifies that all the expected issues are correctly raised by the rule(s), at their expected positions and attributes.

verifyIssueOnFile

void verifyIssueOnFile(String expectedIssueMessage)

Verifies that an issue (only one) is raised directly on the file and not within the content of the file.

Parameters:

expectedIssueMessage - the message to be expected with the issue.

verifyIssueOnProject

void verifyIssueOnProject(String expectedIssueMessage)

Verifies that an issue (only one) is raised directly on the project, which would include this file, and not within the content of the file.

Parameters:

expectedIssueMessage -

verifyNoIssues

void verifyNoIssues()

Verifies that no issues are raised by the rule(s) on the given file(s).