Overview: How to Create a Rule

When you create a rule, your goal is to graphically express the pattern that you do not want to appear in your code. When Jtest enforces a rule, it searches for instances where the specified pattern occurs, then flags any violations that it finds.

To open RuleWizard

1. In either Jtest UI, open the Global Test Parameters window by clicking the Global button.
2. In the Global Test Parameters window, go to Static Analysis> Rules> User Defined Rules.
3. Right-click User Defined Rules and choose Add/Edit Rules (RuleWizard) from the shortcut menu.

Or,

• In either Jtest UI, right-click the Rules button and choose Launch RuleWizard.

When the RuleWizard GUI opens, you will see two main panels. The Node tab on the left side of the GUI contains the nodes that you can use as rule subjects.The right side of the GUI is the area where your rule patterns will be displayed.

There are two ways to create a rule: manually and using the Auto-Create feature.

Manually

Creating a rule generally involves the following steps:

1. Using plain English, define the rule that you want to create and enforce.

   For example: "Begin class names with an uppercase letter."

2. Express this concept in terms of RuleWizard elements.
   • Create the parent rule node that is the subject of your rule.
     1. In the Node tab, select the node that is the subject of your rule.

        Tip: For a description of a certain node, right-click the node, and choose View Documentation from the shortcut menu that opens.

        If you can't find the node you want, right-click inside the white space and choose Find from the shortcut menu that opens.

     2. Right-click the selected node, then choose Create Rule from the shortcut menu. A rule node will appear in the GUI's right panel.
   • Add further qualifications to your node until it fully expresses your rule.
     1. Right-click any of your rule's nodes. All available options for the chosen node will be displayed in the shortcut menu that opens. Any options that are not programming elements or concepts are explained in the section RuleWizard Commands.
     2. Choose a command from the shortcut menu. Depending on the command that you choose, RuleWizard will add a rule element, modify a rule element, or open a dialog box that lets you add or modify a rule element.
     3. If you want to continue adding to and modifying the rule, you can do so by right-clicking any rule node or rule element, then choosing one of the available commands.

• Determine what error message will be displayed when this rule is violated.
  1. Create an output arrow by right-clicking a rule node (the placement of the output arrow determines what line number is used for the output message; to have the line number of node C included in the output message, place the output arrow on node C), then choosing Create Output from the shortcut menu. The Customize Output window will open.
  2. In the Customize Output window, enter a brief explanation of the violation.
  3. Click OK.
     An output arrow will then be added to your rule.

The rule is complete once it:

• Expresses the pattern that you want Jtest to search for, and
• Contains an output arrow and message.

After you customize this rule's properties (you must at least enter a rule header) and save the rule, you can enforce it with Jtest.

Auto-Create

To use Auto-Create, simply right-click inside the white space of the Node tab and choose Auto-Create Rules from the short-cut menu. Then in the RuleWizard Automatic Creation window type the code you do not want to appear and click OK. RuleWizard automatically generates the nodes and conditions for you. Then you can customize the rule's properties, save it, and enforce it with Jtest.

For more information see Automatic Rule Creation.

Searching for Nodes

To search for a node, simply right-click inside the white space of the Dictionary tab and choose Find from the short-cut menu. Then, in the Dictionary window that opens, type the name of the node you want. RuleWizard will search through the nodes and highlight the node that matches what you type. Click Next to go to the next node that matches the text you typed. Click Clear to clear the field. Click Select to have RuleWizard keep that node highlighted as you continue your search.

Tips

General

• Remember that you are trying to express a pattern that constitutes a violation of the rule.
• As you create your rule, look at the status bar for tips on creating a valid rule. The color of the bar in the right side of the status bar indicates whether or not a rule is valid: a red bar indicates that the rule is not yet valid; a green bar indicates that the rule is valid. The messages in the status bar tell you how to make an invalid rule valid.
• Be sure to include at least one output arrow in each rule. If a rule does not have an output arrow, Jtest will not report an error if this pattern is found in the code under test. To include an output arrow, right-click a rule node (the placement of the output arrow determines what line number is used for the output message; to have the line number of node C included in the output message, place the output arrow on node C), then choose Create Output from the shortcut menu.
• The relationship between all rule branches is AND unless you indicate otherwise. If you want to express a different relationship between branches (for example, OR, NAND, or NOR relationships), you can do so by adding or changing logic components. For more detail on logic components, see RuleWizard Commands.
• To undo a command, simply right-click the gray portion of the workspace and choose Undo.
• Be sure to enter a header when you customize this rule's properties; rules without headers are not valid.
• Any node (such as bool Constant) or folder of nodes (Constants) can be used as a rule node.
• To view a description of a node in the Nodes tab, right-click the node that you want more information about, then choose View Documentation from the shortcut menu.
• Be aware that RuleWizard is order-specific. If your rule has more than one child node, you can move the child up or down one position by right-clicking the vertical line common to all children, then choosing Move up one or Move down one from the shortcut menu.

Expressions and Regular Expressions

• Use expressions to match number values, and regular expressions to match strings of text. For guidelines on using expressions and regular expressions, see Expressions and Regular Expressions.

Rule Conditions

• To create a rule with a pattern that involves a union, intersection, exclusive-or relationship, or difference of multiple nodes, see Working With Node Sets.
• To create a rule condition that restricts the number of a certain element that can appear in a block (like a file or a class), create a collector to track the number of instances of that pattern, then use Count to specify the number of instances that constitutes a violation. For information on determining exactly how "counts" are calculated, see Working With Node Sets.
• To create a rule condition about the code element that contains the parent node, use Context.
• To create a rule condition about the parent node's condition statement (if, else, init, increment, for, with, while, switch, and do while), use Condition.
• To create a rule condition about the code element that is a subnode of the parent node, use Body.
• To indicate whether or not Jtest searches nodes recursively when it searches for the rule condition, use Indirect Check and Direct Check.

  Indirect Check is the default setting; to use a Direct Check, right-click the node whose checking type you want to change, then choose Direct Check from the shortcut menu.