Skip to main content
Verify the version tags to ensure you are consuming the intended content or, complete the latest version.

Unit tests

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. By unit testing the individual rules, you know that each rule works as expected when you configure them. For example, consider a decision tree that evaluates a property. As shown in the following image, the application reads the property from a data page that is sourced from a report definition. 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 testing individual rules

You can test a rule with test data that you provide by clicking Actions > Run on the rule form toolbar in Dev Studio. 

Note: For some rule types, such as binary file rules, Pega does not provide an option for unit testing. If the rule cannot be unit tested, the Run option is unavailable.

The appearance of the Run Rule window varies across rule types, so how you run a rule varies by rule type. In general, however, the rules run by using data from a test page that you define for the test.

When you run the rule, the system uses rule resolution. If you unit test a rule, and there is a higher version of the rule, the system runs the higher version of the rule.

Record a unit test for automated testing

After you run the test, you can also convert the test to a reusable test case that you can run at any time. 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 by providing a means to test rules regularly to identify the effects of new or modified rules. Run test cases whenever code changes are made that might affect existing functionality. For more information about using unit test cases, see the Pega Community article Understanding unit test cases.

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

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

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

The following table provides some examples of assertions and their uses.

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.

You can group unit test cases into a test suite to execute multiple test cases and suites in a specified order. When you run test suites in bulk, they run sequentially but not in parallel. 

Preparing test cases

Saving a test case requires access to a ruleset that is configured to store test cases. You cannot save test cases to a ruleset that is not configured to store test cases.

Before you record a unit test, work with your system administrator to identify a suitable ruleset for storing test cases. Keep tests portable and independent, as tests must neither be dependent on any other test case nor interfere with any tests running after. When the development application is released to production, you can migrate the application without including the test cases.

Tip: Use the Cleanup feature to restore any Clipboard system pages or changes to data or work instances that occur during test execution. The History tab will show a history of changes. 

Running a 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. On 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.
Unit testing page

Check your knowledge with the following interaction.

Best practices to configure unit tests

Automated unit tests deliver actionable results and the time spent on running and maintaining automated tests is less than the time spent on manual testing. Ensure that test development occurs simultaneously with the development of rules for your Pega Platform™ application. You may decide to reuse test cases during ongoing development and other teams might leverage your test suites. 

When to create automated unit tests

When a rule returns an expected result, consider configuring an automated unit test as the following priority table suggests.

High-priority Low-priority
Tests that have predictable results Tests that undergo frequent changes that require maintenance of test cases
Tests that are required to execute frequently Tests that are easy to test manually 
Tests that help to reduce manual effort when testing complex logic Tests that are too complex to automate
Tests that contain rules with wide usage across the application Tests that contain persistence of data from a database
Tip: It is recommended that you run tests on every merge and check-in at a minimum, but ideally on a more frequent, regular basis. 

Build for coverage 

Because your unit tests cover a wide range of scenarios, ensure that enough validations are created to cover all positive and negative scenarios. Aim to include as much rule coverage as possible, which includes different paths of rule execution. Add enough tests that cover all input and output combinations, but keep the test case logic short and visible to optimize reusability. Smaller unit tests can help quickly pinpoint when rule functionality does not work and promote ease in design and maintenance. 

Note: To learn more about measuring rule test coverage, see the Academy topic Test coverage.

Build for maintenance

Each test case must be easy to read and understand by any person. For example, test case names and descriptions are relevant and explain the purpose of the test case. Add comments for every step for better readability and to ensure ease of maintenance.

Make test data as modular as possible to make any updates or future changes easier and quicker. For example, you do not need to create test data for the application as a whole or larger, complex data structures. More modular test data means that small changes do not require reconfiguring all test data and potentially introducing issues with other tests. 

This Topic is available in the following Module:

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

Did you find this content helpful?

100% 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