Table of Contents

Article

Running PegaUnit test cases and test suites with the Execute Tests service in Pega 7.4

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 automation server 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

You can quarantine a test case by marking it as “Disabled.” A disabled test case will not be 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 – 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 are associated with the default access group that is configured for your operator.

Use the format ApplicationInformation=<application_name:application_version>.

  • ​AccessGroup – The access group that is 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 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 rule coverage report is generated after the Execute Tests service runs all relevant test cases or the selected test suite.
    • If the parameter is set to False, the rule coverage report is not generated. This is the default behavior.
    • If the parameter is set to True, the Execute Tests service starts coverage mode, runs all tests, stops coverage mode, and generates the rule coverage report. This report is displayed on the rule coverage landing page and its results are also visible on the Application Quality landing page.

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="/"><br />
<nodes xmlns:purchase="urn:acme-purchase-order" expected="/purchase:order[1]" result="/purchase-order[1]"><br />
<error type="Local name comparison">Expected "order" but was "purchase-order"</error><br />
<error type="Namespace URI comparison">Expected "urn:acme-purchase-order" but was ""</error><br />
</nodes><br />
</nodes><br />
<sysout>This text is captured by the report</sysout><br />
<syserr/><br />
</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 check box.
    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/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 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, 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. In the All Tests section, click root. The results of all failed tests and 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.

Published April 19, 2018 — Updated October 5, 2018


100% found this useful

Have a question? Get answers now.

Visit the Pega Support Community to ask questions, engage in discussions, and help others.