Testing Rules
A test runs a rule against values you choose and shows you exactly what the rule did with them: which conditions were true, which branch ran, which fields it changed and which actions it would have taken. You can test a rule before you save it, test a saved version before it goes live, and check that a live rule still works with a newer version of its source. Tests run on your application's real data classes, so a rule behaves in a test the way it behaves in production.
There are two kinds of test:
- Exploration: you give the values and see what the rule does with them. Use it to try a rule out.
- Expectation: you also say what should come out, and the test tells you whether it did. Use it to check that a rule keeps doing what it should, and save it to run again later.
Testing uses these parts of the Rule Repository:
- The Test dialog. It has two steps. In Step 1 you choose what to test. In Step 2 you give values, run the test and save it.
- Step 1 of the Test dialog. It holds the Source, Source Version and Rule boxes, then three choices: A rule version (with a list of the rule's versions), A draft (with a list of the drafts on that source version) and An empty rule editor. Under them, Rule Type, Is Reusable Rule? and Can Other Rules Execute It? describe the rule; they are set for you when you pick an existing rule or draft, and you choose them yourself for a new rule.
- Step 2 of the Test dialog has three panes:
- The Fields View on the left: the source's fields, in-rule methods and actions as a tree, with an Input Values column of boxes beside them, and an Expected Values column when the test type is Expectation.
- The Rule Editor in the middle: the rule being tested. A line over it shows the rule's type and whether its definition is Editable or Immutable.
- The footer, with the run controls and the save buttons.
- The Pay Attention confirmation, which warns you before a test calls one of your application's real methods.
- The Test Result dialog, which shows what happened when the test ran. See Test Results.
Opening the Test Dialog
You can start a test from many places. Each one fills in Step 1 for you as far as it can:
- + New at the top of the screen, then New Test...: Step 1 opens empty.
- Test... in a Source Object dialog: the source is selected.
- Test... in a Source Version dialog: the source and its version are selected.
- Test... in a Rule dialog: the source, the source version and the rule are selected.
- Test... in a Rule Version dialog or a Draft dialog: everything is selected, down to that version or draft.
- Test... in Step 2 of the New Rule or New Draft dialog: the test opens straight at Step 2 with the rule you are writing, so you can try it before you save it. When you go back, the rule returns to the New Rule or New Draft dialog with your changes.
- A row of the Tests grid: the saved test opens at Step 2, ready to run. See Saved Tests.
Choosing What to Test (Step 1)
- In Source, select the source the rule is written for.
- In Source Version, select the version of the source to test against. The live version is marked (Live). You can test a rule version against a different version of its source, for example to check that a live rule still works with a source version that is about to go live.
- In Rule, select the rule, or leave it empty to test a new rule.
- Choose what to load into the Rule Editor:
- A rule version, then select the version in its list. Versions written against the selected source version come first. If you pick one written against a different source version, the editor marks anything the selected source version does not have.
- A draft, then select the draft in its list. Only drafts written against the selected source version are listed.
- An empty rule editor, to write a new rule, or a new version of the selected rule, as you test it.
- For a new rule, choose its Rule Type and the other two answers. For an existing rule or a draft they are already filled in and cannot be changed.
- Click Next. The dialog moves to Step 2.
Giving Values (Step 2)
The Fields View lists what the rule uses. Each field has a box in the Input Values column.
- Click a field's box. The same input the Rule Editor uses for that field opens: a text box, a number, a date or time picker, a list of choices, or True and False. Values are checked exactly as they would be in a rule.
- Pick or type the value. The box shows it, with an × to clear it again.
- Repeat for every field the test needs.
A few things to know about values:
- A box that shows a dash (—) is not set. The test then uses whatever value your application's class starts with. Where that starting value is known, the box shows it in grey instead of a dash.
- Collections. A collection has an + Add Item link. Each click adds an item under it with its own fields; Remove This Item takes one away.
- In-rule methods are listed by call. If the rule calls a method three times, the Fields View shows three calls under it, each with its own box. Setting a value on a call makes the test use that value instead of running the method.
- What the Fields View shows. The list at the top left switches between Referenced fields only with no details (only what the rule uses, by name) and Full view with details (every member of the source, with its settings).
- Hover over a field and the matching elements light up in the rule, and the other way round.
To save the values you entered so you can use them again, see Value Templates.
Methods That Are Replaced During Tests
Your application's developers can give a method or an action a test method: a safe stand-in that runs during tests instead of the real one. The Fields View shows this under the method's name: Test method: followed by its name, or No test method.
- An in-rule method with a test method runs the test method.
- An in-rule method with No test method runs for real, unless you set a value on its call.
- An action with No test method is not run at all. The test only records that the rule would have run it, and with what values.
Saying What You Expect
- In the list at the top of the Fields View, change Exploration to Expectation. The Expected Values column appears beside Input Values, and an Expected result... list appears beside Run.
- In Expected result..., select True or False: the result you expect the rule itself to return. Leave it as it is to expect nothing.
- In the Expected Values column, set the value you expect a field to have after the rule runs, for example a field the rule sets.
- For an action, set whether you expect it to run. Once you expect it to run, you can also set the values you expect it to receive.
Anything you leave as a dash is not checked.
Running the Test
- Optionally, click the settings button beside Run to set Precision and Rounding. Use the ones your application evaluates the rule with: they change how decimal numbers are compared.
- Click Run.
- If the rule would call one of your application's real methods, the Pay Attention confirmation lists those calls and warns that they could change real data. Click OK to run anyway, or Cancel to go back and set values on those calls first. If you do not have permission to run tests that call real methods, the test cannot be run until those calls have values.
- The Test Result dialog opens. See Test Results. Click Back to Test to change values and run again.
A test stops if it takes longer than ten seconds.
Changing the Rule While You Test
When the Rule Editor holds a new rule or a draft, you can change the rule and run the test again as often as you like. The footer then offers:
- Save as Draft...: keeps the rule as a draft. A dialog asks for the rule's and the version's names and descriptions.
- Create Rule... or Create Version...: saves the rule as a new rule or a new version of the selected rule, after the rule is checked. The usual save question follows; see Creating Rules.
A saved rule version is Immutable: you can test it, but not change it. To change it, save it as a draft with Save as Draft..., or start a new version.
If you opened the test from a Draft dialog, the draft's editor moves into the Test dialog. When you close the test, the draft gets its editor back. If you saved the draft as a version, its dialog is replaced by the new version's.