GitHubContribute in GitHub: Edit online

Tutorial: Invoking test cases from Jenkins with JUnit result format

Before you begin

You must have the Automated API behavior testing application enabled and have created and published at least one test. You must have a Jenkins instance that you can create a new build in with the JUnit Plugin installed

About this tutorial

In this tutorial, you invoke a test case using injected variables from a jenkins pipeline

This tutorial takes you through the following steps

  1. Creating an API Hook
  2. Creating an API Key and Secret
  3. Creating a Jenkins build that invokes the API Hook
  4. Executing the build and reviewing the test results

Creating an API Hook

You can generate an API hook for each of the Test Suites within your Test Organization. API hooks are scoped to only one test suite and thus will only have access to operate on the data within that test suite; that is, if an API Hook is generated for Test Suite 1, it grants access only to the tests within Test Suite 1. If you wish to interact with tests in multiple test suites, you will need to generate an API hook for each Test Suite.

How to create an API Hook

  1. Navigate to the Test Organization settings page by clicking the Cog icon in the menu bar.
    Image of cog icon in the menu bar
  2. Within the Test Organization settings page, click the Hooks option under the API Hooks heading in the navigation menu.
    Image of hooks option in the test origanization page
  3. Now click on the + API Hook button to begin creating a new API Hook.
    Create API Hook
  4. Because API Hooks are scoped at a Test Suite level, you will need to select the test suite you wish to generate the hook for. Choose the appropiate test suite from the dropdown and optionally add a description for the API Hook. Click the confirmImage of check mark icon icon to generate and save the API Hook.
  5. The API Hook URL has been created for your Test Suite. Make a note of this this URL as this will form the base path of all future API requests you make for the test suite.

Creating an API Key and Secret

API Keys and Secrets are the credentials required to use an API Hook. For a request to an API Hook to be authorised, both the X-API-Key and X-API-Secret headers must be provided. The values of the API Key and Secret represent the values of these headers respectively.

  1. First navigate to the Test Organization settings page by clicking the Cog icon in the menu bar.
    Image of cog icon in the menu bar
  2. Within the Test Organization settings page, click the KEYS option under the API Hooks heading in the navigation menu.
    Image of Keys option in the test organization page
  3. Now click on the + API Key button to create a new API Key.
    Image of + API Key option in the test organization page
  4. You will then be shown the generated Key and Secret. Make a note of both of these, ensure the Secret is noted as it cannot be retrieved in the future. Give your new API Key a name and then click the confirm Image of check mark icon icon to save it.
    Image of confirm icon

Creating a Jenkins build that invokes the API Hook

  1. Create a Jenkins Project or navigate to an existing one

  2. Select Configure from the the options
    Configure Jenkins Project

  3. Under Build, click Add build step dropdown and select Execute Shell
    Jenkins execute shell

  4. Within the Execute shell block paste a curl command that will invoke the hook that was created in step 1

    curl -XPOST
-H 'x-api-key: <API-KEY>'
-H 'x-api-secret: <API-SECRET>'
-H "Content-type: application/json"
-d '{ options: { JUnitFormat: true }}'
'<API-HOOK-URL>/tests/run'
>| testReports.xml

  5. Under Post-build Actions, click Add post-build action and in the dropdown select Publish JUnit test results report.

    1. For Test report XMLs provide the name of the report created from the curl, in this tutorial testReports.xml
      Jenkins Post build action

  6. Save the project

Executing the build and reviewing the test results

  1. Click Build Now on the project
    Jenkins Build Now
  2. Once the build has completed, you will now see a chart showing
    Jenkins Project Page
  3. Click Latest Test results and review the Junit results
    Jenkins individual build results

To expand upon this tutorial additional options and steps can be found under Using API Hooks

What you did in this tutorial

In this tutorial you completed the following activities:

  • Created a API Hook
  • Created a Key and Secret used for authenicating with a hook
  • Invoked the API Hook using the Key and Secret to start a test and process the results