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 PegaUnit test cases and test suites with the Execute Tests service in Pega 7.3.1

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 can interpret the results and, if the tests are not successful, you can correct errors before you deploy your application.

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 when you use Jenkins. For more information, see Remotely starting continuous integration jobs to perform branch operations and run Pega unit tests.

The service comprises the following information:

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

Pega Platform does not provide a test case quarantine process for this service. Test case quarantines allow you to stop 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 – The name and version of the application for which you want to run Pega unit test cases. This parameter is optional. 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 is associated with the default access group that is configured for your operator.

Use the format ApplicationInformation=<application_name:application_version>.

  • ​AccessGroup – The access group associated with the application for which you want to run Pega unit test cases. This parameter is optional. 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 is associated with this access group.
    • If you do not pass this parameter, the service runs all the test cases in the application that is 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 in the Edit Test Suite form. You can run only 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 there are test suites that 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 or 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.

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.
    Default access group configurationSelecting 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 navigate to the location of the Jenkins server.
  2. Install the HTTP request plug-in for Jenkins to call the service and the JUnit Plugin 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 check box and the JUnit Plugin checkbox.
    4. Specify whether to install the plug-ins without restarting Jenkins or download the plug-in and install it after restarting Jenkins.
  3. Configure the Pega Platform credentials for the operator that 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 by completing one of the following actions:
    1. Open an existing project or create a new 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/PegaUnit/Rule-Test-Unit-Case/pzExecuteTests
  • http://<your application URL>/prweb/PRRestService/PegaUnit/Rule-Test-Unit-Case/pzExecuteTests​?AccessGroup=<access_group_name:accessgroup_group_users>
  • http://<your application URL>/prweb/PRRestService/PegaUnit/Rule-Test-Unit-Case/pzExecuteTests?TestSuiteID=<pxInsName>
  • http://<your application URL>/prweb/PRRestService/PegaUnit/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/PegaUnit/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, which you configured in step 3, that authenticates the service.
  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, 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 was run.
  3. On the next page, click Test Result.
  4. Click root in the All Tests section. The results of all failed tests and all tests are displayed.
  5. You can expand a test result in the All Failed Tests section to view details about why the test was not successful.

Test failures

Tests are not successful in the following scenarios:

  • 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 is passed does not exist.
  • An application is not associated with the access group 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 access group 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