Skip to main content

Unit tests

Unit testing

An incorrect rule configuration in an application can cause delays in case processing. When an error occurs, end users might need to reassign work, or a case might require repair by an administrator. For example, consider a case that needs to be routed to the Fulfillment department. If the case is routed instead to the Accounting department, an accountant must reroute the case to Fulfillment. The accountant wastes time rerouting the assignment, while the Fulfillment department is idle. The result is a delay to the customer during case reassignment.


To avoid configuration errors such as incorrectly routed assignments, developers test their applications. The most basic form of application testing is unit testing individual rules. Unit testing supports the continuous delivery of applications by enabling quality testing of the smallest units of functionality. In a Pega application, the smallest unit is an individual rule. The purpose of unit testing is to verify that each element of the application, for example, a decision table or a report definition, works as expected. Unit testing reduces the risk of a configuration error in one rule being propagated to other rules in the application, which causes significant delays to case processing.

Use unit testing to reduce configuration errors. For example, consider a decision tree that evaluates a property. As illustrated in the following image, the application reads the property from a data page that is sourced from a report definition. By unit testing the individual rules when you configure them, you know that each rule works as expected. If the decision tree returns an incorrect result, but the data page contains the correct data, you can isolate the error to the decision tree.


Check your knowledge with the following interaction.

Unit test application rules

Perform the following tasks to successfully unit test a rule:

  • Open the Run Rule window from the rule form.
  • Initialize the rule with test data.
  • View the result returned by the rule.

Open the Run Rule window from the rule form

To unit test a rule, open the rule form and run the rule. For some rule types, such as binary file rules, Pega Platform does not provide an option for unit testing. If the rule cannot be unit tested, the Run option is not available.

Run Rule window appearance

The appearance of the Run Rule window varies by the type of rule tested. For example, data page rules and when rules use a dialog box that mimics the appearance of the clipboard. For details on unit testing a specific type of rule, see the Community article Unit testing individual rules.

If the rule operates on data in memory, Pega Platform displays the Run Rule window. For example, declare expressions, decision rules, and UI rules operate on data in memory, so Pega Platform displays the Run Rule window.

Report definitions run against the contents of a database table, rather than memory. As a result, Pega Platform skips the Run Rule window and returns the report data when you run a report definition.

Initialize the rule with test data

In the Run Rule window, identify a test page of data used to unit test the rule. The Run Rule window creates the test page on the clipboard. The name of the test page is the same as the Applies To class of the rule, with the prefix temp_ applied. This isolates the test data from other pages in memory.

When you unit test a rule, determine how you want to source data for the test page. The Run Rule window provides several options to add data to the test page, depending on the type of rule tested.

Typically, you can create a page of test data by using a data transform. By default, Pega Platform applies the pyDefault data transform to populate the test page with data. You can also select another data transform to apply. For example, to unit test a decision table, you can create a data transform to provide values for the properties that are evaluated by the table, rather than manually enter values when you run the rule.

You can also copy a page of the appropriate class already on the clipboard. For example, to test a decision table used by a case type, you can create a case and copy data from pyWorkPage.

View the result returned by the rule

After you select a method to populate the test page, reset the page to populate the page with data and run the rule to return a result.

Tip: Reset Page clears the result of a previous test.

If the rule accepts inputs, you can enter values to test. The values that you enter override the values on the test page. For example, consider the ToEmployeeReferralWB decision table shown in the following image. The decision table determines the routing work queue for an assignment. If the value of the property Referred by employee is true, then the application routes the assignment to the ReferralWB work queue.

Decision table referred by

For a decision table or decision tree, assign values to each input property and run again to display the result of the decision table or tree. The following image shows the result of the test when .ReferredByEmployee is set to true.


You can also review the result of the unit test by viewing the output of the test with the Clipboard tool. The Run Rule window generates several pages on the clipboard. These pages provide information about the rule test.

RuleToRun The clipboard representation of the rule that you tested. If more than one version of the rule is present in the application, view this page to identify the tested rule version.
temp_ page

Created or copied when you test a rule. The names of these pages begin with the string temp_. View this page to examine the data that was used to initialize the rule for the unit test.

Check your knowledge with the following interaction.

Check your knowledge with the following interaction.

Record a unit test for automated testing

After you successfully unit test a rule, you can convert the test run to create a test case that is based on the result of the test. A test case identifies one or more testable conditions used to determine whether a rule returns an expected result. Creating a reusable test case supports the continuous delivery model, providing a means to test rules on a recurring basis to identify the effects of new or modified rules.

You can run a saved unit test from the rule or unit test automatically by using the PegaUnit testing facility.

To create a test case, you convert a test in the Run Rule window. You define the expected results that indicate a successful unit test. Each expected result consists of an assertion that describes one or more conditions to test. Test cases support several types of assertions that are designed to test various aspects of rule execution. The assertions available for a test case vary according to the type of rule tested.

For a full explanation of the supported assertion types and their usage, see the Community article Defining expected test results with assertions.

Some examples of assertions and their uses are provided in the following table:

Assertion type Usage Example
Property Tests the value of the specified property. Requires the page on which the property is defined, a comparison operation, and a comparison value. pxUrgencyWork is equal to 10
Decision result Tests the value returned by a decision rule. Requires values for each input property needed by the decision rule to return the expected result. When Referred by employee is false, return RecruitingWB
Expected run time Tests whether a rule executes within an allowed amount of time. Requires a comparison operation and an allowed time in seconds. Expected run time is less than or equal to three seconds
Page Tests for the presence of a page in memory. Requires the name of the page and a comparison operation. Page D_CoursesList has no errors

When you complete the set of expected results, save the configuration of the test case. You can access a saved test case from the rule. The rule lists all the test cases recorded for that rule and the status of each test case as of its last execution.

If you rerun a test case and the test case fails, open the result, and identify each assertion that returned an unexpected result. If a test case returns expected results, a green Passed status is displayed.

Check your knowledge with the following interaction. 

Best practices to configure unit tests

Save the test case

Saving the test case requires access to a ruleset that is configured to store test cases. If the ruleset you select is not configured to store test cases, Pega Platform returns an error. Before you record a unit test, work with your system administrator to identify a suitable ruleset for storing test cases.

Save test cases to a dedicated testing ruleset for maintenance and packaging. For ease of configuration, use an application built on the development application, and include a ruleset designed specifically for test cases. When the development application is released to production, you can migrate the application without including the test cases.

Run the test case

In Dev Studio, the Unit testing landing page lists all the test cases defined for an application and the status of each test case as of its last execution. From the landing page, you can also create test suites that consist of one or more related test cases. Pega unit test suites run multiple test cases in the order that you specify. 

Tip: On the Configure menu, select Application > Quality > Automated Testing > Unit Testing to access the landing page.

Check your knowledge with the following interaction.

If you are having problems with your training, please review the Pega Academy Support FAQs.

Did you find this content helpful?

40% found this content useful

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega Academy has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice