Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

Running Pega unit test cases and test suites with the Execute Tests service

Updated on September 10, 2021

When you build an application on Pega Platform™ in a continuous delivery pipeline, you can use the Execute Tests service (REST API) to validate the quality of the build by running Pega unit test cases that are configured for the application.

A continuous integration (CI) tool, such as Jenkins, calls the service, which runs all the Pega unit test cases or a test suite in your application and returns the results in xUnit format. The continuous integration tool interprets the results and, if the tests are not successful, you can correct errors before you deploy your application.

When you use Jenkins, you can also use the Execute Tests service to run Pega unit tests after you merge a branch on a remote system of record and start a job. For more information, see Remotely starting automation server jobs to perform branch operations and run Pega unit tests.

The service comprises the following information:

  • Service name: Pega unit Rule-Test-Unit-Case pzExecuteTests
  • Service package: Pega unit
  • End point: http://<yourapplicationURL>/prweb/PRRestService/Pega unit/Rule-Test-Unit-Case/pzExecuteTests

You can quarantine a test case by marking it as “Disabled.” A disabled test case is not run by the Execute Tests service. Test case quarantines prevent noncritical tests from running if they are causing failures so that the service can continue to run.

Request parameters

The Execute Tests service takes the following request parameters, which are strings:

  • ApplicationInformation – Optional. The name and version of the application for which you want to run Pega unit test cases. You can pass it instead of the AccessGroup parameter.
    • If you pass only this parameter, the service runs all the test cases in the application.
    • If you do not pass this parameter, the service runs all the test cases in the application that are associated with the default access group that is configured for your operator.

Use the format ApplicationInformation=<application_name:application_version>.

  • ​AccessGroup – Optional. The access group that is associated with the application for which you want to run Pega unit test cases. You can pass it instead of the ApplicationInformation parameter.
    • If you pass this parameter, the service runs all the test cases in the application that are associated with this access group.
    • If you do not pass this parameter, the service runs all the test cases in the application that are associated with the default access group that is configured for your operator.

Use the format AccessGroup=<access_group_name:access_group_user>.

  • ​TestSuiteID – The pxInsName of the test suite that you want to run. You can find this value in the XML document that comprises the test suite by clicking Actions > XML on the Edit Test Suite form. You can run one test suite at a time. When you use this parameter, all the test cases in the test suite are run, but no other test cases in your application are run. This parameter is required for Pega unit test suites. If test suites share the same name among applications:
    • If you pass the ApplicationInformation or AccessGroup parameter with the TestSuiteID parameter, the service runs the test suite in the application that you specified.
    • If you do not pass the ApplicationInformation parameter or the AccessGroup parameter with the TestSuiteID parameter, the system runs the test suite in the application that is associated with the default access group.

Use the format TestSuiteID=<pxInsName>.

  • LocationOfResults – The location where the service stores the XML file that contains the test results. This parameter is optional for test cases and test suites.
  • RunWithCoverage – Determines whether the application-level test coverage report is generated after the Execute Tests service runs all relevant test cases or the selected test suite. For more information, see Generating an application-level test coverage report.
    • If you set the parameter to False, the application-level test coverage report is not generated. This is the default behavior.
    • If you set the parameter to True, and application-level coverage is not running, the Execute Tests service starts application-level coverage mode, runs all unit tests, stops coverage mode, and generates the application-level coverage report. This report is displayed on the test coverage landing page in the Application level section.
    • If you set the parameter to True, and application-level coverage is already running, the Execute Tests service returns an error.

Response

The service returns the test results in an XML file in xUnit format and stores them in the location that you specified in the LocationOfResults request parameter. The output is similar to the following example:

 

<test-case errors="2" failures="0" label="Purchase order transformation with a bad element in the output expected" name="report-bad-element-name" skip="0" tests="7"> <nodes expected="/" result="/">
<nodes xmlns:purchase="urn:acme-purchase-order" expected="/purchase:order[1]" result="/purchase-order[1]">
<error type="Local name comparison">Expected "order" but was "purchase-order"</error>
<error type="Namespace URI comparison">Expected "urn:acme-purchase-order" but was ""</error>
</nodes>
</nodes>
<sysout>This text is captured by the report</sysout>
<syserr/>
</test-case> 

 

Configuring your default access group

When you run the Execute Tests service, you can specify the access group that is associated with the application for which you want to run all Pega unit test cases or a test suite. If you do not specify an access group or application name and version, the service runs the Pega unit test cases or test suite for the default access group that is configured for your Pega Platform operator ID. To configure a default access group, complete the following steps:

  1. In Designer Studio, click the Operator menu, and then click Operator.
  2. In the Application Access section, select your default access group.
    Selecting default access group configuration
  3. Click Save.

Configuring your build environment

Configure your build environment so that it can call the Execute Tests service and run all the Pega unit test cases or a test suite in your application. Your configuration depends on the external validation engine that you use. For example, the following procedure describes how to configure the Jenkins server to call the service.

  1. Open a web browser and go to the location of the Jenkins server.
  2. Install the HTTP request plug-in for Jenkins to call the service and the JUnit plug-in so that you can view reports in xUnit format.
    1. Click Manage Jenkins.
    2. Click Manage Plugins.
    3. On the Available tab, select the HTTP Request Plugin and the JUnit Plugin check boxes.
    4. Specify whether to install the plug-in without restarting Jenkins or to download the plug-in and install it after restarting Jenkins.
  3. Configure the Pega Platform credentials for the operator who authenticates the Execute Tests service.
    1. Click Credentials, and then click System.
    2. Click the drop-down arrow next to the domain to which you want to add credentials, and click Add credentials.
    3. In the Username field, enter the operator ID that is used to authenticate the service. This operator should belong to the access group that is associated with the application for which you want to run test cases and test suites.
    4. In the Password field, enter the password.
    5. Click OK.
  4. Configure the Jenkins URL that runs the service.
    1. Click Manage Jenkins, and then click Configure System.
    2. In the Jenkins Location section, in the Jenkins URL field, enter the URL of the Jenkins server.
    3. Click Apply, and then click Save.
  5. Add a build step to be run after the project is built.
    1. Open an existing project or create a project.
    2. Click Configure.
    3. In the Build section, click Add build step, and select HTTP Request from the list.
    4. In the HTTP Request section, in the URL field, enter the endpoint of the service. Use one of the following formats:
  • http://<your application URL>/prweb/PRRestService/Pega unit/Rule-Test-Unit-Case/pzExecuteTests
  • http://<your application URL>/prweb/PRRestService/Pega unit/Rule-Test-Unit-Case/pzExecuteTests​?AccessGroup=<access_group_name:accessgroup_group_users>
  • http://<your application URL>/prweb/PRRestService/Pega unit/Rule-Test-Unit-Case/pzExecuteTests?TestSuiteID=<pxInsName>
  • http://<your application URL>/prweb/PRRestService/Pega unit/Rule-Test-Unit-Case/pzExecuteTests?ApplicationInformation?=ApplicationInformation:<application_name:application_version>

If you are using multiple parameters, separate them with the ampersand (&) character, for example, http://<your application URL>/prweb/PRRestService/Pega unit/Rule-Test-Unit-Case/pzExecuteTests?ApplicationInformation?=ApplicationInformation:<application_name:application_version>&TestSuiteID=<pxInsName>

  1. From the HTTP mode list, select POST.
  2. Click Advanced.
  3. In the Authorization section, from the Authenticate list, select the Pega Platform operator ID that authenticates the service that you configured in step 3.
  4. In the Response section, in the Output response to file field, enter the name of the XML file where Jenkins stores the output that it receives from the service. This field corresponds to the LocationOfResults request parameter.
  5. In the Post-build Actions section, from the Add post build section list, select Publish Junit test result report and enter **/*.xml in the Test Report XML field. This setting configures the results in xUnit format, which provides information about test results, such as a graph of test results trends. These results are displayed on your project page in Jenkins.
  6. Click Apply, and then click Save.

Running tests and verifying results

After you configure your validation engine, run the service and verify the test results. Your test suites and test cases must be checked in so that you can run them.

For example, in Jenkins, complete the following steps:

  1. Open the project and click Build Now.
  2. In the Build History pane, click the build that you ran.
  3. On the next page, click Test Result.
  4. In the All Tests section, click root. The results of all tests are displayed.
  5. Optional: Expand a test result in the All Failed Tests section and view details about why the test was not successful.

Test failures

Tests can fail for the following reasons:

  • The operator does not have access to the location of the results.
  • The access group that is passed by the service either does not exist or no access group is associated with the operator ID.
  • The application name and version that are passed do not exist.
  • An application is not associated with the access group that is passed by the service.
  • No Pega unit test cases or test suites are in the application.
  • The test suite pxInsName does not exist for the application name and version or for the access group that is passed by the service.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

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

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us