Testing XML rules

After you have created an XML rule, you should create a test rule to ensure that it works.

Creating a test rule

Test rules are created using a process similar to the process for creating an XML rule, with the following differences:

Test rules should be placed in a tests/ directory beneath the rule to be tested.
Any data, such as test classes, should be placed in a data/ directory beneath the tests/ directory.
Test rules should use the .windup.test.xml extension.
These rules use the structure defined in the Test XML Rule Structure.

In addition, it is recommended to create a test rule that follows the name of the rule it tests. For example, if a rule were created with a filename of proprietary-rule.{LC_PSN}.xml, the test rule should be called proprietary-rule.windup.test.xml.

Test XML rule structure

All test XML rules are defined as elements within ruletests which contain one or more rulesets. For more details, see the {ProductShortName} XML rule schema.

A ruletest is a group of one or more tests that targets a specific area of migration. This is the basic structure of the <ruletest> element.

<ruletest id="<RULE_TOPIC>-test">: Defines this as a unique {ProductShortName} ruletest and gives it a unique ruletest id.
- <testDataPath>: Defines the path to any data, such as classes or files, used for testing.
- <sourceMode>: Indicates if the passed in data only contains source files. If an archive, such as an EAR, WAR, or JAR, is in use, then this should be set to false. Defaults to true.
- <rulePath>: The path to the rule to be tested. This should end in the name of the rule to test.
- <ruleset>: Rulesets containing the logic of the test cases. These are identical to the ones defined in Rulesets.

Test XML rule syntax

In addition to the tags in the standard XML rule syntax, the following when conditions are commonly used for creating test rules:

<not>
<iterable-filter>
<classification-exists>
<hint-exists>

In addition to the tags in the standard perform action syntax, the following perform conditions are commonly used as actions in test rules:

<fail>

<not> syntax

Summary

The <not> element is the standard logical not operator, and is commonly used to perform a <fail> if the condition is not met.

The following is an example of a test rule that fails if only a specific message exists at the end of the analysis.

<ruletest xmlns="http://windup.jboss.org/schema/jboss-ruleset"
          id="proprietary-servlet-test" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://windup.jboss.org/schema/jboss-ruleset http://windup.jboss.org/schema/jboss-ruleset/windup-jboss-ruleset.xsd">
  <testDataPath>data/</testDataPath>
  <rulePath>../proprietary-servlet.windup.xml</rulePath>
  <ruleset>
    <rules>
      <rule id="proprietary-servlet-01000-test">
        <when>
          <!--
	    The `<not>` will perform a logical _not_ operator on the elements within.
	  -->
          <not>
            <!--
	      The defined `<iterable-filter>` has a size of `1`. This rule will only match on a single instance of the defined hint.
	    -->
            <iterable-filter size="1">
              <hint-exists message="Replace the proprietary @ProprietaryServlet annotation with the Java EE 7 standard @WebServlet annotation*" />
            </iterable-filter>
          </not>
        </when>
        <!--
	  This `<perform>` element is only executed if the previous `<when>` condition is false.
          This ensures that it only executes if there is not a single instance of the defined hint.
        -->
        <perform>
          <fail message="Hint for @ProprietaryServlet was not found!" />
        </perform>
      </rule>
    </rules>
  </ruleset>
</ruletest>

The <not> element has no unique attributes or child elements.

<iterable-filter> syntax

Summary

The <iterable-filter> element counts the number of times a condition is verified. For additional information, see the IterableFilter class.

The following is an example that looks for four instances of the specified message.

<ruletest xmlns="http://windup.jboss.org/schema/jboss-ruleset"
          id="proprietary-servlet-test" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://windup.jboss.org/schema/jboss-ruleset http://windup.jboss.org/schema/jboss-ruleset/windup-jboss-ruleset.xsd">
  <testDataPath>data/</testDataPath>
  <rulePath>../proprietary-servlet.{LC_PSN}.xml</rulePath>
  <ruleset>
    <rules>
      <rule id="proprietary-servlet-03000-test">
        <when>
          <!--
	    The `<not>` will perform a logical _not_ operator on the elements within.
	  -->
          <not>
	    <!--
	      The defined `<iterable-filter>` has a size of `4`. This rule will only match on four instances of the defined hint.
	    -->
            <iterable-filter size="4">
              <hint-exists message="Replace the proprietary @ProprietaryInitParam annotation with the Java EE 7 standard @WebInitParam annotation*" />
            </iterable-filter>
          </not>
        </when>
	<!--
	  This `<perform>` element is only executed if the previous `<when>` condition is false.
	  In this configuration, it only executes if there are not four instances of the defined hint.
	-->
        <perform>
          <fail message="Hint for @ProprietaryInitParam was not found!" />
        </perform>
      </rule>
    </rules>
  </ruleset>
</ruletest>

The <iterable-filter> element has no unique child elements.

Attribute Name	Type	Description
size	integer	The number of times to be verified.

Attribute Name

Type

Description

size

integer

The number of times to be verified.

<classification-exists> syntax

The <classification-exists> element determines if a specific classification title has been included in the analysis. For additional information, see the ClassificationExists class.

Important

When testing for a message that contains special characters, such as [ or ', you must escape each special character with a backslash (\) to correctly match.

The following is an example that searches for a specific classification title.

<ruletest xmlns="http://windup.jboss.org/schema/jboss-ruleset"
          id="proprietary-servlet-test" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://windup.jboss.org/schema/jboss-ruleset http://windup.jboss.org/schema/jboss-ruleset/windup-jboss-ruleset.xsd">
  <testDataPath>data/</testDataPath>
  <rulePath>../weblogic.{LC_PSN}.xml</rulePath>
  <ruleset>
    <rules>
      <rule id="weblogic-01000-test">
        <when>
          <!--
	    The `<not>` will perform a logical _not_ operator on the elements within.
	  -->
          <not>
	    <!--
	      The defined `<classification-exists>` is attempting to match on the defined title.
	      This classification would have been generated by a matching `<classification title="WebLogic scheduled job" .../>` rule.
	    -->
            <classification-exists classification="WebLogic scheduled job" />
          </not>
        </when>
	<!--
	  This `<perform>` element is only executed if the previous `<when>` condition is false.
	  In this configuration, it only executes if there is not a matching classification.
	-->
        <perform>
          <fail message="Triggerable not found" />
        </perform>
      </rule>
    </rules>
  </ruleset>
</ruletest>

The <classification-exists> has no unique child elements.

<classification-exists> element attributes

Attribute Name Type Description

Attribute Name	Type	Description
classification	String	The `<classification>` `title` to search for.
in	String	An optional argument that restricts matching to files that contain the defined filename.

classification

String

The <classification> title to search for.

String

An optional argument that restricts matching to files that contain the defined filename.

<hint-exists> syntax

The <hint-exists> element determines if a specific hint has been included in the analysis. It searches for any instances of the defined message, and is typically used to search for the beginning or a specific class inside of a <message> element. For additional information, see the HintExists class.

Important

When testing for a message that contains special characters, such as [ or ', you must escape each special character with a backslash (\) to correctly match.

The following is an example that searches for a specific hint.

<ruletest xmlns="http://windup.jboss.org/schema/jboss-ruleset"
          id="proprietary-servlet-test" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://windup.jboss.org/schema/jboss-ruleset http://windup.jboss.org/schema/jboss-ruleset/windup-jboss-ruleset.xsd">
  <testDataPath>data/</testDataPath>
  <rulePath>../weblogic.windup.xml</rulePath>
  <ruleset>
    <rules>
      <rule id="weblogic-eap7-05000-test">
        <when>
          <!--
	    The `<not>` will perform a logical _not_ operator on the elements within.
	  -->
          <not>
	    <!--
	      The defined `<hint-exists>` is attempting to match on the defined message.
	      This message would have been generated by a matching `<message>` element on the `<hint>` condition.
	    -->
            <hint-exists message="Replace with the Java EE standard method .*javax\.transaction\.TransactionManager\.resume\(Transaction tx\).*" />
          </not>
        </when>
	<!--
	  This `<perform>` element is only executed if the previous `<when>` condition is false.
	  In this configuration, it only executes if there is not a matching hint.
	-->
        <perform>
          <fail message="Note to replace with standard TransactionManager.resume is missing!" />
        </perform>
      </rule>
    </rules>
  </ruleset>
</ruletest>

The <hint-exists> element has no unique child elements.

<hint-exists> element attributes

Attribute Name Type Description

Attribute Name	Type	Description
message	String	The `<hint>` `message` to search for.
in	String	An optional argument that restricts matching to `InLineHintModels` that reference the given filename.

message

String

The <hint> message to search for.

String

An optional argument that restricts matching to InLineHintModels that reference the given filename.

<fail> syntax

The <fail> element reports the execution as a failure and displays the associated message. It is commonly used in conjunction with the <not> condition to display a message only if the conditions are not met.

The <fail> element has no unique child elements.

<fail> element attributes

Attribute Name	Type	Description
message	String	The message to be displayed.

Attribute Name

Type

Description

message

String

The message to be displayed.

Windup Documentation

Testing XML rules

Creating a test rule

Test XML rule structure

Test XML rule syntax

<not> syntax

Summary

<iterable-filter> syntax

Summary

<iterable-filter> element attributes

<classification-exists> syntax

<classification-exists> element attributes

<hint-exists> syntax

<hint-exists> element attributes

<fail> syntax

<fail> element attributes