Make sure the Cucumber version is the same for all Cucumber dependencies.

Thus, we are going to create a template in which we check the Cucumber dependency versions specified in a project’s Maven pom.xml, and report them, if at least one dependency’s version differs from the other ones.

Identifying the dependency versions

There are two ways in Maven to specify dependency versions: either explicitly as for example 4.6.8, or via Maven properties such as ${cucumber.version}.

We’re going to handle only the explicit values: if the texts of the dependency versions are the same, the template won’t match.

Dependency format in pom.xml files

Dependencies in pom.xmls are specified in the following format (in this case specific to Cucumber):

<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-java</artifactId>
    <version>5.6.7</version>
    <!-- ... -->
    <!-- other tags like <scope>, <type> or <exclusions> -->
</dependency>

Template creation

Match a single dependency

To target Cucumber specific dependencies, we’ll start with the following template:

<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>$artifactId$</artifactId>
    <version>$version$</version>
</dependency>

where $artifactId$ and $version$ will match any text.

So far, so good. It matches the dependencies with the io.cucumber group id.

Match multiple dependencies

The next step is to figure out how can we match multiple io.cucumber dependencies, and potentially be able to fetch the version numbers from all of those matched elements.

One straightforward way is to duplicate our template and define separate template variables for their artifact ids and version numbers. This way, the template handles those variables as separate elements, even if their values/texts are the same.

<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>$artifactId$</artifactId>
    <version>$version$</version>
</dependency>
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>$artifactId_2$</artifactId>
    <version>$version_2$</version>
</dependency>

To check if the two version numbers are different, you can add a Script filter for the whole template (otherwise, adding it to a specific variable e.g. $version$, you wouldn’t have access to the other variable, in this case $version_2$):

version.text != version_2.text

This will make the template report dependencies where the two version numbers are different. Note: this doesn’t handle the case when the versions are referenced via Maven properties.

This is great so far, but there are three major problems with this:

• if the <scope> or other extra dependency tags are specified in the tested code, the template won’t match them,
• it matches only and exactly the first two io.cucumber dependencies in the examined file, but doesn’t cover the case when there are more than two of them,
• it matches only consecutive io.cucumber dependencies, but not ones that have other dependencies in-between.

Let’s try to handle these cases.

Extra, optional dependency elements

So far, we had the <groupId>, <artifactId> and <version> tags in our template, but what if there are other tags as well within the dependencies, like <scope>?

One way to define optional extra elements is to add a new tag as a placeholder inside both of our <dependency> tags, so that both are ‘told’ to expect additional tags:

<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>$artifactId$</artifactId>
    <version>$version$</version>
    <$tag$/>
</dependency>
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>$artifactId_2$</artifactId>
    <version>$version_2$</version>
    <$tag2$/>
</dependency>

$tag$ and $tag2$ are also added a Count filter with the [0,inf.] range, so that they indeed become optional.

There is only one problem with this: what if the additional tags are not specified after the groupId, artifactId and version tags in this order, but somewhere between them, or before them?

Now, we could do something like this (each $tag*$ configured with the [0,inf.] range):

<dependency>
    <$tag$/>
    <groupId>io.cucumber</groupId>
    <$tag1$/>
    <artifactId>$artifactId$</artifactId>
    <$tag2$/>
    <version>$version$</version>
    <$tag3$/>
</dependency>
<dependency>
    <$tag4$/>
    <groupId>io.cucumber</groupId>
    <$tag5$/>
    <artifactId>$artifactId_2$</artifactId>
    <$tag6$/>
    <version>$version_2$</version>
    <$tag7$/>
</dependency>

but we can see that this can get out of hand quickly (and has just happened), especially if we want to include even more relevant tags, like <scope>$scope$</scope>, in the template.

We’ll “handle” (rather ignore and work around) it in a Script filter later.

Match more than two dependencies

For now, let’s return to our simpler template. To match more than two io.cucumber dependencies, first, we could go with something like this:

<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>$artifactId$</artifactId>
    <version>$version$</version>
</dependency>
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>$artifactId_2$</artifactId>
    <version>$version_2$</version>
</dependency>
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>$artifactId_3$</artifactId>
    <version>$version_3$</version>
</dependency>

It quickly gets clear that this way, we can match only a fixed number of, and only consecutive dependencies, and handling a varying number of dependencies becomes difficult.

We could go with a template like this:

<$dependency$>
    <groupId>io.cucumber</groupId>
    <artifactId>$artifactId$</artifactId>
    <version>$version$</version>
</$dependency$>

where $dependency$ is added a Count filter with the [2,inf.] range. It would solve the matching of varying number of elements, but would still report only the first matching ones, and moreover the first consecutive matching ones.

Match not only consecutive dependencies

The following snippet (see <$dependency2$/>), to make the template order- and consecutiveness-insensitive, could be one quick solution, but we’ll quickly learn that it doesn’t really does the job for us:

<$dependency1$/>
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>$artifactId$</artifactId>
    <version>$version$</version>
</dependency>
<$dependency2$/>
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>$artifactId_2$</artifactId>
    <version>$version_2$</version>
</dependency>
<$dependency3$/>

Unfortunately, although this partially solves the matching more than two dependencies problem, this also matches dependencies other than io.cucumber via the numbered dependency template variables (dependency1, dependency2 and dependency3).

Furthermore, if we replace the numbered dependency variables with io.cucumber specific ones, we would get a template that matches 5 consecutive io.cucumber dependencies, and we would still have the problem of having to handle their order and non-consecutiveness.

Time to rethink

At this point it is becoming apparent that solving this with a (mostly) static template won’t cut it.

Also, if we want to consider dependency tags in <dependencies> and <dependencyManagement> as well, not even mentioning parent and child poms (which this article won’t discuss), we’ll need a rather programmatic solution, and this is when some Script filtering comes into the picture.

Let’s start over

Let’s establish that we want to report incorrectly versioned dependencies only within the <dependencies> element. That makes our job a bit easier.

The idea is to

• collect all <dependency> tags in the current file
• filter them by io.cucumber groupId
• compare their versions
• report them if they have different versions

The reporting part is a little tricky because in SSR templates either elements represented by template variables or the whole template can be selected as the target to highlight.

That would not necessarily be problematic with a static template, but Script filters return a true or false value, and they cannot register individual issues.

So, although not the most informative way, but we’ll report the <dependencies> element if we find differing Cucumber package versions.

We can start with this template:

<$dependencies$/>

with a Text filter configured as dependencies, or this one:

<$dependencies$>
    <$dependency$/>
</$dependencies$>

with corresponding Text filters configured as dependencies and dependency, and a Count filter with [2,inf.] range for $dependency$.

I will demonstrate a few slightly different solutions, for which we’ll make use of IntelliJ’s PSI API for XML.

The Script filter

We can handle the Script filter from the following perspectives:

• the $dependencies$ variable
• the Complete Match variable

Targeting them from the $dependency$ variable’s perspective would not work, since we’d be able to target only a single <dependency> tag, not all of them.

The $dependencies$ variable

First we need to find out the PSI class of the object that the $dependencies$ variable holds.

A simple way is to log its class with the __log__ variable available in Script filters.

__log__.info(dependencies.getClass())

You’ll get a notification message saying:

so we’ll be able to use XmlTagImpl‘s parent interface type com.intellij.psi.xml.XmlTag.

First, let’s make sure that if, for some reason, the type is not an XmlTag, then the script filter doesn’t throw an exception:

import com.intellij.psi.xml.XmlTag

if (!(dependencies instanceof XmlTag)) return false

In script filters, template variables can be referenced by their names without the enclosing $ symbols.

The next step is to collect all <dependency> tags inside <dependencies>.

We can call dependencies.findSubTags('dependency') to return all <dependency> tags, then to filter by the io.cucumber group id, we can use the following:

var ioCucumberDeps = dependencies
  .findSubTags('dependency')
  .findAll { it.getSubTagText('groupId') == 'io.cucumber' }

In case there is no dependency returned, the template won’t match, so we can just return without a match:

if (ioCucumberDeps.isEmpty()) return false

There are a couple of ways we can go from here:

1) Get one of the dependency versions and use that as a reference when comparing with the rest:

The final step is to retrieve one dependency version, the first one for simplicity, with which we’ll compare the rest of them, and if at least one doesn’t match, code highlighting is necessary:

//Get the <version> tag's text inside the first <dependency> tag
var firstVersion = ioCucumberDeps[0].getSubTagText('version')

a) Filter the complete collection of <dependency> tags by whether their version differs from the reference one. If there is at least one such item, do the highlighting.

!ioCucumberDeps
  .findAll { it.getSubTagText('version') != firstVersion }
  .isEmpty()

b) Find the first dependency whose version differs from the reference one. If one is found, do the highlighting.

ioCucumberDeps
  .drop(1)
  .find { it.getSubTagText('version') != firstVersion } != null

2) Use unique() from groovy collections to determine whether there is a different version.

ioCucumberDeps.unique { it.getSubTagText('version') }.size > 1

Using the latter comparison logic, the complete filter will look like this:

import com.intellij.psi.xml.XmlTag

if (!(dependencies instanceof XmlTag)) return false
var ioCucumberDeps = dependencies
    .findSubTags('dependency')
    .findAll { it.getSubTagText('groupId') == 'io.cucumber' }
if (ioCucumberDeps.isEmpty()) return false
ioCucumberDeps.unique { it.getSubTagText('version') }.size > 1

The Complete Match variable

This solution is very similar to the previous one. The only difference is in how the <dependency> tags are collected. While in the previous version, they were retrieved as the sub tags of <dependencies>, here we are handed them automatically via the $dependency$ variable.

It is important to mention that the type of PSI object $dependency$ holds is different when the Script filter is used in the Complete Match variable compared to when it is used in $dependency$.

In case of $dependency$, it would be an XmlTag, while in the Complete Match variable, it is an java.util.ArrayList of XmlTags (the <dependency> tags in this case), since the context the variable sees is broader.

Based on this information, only the beginning of our previous Script filter becomes slightly different, to handle the different variable type:

import java.util.List

if (!(dependency instanceof List)) return false
var ioCucumberDeps =
  dependency
    .findAll { it.getSubTagText('groupId') == 'io.cucumber' }

So, the complete Script filter looks like this:

import java.util.List

if (!(dependency instanceof List)) return false
var ioCucumberDeps =
  dependency
    .findAll { it.getSubTagText('groupId') == 'io.cucumber' }
if (ioCucumberDeps.isEmpty()) return false
ioCucumberDeps.unique { it.getSubTagText('version') }.size > 1

Closing thoughts

Of course, there may be other various ways of building the Script filter, additional logic to handle different edge cases, Maven properties, dependencies within <dependencyManagement>, and more, but I wanted to keep this article fairly simple. (I’m saying this after I wrote a short novel worth of material in this article :)).

I might delve into those aspects in the future, but can’t make any promises.

You can also find details about XML and HTML based templates in the IntelliJ and other IDE documentations.

First off, to be able to create a template for these markup languages, you need to select XML, HTML or one of their dialects from the language dropdown, if you are going for a specific document type.

XML templates

Tags

You can define a tag just like in XML, as <tag>, or, if you want to make the tag name customizable, define it using a template variable, as <$tag$>.

The following examples all match both self-closing tags, and the opening tag (practically the complete tag) of <tag></tag> elements:

<$tag$>
<$tag$/>
<$tag$></$tag$>

Distinguishing between ordinary and self-closing tags is not possible.

For now, it also seems that targeting the closing tag of an element is not possible either. Trying to target it using a template variable, either doesn’t match anything, or matches the whole element, including the opening tag.

Editor convenience

Just like in actual XML documents, when either the opening or closing tag is modified, the corresponding opening or closing tag is modified too.

Partial tag names and namespaces

If you want to specify tags mixed with literal value and template variable, for example <xs:$tag$/>, it is considered an invalid template. You have to go with <$tag$/> as the template, and a Text filter for $tag$.

When it comes to targeting namespaces, they aren’t any different from ordinary tags. The tag name is just a text, so you can simply specify them, given an xs namespace, as <xs:element/> or <$tag$> with a Text filter with value xs:element.

XML Prolog

Unfortunately, XML prologs like <?xml version="1.0" encoding="UTF-8" ?> don’t seem to be supported, not even in this simple format: <?xml ?>, or as a Text filter value “\?xml \?” for the template <$prolog$>.

Attributes

You can define XML attributes in two ways, either as

<$tag$ $attribute$>

or, if you are also interested in the attribute value, then as

<$tag$ $attribute$="$value$">

Attribute count

When it comes to specifying the attribute count, it works the following way:

• by default (without a Count filter on $attribute$) it finds tags with any number of attributes,
• if one specifies a Count filter, it finds tags according to that filter.

However, there is a little trickery. Let’s say, you add a Count filter with [2,inf] as value. If $attribute$ is selected as target, the template highlights any attribute, not just tags that contain at least 2 attributes. Having the $tag$ or $value$ as target, it works properly.

NOTE: whether this is a bug, or is expected, given that it’s the combination of a template variable as target and a filter on that same variable, is not clear yet.

Attribute values

As mentioned in the previous section, tags with attribute values can be specified as

<$tag$ $attribute$="$value$">

However,

<$tag$ $attribute$=$value$>

without double-quotes around the value, is considered an invalid template, and the template editor gives you an Attribute value expected error message.

If you have attribute values, in which certain characters are escaped, for example

<pluginProperties location="settings &gt; editor" .../>

you can target them as simple text

<$tag$ $attribute$="settings &gt; editor"/>

Tag values

In its almost simplest form, <$tag$></$tag$>, the template matches any tag with or without an actual value, and with or without embedded tags.

You can narrow down the results by specifying an actual value as <$tag$>$value$</$tag$>, which, by default, will match tags with a value, but not with embedded tags.

You can also define a Count filter for the value:

• using [0,inf] matches tags with/without a value/embedded tag/comment
• using [1,inf] matches tags with at least one value/embedded tag/comment
• using greater than 1 as the minimum value matches tags with a value, or at least the specified number of embedded tags/comment

A non-zero minimum count makes sense only in case of embedded tags and comments, since each of them counts as a separate element.

Embedded tags

It is kind of straightforward to target embedded tags, for example as

<$tag$><$embtag$></$tag$><$tag$><$embtag$></$embtag$></$tag$>

however, in their default states, these templates don’t seem to match with anything.

To actually match, one has to add a Count filter with at least 0 as its minimum value.

Comments

Comments may be targeted using the

<!--$comment$-->

template. The presence of whitespaces around the template variable is optional, it works even as <!-- $comment$ -->. However, it doesn’t match anything without the variable, in the <!-- --> form.

HTML templates

DOCTYPE

I tried to match them as <!DOCTYPE >, and with attributes as well, <!DOCTYPE $attribute$>, even with a Count filter, but they don’t seem to be supported.

Case-sensitivity

Tags in both XML and HTML documents match in a case-sensitive way, the case of tag names does matter.

Special predefined templates

There is a predefined template in the Structural search editor called <li> not contained in <ul> or <ol>, which uses a filter type that is not available for customization on the UI.

I mentioned more details about this in the post called Contained in constraints.

According to the official documentation:

The Reference filter lets you reference some other search template in the variable.

Configuration

The reference will always contain the name of a preconfigured or saved template, and you can use auto-completion to fill out this field.

One example is the method calls to deprecated methods existing template:

$Instance$.$MethodCall$($Parameter$)

with its XML representation:

<searchConfiguration
    name="method calls to deprecated methods"
    text="$Instance$.$MethodCall$($Parameter$)"
    recursive="true"
    caseInsensitive="true"
    type="JAVA"
    pattern_context="default">
    <constraint name="__context__" within="" contains="" />
    <constraint
        name="Instance"
        minCount="0"
        within=""
        contains="" />
    <constraint
        name="MethodCall"
        reference="deprecated methods" target="true"
        within=""
        contains="" />
    <constraint
        name="Parameter"
        minCount="0"
        maxCount="2147483647"
        within=""
        contains="" />
</searchConfiguration>

You can see that the $MethodCalls$ variable stores as reference the name of the deprecated methods existing template, whose template text is:

@Deprecated
$ReturnType$ $Method$($ParameterType$ $Parameter$);

Selecting a template as Reference filter

When editing a Reference filter of a template variable, a code-completion list is displayed upon typing, and can also be triggered using the Ctrl+Space shortcut key.

This list displays all templates found for the typed keyword, not only the ones that may actually be valid/usable for the given template variable’s actual type.

Invert condition

You can invert the condition by adding an ! (exclamation mark) at the beginning of the filter value, like !deprecated methods, which in the XML representation adds the negateReference="true" attribute to the template:

<constraint
    name="MethodCall"
    reference="deprecated methods"
    target="true"
    negateReference="true"
    within=""
    contains="" />

This will find all non-deprecated method calls.

Referencing between languages

Referencing also works between different programming/markup languages. If you take, for instance, the existing template called xml attribute referencing Java class:

<$tag$ $attribute$="$value$"/>

it, in its $value$ variable, references the template called classes, interfaces & enums:

class $ClassInterfaceEnum$ {}

To also give an actual example, this template will mark the following XML snippet:

<sometag attr="com.myproject.AwesomeClass" />

but not

<sometag attr="AwesomeClass" />

so in this case, it must be defined with the fully qualified name in order to match.

“Invalid” templates as References

When one selects as a reference a template that is not applicable for the template variable (or the underlying PSI element), nothing will happen, simply the template will not match against any code snippet.

Reference filter UI

If you are interested in the Reference filter’s UI structure you can check out the com.intellij.structuralsearch.plugin.ui.filters package, specifically the class ReferenceFilter.

Closing thoughts

There are a few uncertainties as to how exactly the Reference filter works under the hood, so please take the contents of this article with a grain of salt, and if you encounter different behaviour somewhere, please let me know.

Templates sidebar

The list of all templates is now available on the sidebar, instead of in a separate dialog. It is much easier to use those templates, and at the same time it kind of encourages users to use them because they are just right there.

One tiny but nice aspect that I want to highlight is, when you select a language, and that language
has templates in the sidebar, that language folder becomes highlighted/selected.

Pin dialog

There is a new Pin Dialog icon at top right, so that when the users perform a search, the dialog remains open.

This change is very welcome, especially in light of that by default the Search Structurally… menu action doesn’t have a shortcut key assigned, thus it was cumbersome to open the dialog again.

Code completion in Script filters

Although I don’t know if this change was added in EAP 6 or sometime earlier (maybe way earlier), it is nice to see that coding in the Script filter dialog can be a pleasant experience.

The Script filter editor can provide code completion in the following cases that I noticed so far:

• language keywords
• live templates
• types from the current project’s classpath

The last item is especially useful, since in many cases, when it comes to implementing complex Script filters, one has to work with the IntelliJ Platform’s code base.

Now, since the types are available only from the project’s classpath, to have code completion for types in the IntelliJ Platform, one has to use the Search and Replace dialog in an IntelliJ plugin project.

This may be a little inconvenient, but of course, the lack of code completion does not affect the functionality of the Script filter, only the user experience during implementation.

One prominent issue was that entire unit test methods were wrapped in try-catch(Exception) blocks, and the only thing the catch blocks did was to log an error.

Example:

@Test
public void shouldTestSomething() {
    try {
        //do stuff
        //do another stuff
        //do something else
    } catch (Exception e) {
        LOG.error("Some not that specific error message", e);
    }
}

This, of course, is not a good practice because it covers up all problems that occur during test execution, resulting in false positives.

The solution: use assertTrue(true). The result: green tests, nice reports, job done, everyone happy. The End

Due to the state of the project, creating an IntelliJ plugin would have been an overkill, so I turned to the SSR templates with the aim to push them to the project’s git repository within the .idea folder. It took me a total of 3 minutes to compose the template.

You can find the XML representation of this template on GitHub.

It basically targets JUnit @Test methods whose entire contents are wrapped in try-catch blocks catching any type of exception, and handling it only by logging something with slf4j.

My first thought was to have the method name highlighted which is subtle but visible enough to be noticed.

BUT… given that this issue was quite reoccurring, I decided to have the whole body (the $statements$ variable) of the try block highlighted to make engineers annoyed enough, so that they want to deal with it somehow: either by fixing it, OR in worse case, figuring out how to turn off this inspection.

Whether my evil plan worked, I can only hope. (evil laugh)

• boxed expressions
• unboxed expressions
• boxing in method calls
• unboxing in method calls

In the editor it is displayed as Expected type, while in the XML representation it is called nameOfFormalType. Given the template called boxed expressions, it looks like as follows:

Editor:

XML template:

<searchConfiguration
    name="boxed expressions"
    text="$expression$"
    recursive="true"
    caseInsensitive="true"
    type="JAVA"
    pattern_context="default">
    <constraint name="__context__" within="" contains="" />
    <constraint
        name="expression"
        nameOfExprType="int|boolean|long|char|short|byte"
        nameOfFormalType="Object|Integer|Boolean|Long|Character|Short|Byte" within="" contains="" />
</searchConfiguration>

This value can be a regular expression (like the one above), the name of a type (Boolean), or a fully qualified name of a type (com.project.SomeType, or the one below):

<searchConfiguration
    name="boxed expressions"
    text="$expression$"
    recursive="true"
    caseInsensitive="true"
    type="JAVA"
    pattern_context="default">
    <constraint name="__context__" within="" contains="" />
    <constraint
        name="expression"
        nameOfExprType="int"
        nameOfFormalType="java.lang.Integer"
        within=""
        contains="" />
</searchConfiguration>

You can find some configuration logic in the class com.intellij.structuralsearch.MatchVariableConstraint within the intellij-community GitHub project.

Negate the expression

It is also possible negate the expression, although not via the editor, which will search for any other type(s) than the specified one(s).

You can add the negateFormalType attribute to the desired template variable as negateFormalType="true":

<searchConfiguration
    name="boxed expressions"
    text="$expression$"
    recursive="true"
    caseInsensitive="true"
    type="JAVA"
    pattern_context="default">
    <constraint name="__context__" within="" contains="" />
    <constraint
        name="expression"
        nameOfExprType="int|boolean|long|char|short|byte"
        nameOfFormalType="Object|Integer|Boolean|Long|Character|Short|Byte"
        negateFormalType="true"
        within=""
        contains="" />
</searchConfiguration>

Expected type filter without a Type filter

The Expected type filter works without the regular Type filter too, in that case given the following simple template text and code snippet:

$expression$

Integer number = 32;

the highlighted part will be 32.

Casting

As it turns out, besides boxing/unboxing, the Expected type filter works for regular casting as well.

Let’s say you have a class and a subclass of it:

class SuperClass {
}

class SubClass extends SuperClass {
}

With the following template configuration:

<searchConfiguration
    name="Casting to SubClass"
    text="$expression$"
    recursive="true"
    caseInsensitive="true"
    type="JAVA"
    pattern_context="default">
    <constraint name="__context__" within="" contains="" />
    <constraint
        name="expression"
        nameOfExprType="com\.project\.SuperClass"
        nameOfFormalType="com.project.SubClass"
        within=""
        contains="" />
</searchConfiguration>

• Type filter value: com.project.SuperClass (on the UI), com\.project\.SuperClass (in the XML)
• Expected type filter value: com.project.SubClass

the following code snippet, specifically the superClass expression, will be marked as problematic:

SuperClass superClass = new SubClass();
SubClass subClass = (SubClass) superClass;

Within hierarchy

Setting the formalTypeWithinHierarchy="true" constraint attribute as well, any target type within a class’s hierarchy will also be taken into account.

So, for example, using the previous examples and having one additional class:

class SubSubClass extends SubClass {
}

both of the following superClass expressions will be highlighted:

SuperClass superClass = new SubClass();

SubClass subClass = (SubClass) superClass;
SubSubClass subSubClass = (SubSubClass) superClass;

Additional resources

If you are looking for how the Existing templates are configured under the hood, you can look into com.intellij.structuralsearch.JavaPredefinedConfigurations
in the intellij-community GitHub project.

If you want to know more about other hidden filter types, you can also check out the article called Contained in constraints.

And meanwhile it has been fixed in IDEA-243232, see GitHub commit as well, and is now available and works in IntelliJ 2020.2.

Indexed variables

Let’s say you’d like to standardize AssertJ assertions for collections, and you want to replace calls like

Assertions.assertThat(aCollection).size().isGreaterThan(5);

to

Assertions.assertThat(aCollection).hasSizeGreaterThan(5);

The problem is that there are multiple size assertions for collections, but you don’t want to create a separate template for each assertion, rather handle all of them unified in one template. This saves you time of implementing and maintaining this inspection, and saves anyone time and effort to include them in their projects, and later potentially update them when/if necessary.

In case of creating separate inspections for each of them, a template would look something like this:

Search template:

org.assertj.core.api.Assertions.assertThat($collection$).size().isGreaterThan($value$);

Replace template:

org.assertj.core.api.Assertions.assertThat($collection$).hasSizeGreaterThan($value$);

But when it comes to unifying all possible cases you can go with a template like this:

Search template:

org.assertj.core.api.Assertions.assertThat($collection$).size().$assertion$($value$);

where a Text Filter is added to $assertion$ with value is(.*), or if you want to be more specific you can include all possible values in the capturing group.

Replace template:

org.assertj.core.api.Assertions.assertThat($collection$).hasSize$assertion_1$($value$);

Then, in the replace template you replace $assertion$ with hasSize$assertion_1$, where $assertion_1$ will be resolved to the value of the first capturing from $assertion$‘s Text Filter.

So, it doesn’t matter if the assertion is isLessThan(), isGreaterThan(), or something else, it will be replaced with the appropriate hasSize...() assertion.

Any number is allowed as the index of a variable (the index of the capturing group), starting from 1.

One important note is that, although the returned value of replacement variables can be defined via Script filters, in this case make sure that you don’t add a Script filter for the variable, just define the variable in the Replacement part of the template.

The XML below is a complete replace template for the inspection in this section:

<replaceConfiguration
    name="AssertJ size assertion"
    text="org.assertj.core.api.Assertions.assertThat($collection$).size().$assertion$($value$);"
    recursive="false"
    caseInsensitive="true"
    type="JAVA"
    pattern_context="default"
    reformatAccordingToStyle="true"
    shortenFQN="true"
    replacement="org.assertj.core.api.Assertions.assertThat($collection$).hasSize$assertion_1$($value$);">
  <constraint name="__context__" within="" contains="" />
  <constraint name="collection" within="" contains="" />
  <constraint name="value" within="" contains="" />
  <constraint name="assertion" regexp="is(.*)" within="" contains="" />
  <variableDefinition name="assertion_1" />
</replaceConfiguration>

Resolving capturing groups in non-Text Filters

Besides Text filters, regex capturing groups defined in the values of Type Filters can also be resolved by indexed replacement variables.

But make sure that the Regex checkbox is ticked on the UI for the Type Filter.

Not supported features

Variables for named capturing groups

Named capturing groups are not supported at the moment, but it may have some potential to have support for that.

In theory, it could be similar to the indexed variables but instead of indexing the referenced template variable, they could be postfixed with the capturing groups’ names.

Regex replacement variables used in Search template

Although it may have potential to use indexed replacement variables in the Search template part of a template, IntelliJ doesn’t have support for that as of version 2020.2.

In the Search template part it is handled simply as another template variable, and not as the specialized version of an already existing one.

They became slightly restructured, so that now users are able to define multiple templates for each inspection, and each inspection can have its own severity.

There are also some new configuration options added. Let’s see in more detail what JetBrains devs have cooked for us.

Multiple templates per inspection

First, it’s important to distinguish the terms inspection and template.

Inspections are common coding problems for what there can be one or more different checks, meanwhile templates are one or more different checks for the same problem.

For example, there can be an inspection called Incorrect Cucumber tag expression which can be validated in the @CucumberOptions annotation, or in any of the hook annotations (@Before, @After, etc.). Inside the inspection one template might validate the tags in the @CucumberOptions annotation, another one in the hook annotations, or a third one somewhere else, if necessary.

Restructuring of inspections

The first prominent change is that Structural Search Inspection is now moved out of General into its own category and is now called Structural Search.

Along with that, inspections can be added into this category via a new Add button at the top window toolbar:

Since before 2020.2 Structural Search Inspection was stored on inspection level, rather as a category, setting severity for different templates were not possible.

Now, that there can be multiple Structural Search inspections added, each inspection can specify its own severity.

Finally, each inspection can store multiple search and replace templates.

In the XML representation of <searchConfiguration> and <replaceConfiguration> tags there is a new attribute called order, which holds an Integer (starting from 1) as a String value, and reflects the order of templates as they are shown on the Settings UI.

Whether the order also means order of precedence in terms of execution, I have no information on.

Inspection meta data

Each inspection now contains editable metadata, most are newly added in this version of IntelliJ:

• Inspection name: the name that is displayed under the Structural Search category in the Settings.
• Problem tooltip:
  This is the text of the tooltip that is shown in the editor when the mouse is hovered over a highlighted code snippet.
  In this field you can even insert the #ref macro which will be resolved to the highlighted code, so you can define somewhat
  dynamic tooltip messages.
• Description: in this field you can compose an HTML document that serves as the description of the inspection shown in the top right section of the inspection details.
• Suppress ID: from now on it is also possible to suppress the inspection in case of certain warnings. Quoting from the
  IntelliJ documentation:

provide a suppress ID if necessary (@SuppressWarnings("suppress id")). The default suppress ID for custom inspections is SSBasedInspection.

Final thoughts

For some of the newly added features, like the #ref macro and the suppress ID, I will probably write separate article providing more details and examples on how they work.

An example

One such example may be Selenium WebDriver’s @FindBy annotation in which you can specify a locator strategy, and the locator itself for related WebElements. However, multiple WebElements or list of WebElements with the same locator strategy and locator are incorrect, or may be misleading:

public class APageObject {

  @FindBy(id = "header")
  private WebElement header;

  @FindBy(id = "header")
  private WebElement head;
}

Of course, in case of WebDriver it can still be valid if you have a WebElement and a separate List<WebElement> field with the same locator strategy and value because the WebElement type field will store the first match for that locator, meanwhile the List<WebElement> type field will store all matches for it:

public class APageObject {

  @FindBy(className = "table-row")
  private WebElement firstRow;

  @FindBy(className = "table-row")
  private List<WebElement> tableRow;
}

This logic is specific to WebDriver. Other libraries and annotations (like Spring’s @Value annotation) will probably work differently.

Creating the template

Of course implementing a custom Groovy script in the Script filter is always a good option, but here I’m not going to go into the details of that, instead I’m going to show you how this check may be achieved without the Script filter.

In the template text you’ll need two fields of class (they might also be marked as instance fields using the @Modifier("Instance") annotation), e.g:

class $Class$ {
    @$FindBy$(css = "$value$")
    $FieldType$ $field$ = $init$;

    @$FindBy$(css = "$value$")
    $FieldType2$ $field2$ = $init2$;
}

In this first approach, although we are looking for same-type fields, the template variables representing the field types may have different names but their text filters must be configured with the same value/type.

This template might also be useful when you don’t want to allow even different type objects for the same locator.

Configuration:

• FieldType, FieldType2: Text filter: org\.openqa\.selenium\.WebElement
• FindBy: Text filter: org\.openqa\.selenium\.support\.FindBy
• init, init2: Count filter: 0,1

The other approach is almost identical to the previous one, but here the two field types are handled with the same template variable (the filter configuration remains the same):

class $Class$ {
    @$FindBy$(css = "$value$")
    $FieldType$ $field$ = $init$;

    @$FindBy$(css = "$value$")
    $FieldType$ $field2$ = $init2$;
}

In this latter case, if there are more than 2 matches, using $FieldType$ as the search target, only the first two matches will be highlighted.

Additional resources

Related support and YouTrack tickets:

• Find fields in class annotated with the same values (Structural Search ?)
• Finding same values does not work

According to the official documentation:

The Text filter checks the variable against regular expressions or plain text.

Configuration

Let’s consider the following method call template:

$Instance$.$MethodCall$($Parameter$)

To filter for the text of a template variable/PSI node, you can use the Text filter to define the constraint.

The Text filter has 3 configuration options:

• text: the actual filter value, a regex
• Words: you can match against whole words
• Within type hierarchy: to also handle subtypes of a given type

Text

In this field you can specify a regex pattern that is going to be matched against the text of the template variable, or more specifically the actual language element that the variable is resolved to.

Matching against different nodes’ texts differs depending on the type of the PSI node.

Targeting literal values

In case of targeting String literals there are two ways to define variables:

• $variable$: in this case the variable can mean nodes other than String literals too
• "$variable$": specified between double-quotes. In this case the variable will only match if a String literal is found.

In both cases, if there is an input String e.g. "stringLiteral", both of their texts will be "stringLiteral" including the double-quotes.

When it comes to number and boolean literals the text of variables for input values like 3 (as Integer) or false (as boolean) will be 3 and false, both as Strings, without double-quotes.

Type references: classes, interfaces, enums

If you consider the above mentioned method call template, the $Instance$ variable may be an instance of a type, or a type itself as well.

In the latter case you have to take into account that a type’s, e.g. java.lang.String, text is not just String but the fully qualified name java.lang.String, so you need to make sure the text pattern you specify matches against that fully qualified name.

Invert condition

You can invert the condition by adding an ! (exclamation mark) at the beginning of the filter value, like !java.lang.String:

<constraint
    name="Instance"
    regexp="java.lang.String"
    minCount="0"
    negateName="true"
    within=""
    contains="" />

Words

Enabling this option results in performing a “whole words only” search (quoting from regular-expressions.info).

In that case the actual regex pattern will not be the one that you specify as the filter value, but that value is embedded in additional regex:

.*?\\b(?:" + realRegexp + ")\\b.*?;

where realRegexp is a variable that has the value specified in the filter.

You can find the related code in com.intellij.structuralsearch.impl.matcher.predicates.RegExpPredicate#compilePattern.

So, as a result, specifying the filter value as e.g. word and enabling the Words option, it will match the following input value:

this.someMethod("this is a word");

but not this one

this.someMethod("this is a longerword");

Within type hierarchy

When a template variable corresponds to a Java type (class, interface, enum, record) name, there is an additional option in the filter called Within type hierarchy.

When this option is enabled, subtypes of the specified type (but not supertypes) are also considered during match, contrary to when it is disabled, in that case code elements are matched only against that specific type.

<constraint
    name="Instance"
    regexp="java.lang.String"
    withinHierarchy="true"
    minCount="0"
    within=""
    contains="" />

Text filter UI

If you are interested in the Text filter’s UI structure you can check out the com.intellij.structuralsearch.plugin.ui.filters package, specifically the class TextFilter.