Open topic with navigation

Integrate your test suite to inform review acceptance or rejection

Integrating Helix Swarm with a test suite involves enabling Automated Tests in your project's configuration and providing a trigger URL. When the trigger URL is requested, Swarm expects your test suite to be executed. When the tests complete, Swarm expects either a pass callback URL or fail callback URL to be requested by your test suite.

1. Navigate to the project page.
2. Click the project Settings tab to display the Project Settings page.
3. Ensure that paths in each named branch configured for the project do not overlap with paths in other named branches.

4. Automated tests checkbox: select Enable to display the configuration fields:

   

5. Provide a URL that triggers your test suite execution.

   Special arguments are available to inform your test suite of various details from Swarm:

   {change}

   The change number

   {status}

   Status of the shelved change, shelved or committed

   {review}

   The review's identifier

   {project}

   The project's identifier

   {projectName}

   The project's name

   {branch}

   The branch identifier(s) impacted by the review, comma-separated

   {branchName}

   The branch name(s) impacted by the review, comma-separated

   {pass}

   Tests pass callback URL

   {fail}

   Tests fail callback URL

   Note

   The {pass} and {fail} are composed automatically by Swarm, and include Swarm's own per-review authentication tokens.

6. Optional: specify any parameters that your automated tests require that must be sent via HTTP POST in the POST Body field. The POST parameters can include the special arguments listed above.

   Select the format of the POST parameters, either URL Encoded or JSON Encoded.

   • URL Encoded: POST parameters are parsed into name=value pairs.
   • JSON Encoded: parameters are passed raw in the POST body.

Configuring Jenkins for Swarm integration

1. Install the p4-plugin in Jenkins:

   https://wiki.jenkins-ci.org/display/JENKINS/P4+Plugin

2. Configure a Jenkins project:

   1. Specify the job name so that it matches the project identifier used in the trigger URL, as defined below.

      For example, the computed value of {projectName}_{branchName}.

      Or, edit the trigger URL to use the Jenkins job name you specify.

   2. Make the build parameterized to accept these parameters (note that these are named to match up with the script that is called):

      {status}

      Whether the changelist to be tested is shelved or submitted

      {change}

      Changelist # to run tests against

      {review}

      The review's identifier

      {pass}

      The URL to wget if the build succeeds

      {fail}

      The URL to wget if the build fails

   3. Select Perforce Software for the Source Code Management section.

      Important

      You may see Perforce in the Source Code Management section. This represents an earlier community-provided Perforce plugin that does not include support for Swarm.

   4. Set up credentials and workspace behavior as needed.

      See the Credentials and Workspaces sections of the p4-plugin documentation for details.

      Important

      • If your Helix Server is configured for Multi-Factor Authentication (MFA), the service user credentials used for automated testing must not use MFA.
      • The client workspace configured in Jenkins must have a view that includes the paths defined for that branch in Swarm.

3. Configure your Swarm project to run automated tests with a URL like this:

   http://jenkins_host:8080/job/{projectName}_{branchName}/review/build?status={status}&review={review}&change={change}&pass={pass}&fail={fail}

   Important

   For Jenkins, the job name needs to match the job identifier in the URL. In the example above, this is the computed value of {projectName}_{branchName}.

   If you prefer a different naming scheme in Jenkins, replace {projectName}_{branchName} in the URL above with the project name actually defined in Jenkins.

   Note

   If your build script has access to the results of test execution, include a GET or POST parameter called url when calling the pass or fail URLs. Swarm uses the provided url to link reviews to the test results.

   Important

   If security is enabled in Jenkins, the trigger URL needs to include credentials. Follow these steps:

   1. Create a Jenkins user that will trigger Swarm builds. For example swarm.
   2. Log into Jenkins as the new user.
   3. Click on the user's username in the Jenkins toolbar.
   4. Scroll down to API Token.
   5. Click Show API Token.

   6. Incorporate the value of the API Token into the Swarm trigger URL.

      For example, if the username is swarm and the API Token value is 832a5db7e5500c1288324c1441460610, the Swarm trigger URL should be:

      http://swarm:832a5db7e5500c1288324c1441460610@jenkins_host:8080/job/{projectName}_{branchName}/review/build?cause=Automated%20test%20triggered%20for%20Swarm%20project%20{projectName},%20branch%20{branchName},%20review%20{review}&status={status}&review={review}&change={change}&pass={pass}&fail={fail}