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 of that application.

An external validation engine, such as Jenkins, calls the service, which runs all data page unit test cases in your application and returns the results in xUnit format. The validation engine can interpret the results and, if the tests are not successful, you can correct errors before you deploy your application.

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

Request parameters

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

• Access Group - The access group associated with the application for which you want to run data page unit tests.
  • 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 from the application that is associated with the default access group configured for your operator.
• LocationOfResults - The location where the service stores the XML file that contains the test results.

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 data page unit tests. If you do not specify an access group, the service runs data page unit test cases for the default access group that is configured for your operator ID on the Pega 7 Platform. 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.
   
3. Click Save.

Configuring your build environment

Configure your build environment so that it can call the Execute Tests service and run the data page unit test cases in your application. Your configuration depends on the external validation engine that you use. For example, the following procedure describes how to configure Jenkins 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.
   1. Click Manage Jenkins.
   2. Click Manage Plugins.
   3. On the Available tab, select the HTTP Request Plugin check box.
   4. Specify whether to install the plug-in without restarting Jenkins or download the plug-in and install it after restarting Jenkins.
3. Click Manage Jenkins.
4. Click Configure System.
5. In the Jenkins Location section, in the Jenkins URL field, enter the URL of the Jenkins server.
6. In the HTTP Request section, create a record for authentication by completing the following steps:
   1. Click Add next to Basic/Digest Authentication.
   2. In the Key Name field, enter a name for the authentication record.
   3. In the Username field, enter the operator ID that is used for authenticating the service. This operator should belong to the access group that is associated with the application that has the tests that you want to run.
7. Select POST from the HTTP default mode list.
8. ​Click Apply, and then click Save.
9. Add a build step to be run after the project builds:
   1. Complete one of the following actions:
   • Create a project if you have not already done so.
   • Open an existing 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 the format http://<your application URL>/prweb/PRRestService/PegaUnit/Rule-Test-Unit-Case/pzExecuteTests.
   5. Optional: At the end of the URL, append the name of the access group that is associated with the application for which you want to run data page unit tests. Use the format ?AccessGroup:AccessGroup, for example: http://myPega7PlatformHost:8080/prweb/PRRestService/PegaUnit/Rule-Test-Unit-Case/pzExecuteTests?AccessGroup=HRDepart:Administrators.

If you do not specify an access group name, the service uses the default access group for your operator ID. See Configuring your default access group.

10. From the HTTP mode list, select POST.
11. Click Advanced.
12. 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.
13. From the Authenticate list, select the name of the authentication record that you provided in step 6b.
14. In the Post-build Actions section, 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.
15. Click Save.

Running tests and verifying results

After you configure your validation engine, run the service and verify the test results. For example, in Jenkins, complete the following steps:

1. Open the project and click Build Now.
   • If you did not specify an access group, all data page unit tests are run for the application that is associated with the default access group for your user ID.
   • If you specified an access group, the data pages are run for the application that is associated with the access group.
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.
• An application is not associated with the access group passed by the service.
• No data page unit test cases are in the application.