View source for Integrating Pega unit tests and scenario tests into build tools and pipelines

{{Design pattern|Title=Integrating unit tests into build tools and Jenkins|Description=Guidelines on integrating Pega unit tests and  scenario tests into build tools and Jenkins|Version=8.5|Applications=Pega Platform|Capability Area=DevOps|Owner=Vishwanatham, tejodeep}}

Unit testing automation is a key stage of a continuous development and continuous integration model of application development. With continuous and thorough testing, you can identify and fix issues prior to releasing an application, which improves the application quality. Continuous and automated unit testing is complete with the help of build tools like Maven, Gradle, and so on, while continuous integration needs tools like Jenkins, Bamboo.

== Integration with build tools ==
Software build tools are used to automate the creation of executable applications from source code. They script or automate a variety of tasks, such as downloading dependencies, compiling and packaging code, running tests, and deployment. Examples of build tools include Apache Ant, Apache Maven, and Gradle.

As Gradle is a widely used build tool, the following sections describe how to execute unit and scenario tests from a sample Gradle build script.

=== '''Execution of PegaUnit test cases through Gradle''' ===
Pega Platform provides a service to execute PegaUnit test cases or test suites in your application and return results in xUnit format. The service provides the following information: 
* '''Service name''': <code>PegaUnit Rule-Test-Unit-Case pzExecuteTests</code>
* '''Service package''': <code>PegaUnit</code>
* '''Endpoint''':<code>http://<yourapplicationURL>/prweb/PRRestService/PegaUnit/Rule-Test-Unit-Case/pzExecuteTests</code>
To invoke a unit rest service, add REST dependency in your Gradle script: 
[[File:Restgradledependency.png|thumb|663x663px|none|Adding REST dependencies]]

To create your Gradle task, send the following request parameters:
* '''Uri''': ''' '''Provide the end point URL of your application.
* '''Username''': Provide the operator name.
* '''Password''': Provide the password. 
* '''HTTP Method:''' Post. 
* '''Content Type''': XML.
For example, to execute unit tests through a Gradle task, enter the code as shown in the following figure:[[File:PegaUnitA.png|thumb|651x651px|none|Executing unit tests through a Gradle task]]'''Note:''' The Gradle task above can be called from the Jenkins pipeline as well as a standalone Gradle build task.

Pega Platform also provides another service to execute unit tests in asynchronous mode. This service returns polling ID as a response that can be used to track the execution output by using it with the REST service <code>/pegaunits/execute/{ID}/results</code>. The service provides the following information:
* '''Service name''': <code>pegaunits</code>
* '''Service package''': <code>api</code>
* '''Endpoint''': <code>http://<yourapplicationURL>/prweb/api/v1/pegaunits/execute</code>

=== '''Execution of Pega scenario tests through Gradle''' ===
Pega Platform provides service to execute Pega scenario tests and returns the status code of service. The service provides the following information:
* '''Service name''': <code>scenariotests</code>
* '''Service package''': <code>api</code>
* '''Endpoint''':<code>http://<yourapplicationURL>/prweb/api/v1/scenariotests/execute</code>

==== Query parameters ====
* '''JOB ID''': Unique Job ID/Run ID/Build number for the invocation (used by Deployment Manager to separate runs across deployments, also passed as the run ID to cloud providers for tracking)
* '''Provider''':  STANDALONE | CBT | BROWSERSTACK Test service provider to use (or Test service cloud provider)
* '''ProviderAuthName''': Authentication name for the test service account
* '''ProviderAuthKey''': Authentication key for the test service account
* '''ProviderURL''': Alternate test service provider URL (optional; generally used for local selenium hubs)
* '''Browser''': Browser for running the UI tests	
* '''BrowserVersion''': Browser version for running the UI tests
* '''Platform''': OS platform to use
* '''PlatformVersion''': OS platform version to use
* '''ScreenResolution''': Resolution of the test system screen for running the tests
* '''SUTURL''': URL of the Pega Platform system under test
* '''SUTUserID''': Test operator ID from the Pega Platform system under test
* '''SUTPassword''': Password of the test operator ID from the Pega Platform system under test.
* '''TestSuiteID''': <code>pxInsname</code> of the test suite to be executed

==== Executing scenario tests ====
#  ''Add a REST dependency to invoke a unit rest service from your Gradle script:''  <big><code>dependencies {</code></big>  <big><code>classpath group: 'org._10ne.gradle', name: 'rest-gradle-plugin', version: '0.4.2'</code></big>  <big><code>}</code></big>
# Build your service URL. For example:  <code><nowiki>http://xxx:8080/prweb/api/v1/scenariotests/execute?JobID=1&Provider=STANDALONE&ProviderURL=http://10.225.82.213:5555/wd/hub/&Browser=chrome&BrowserVersion=83.0.4103.39&Platform=XP&SUTURL=http://xxxx:8080/prweb/&SUTUserID=xxx&SUTPassword=xxx&TestSuiteID=xxxxx</nowiki></code>
# Create your Gradle task by sending the following request parameters:
#* '''Uri''': ''' '''Provide the end point URL of your application.
#* '''Username''': Provide the operator name.
#* '''Password''': Provide the password.
#* '''HTTP Method''': Post.
'''Note:''' Before running the service, ensure that the provider URL is up and running. See the References section on how to launch Selenium Grid and Browser stack.

[[File:Scenariotestgradletask.png|thumb|1060x1060px|none|''Sample Gradle task to execute Pega scenario tests'']]

== Integration with Jenkins ==
Jenkins is an open-source automation server. It helps automate the parts of software development related to building, testing, and deploying, while facilitating continuous integration and continuous delivery.

Jenkins is a highly used CI/CD tool. Learn how you can execute PegaUnit tests from the Jenkins pipeline project and Jenkins freestyle project.

=== '''Configuring a Jenkins pipeline''' ===
Call a Gradle task from a Jenkins pipeline configuration through the following steps:
# Open a web browser, and then navigate to the location of the Jenkins server.
# Create a Jenkins job of type <code>Pipeline</code>.
# Create a Jenkins pipeline script file to run the Gradle task from your <code>build.gradle</code>.  You can parameterize the URL, user name, and passwords, and pass them from the Jenkins file to the Gradle task.
[[File:Jenkinspipelinesnippet.png|thumb|799x799px|none|Sample Jenkins pipeline script file]]

=== '''Running a freestyle Jenkins project''' ===
Create a freestyle project (old-fashioned) and configure the Jenkins server to call the service.
# Open a web browser and navigate to the location of the Jenkins server.
# Install the HTTP request plug-in for Jenkins to call the service and the JUnit Plugin so that you can view reports in the xUnit format:
## Click '''Manage Jenkins''', and then click '''Manage Plugins'''.
## On the '''Available''' tab, select the '''HTTP Request Plugin''' check box and the '''JUnit Plugin''' check box.
## Specify whether to install the plug-in without restarting Jenkins or to download the plug-in and install it after restarting Jenkins.
# Configure the Pega Platform credentials for the operator who authenticates the Execute Tests service:
## Click '''Credentials''', and then click '''System'''.
## Click the drop-down arrow next to the domain to which you want to add credentials, and then click '''Add credentials'''.
## 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.
## In the '''Password''' field, enter the password.
## Click '''OK'''.
# Configure the Jenkins URL that runs the service:
## Click '''Manage Jenkins''', and then click '''Configure System'''.
## In the '''Jenkins Location''' section, in the '''Jenkins URL''' field, enter the URL of the Jenkins server.
## Click '''Apply''', and then click '''Save'''.
# Add a build step that you want to run after building the project:
## Open an existing project or create a project.
## Click '''Configure'''.
## In the '''Build''' section, click the '''Add build''' step, and then select '''HTTP Request''' in the list.
## In the '''HTTP Request''' section, in the '''URL''' field, enter the endpoint of the service in the following format:  <code>http://<your application URL>/prweb/PRRestService/PegaUnit/Rule-Test-Unit-Case/pzExecuteTests</code>
# In the '''HTTP mode''' list, select '''POST'''.
# Click '''Advanced'''.
# In the '''Authorization''' section, in the '''Authenticate''' list, select the Pega Platform operator ID that authenticates the service that you configured in step 3.
# 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 <code>LocationOfResults</code> request parameter.
# In the '''Post-build Actions''' section, from the '''Add post build section''' list, select the '''Publish Junit test result''' report and enter <code>**/*.xml</code> in the '''Test Report XML''' field.  This setting configures the results in the xUnit format, which provides information about test results, such as a graph of test results trends, on your project page in Jenkins.
# Click '''Apply''', and then click '''Save'''.
# After job configuration. you can run your test suites and test cases.
# Open the project and click '''Build Now'''.
# In the '''Build History''' pane, click your build.
# On the next page, click '''Test Result'''.
# In the '''All Tests''' section, click root.  The results of all failed tests and all tests are displayed.

== Running PegaUnit tests and scenario tests in Deployment Manager ==

=== '''Configuring Deployment Manager to execute unit tests'''  ===
The unit testing task is run for the access group that is specified in the '''Application test cases''' section, which you configure when you add or modify a pipeline.
# Do one of the following actions:
#* Click a manually added task, click the '''More''' icon, and then click either '''Add task''' '''above''' or '''Add task below'''.
#* In a stage, click '''Add task'''.
# To run unit tests for either the pipeline application or for an application that is associated with an access group, in the '''Task''' list, select '''PegaUnit testing'''.
# '''Optional:''' Perform one of the following actions:
#* To run all the unit tests that are in a unit suite for the pipeline application, in the '''Test Suite ID''' field, enter the value of the <code>pxInsName</code> parameter of the test suite.   You can find this value in the XML document that provides the test suite in Pega Platform, by clicking '''Actions''' > '''XML''' on the '''Edit Test Suite''' form. If you do not specify a test suite, all the unit tests for the pipeline application are run.
#* To run all the unit tests for an application that is associated with an access group, in the '''Access Group''' field, enter the access group. 
# Click '''Submit'''.

=== '''Configuring Deployment Manager to execute scenario tests'''  ===
# Do one of the following actions:
#* Click a manually added task, click the '''More''' icon, and then click either '''Add task above''' or '''Add task below'''.
#* In a stage, click '''Add task'''.
# In the '''Task''' list, select '''Run Pega scenario tests'''.
# In the '''User name''' field, enter the user name for the Pega Platform instance on which you are running scenario tests.   For the <code>Run Pega scenario tests</code> task, if you are using a separate product rule for a test application, the user name that you provide should belong to the access group that is associated with the test application. 
# In the '''Password''' field, enter the Pega Platform password.
# In the '''Test Service Provider''' field, select the browser that you are using to run the scenario tests in the pipeline.
# Do one of the following actions:
#* If you selected '''CrossBrowserTesting''', '''BrowserStack''', or '''SauceLabs''':
#** In the '''Provider auth name''' field, enter the authentication name that you use to log in to the test service provider.
#** In the '''Provider auth key''' field, enter the key for the test service provider.
#* If you selected '''Standalone''', in the '''Provider URL''' field, enter the URL of the Selenium Standalone Server by using one of the following details:
#** Hub hostname and port.  Use the following format: <code>Hubhostname:port</code>
#** IP address.   Enclose the IP address in double quotation marks.
# In the '''Browser''' field, enter the browser that you are using to record scenario tests.
# In the '''Browser version''' field, enter the browser version.
# In the '''Platform''' field, enter the development platform that you are using to record tests.
# In the '''Screen resolution''' field, enter the resolution at which you want to record scenario tests.
# Click '''Submit'''.

== References: ==
https://community.pega.com/knowledgebase/articles/devops-release-pipeline-overview/running-pegaunit-test-cases-and-test-suites-execute-tests-service-pega-74

https://collaborate.pega.com/discussion/crossbrowsertesting-integration-scenario-testing-framework

https://collaborate.pega.com/discussion/browserstack-integration-scenario-testing-framework

https://collaborate.pega.com/discussion/selenium-grid-integration-scenario-testing-framework

https://community.pega.com/knowledgebase/articles/devops-release-pipeline-overview/using-deployment-manager-45x