Automating Microcks tests with Jenkins

Microcks Jenkins plugin

Microcks provides a Jenkins plugin that you may find here: microcks-jenkins-plugin. This plugin allows your Jenkins builds and jobs to delegate the tests of microservices or API you just deployed to Microcks server. See this page on Tests for more informations on running tests with Microcks.

Using this plugin, it is really easy to integrate tests stages within your Continuous Integration / Deployment / Delivery pipeline. Microcks Jenkins plugin delegates tests realization and assertions checking to Microcks, wait for the end of tests or a configured timeout and just pursue or fail the current job depending on tests results.

Getting raw plugin

While not being distributed yet as an official Jenkins plugin, Microcks Jenkins plugin is available and can be downloaded from Central Maven repository. Just get the HPI file and install it on your Jenkins master your preferred way.

Building an OpenShift Jenkins master embedding plugin

A common option for running Jenkins is through OpenShift platform. In that case, you may want to create your own custom Jenkins master container image embedding this plugin. While there's many ways of building such images, as Microcks plugin is not yet an official Jenkins plugin, we provide our own OpenShift configuration for that.

Given you have an OpenShift installation running and you're logged on it, just execute that command from terminal:
oc create -f https://raw.githubusercontent.com/microcks/microcks-jenkins-plugin/master/openshift-jenkins-master-bc.yml

This should start a Build and then create an ImageStream called microcks-jenkins-master in your current project. After few minutes, a microcks-jenkins-master:latest container image should be available and you may be able to reference it as a bootstrap when creating a new Jenkins Service on OpenShift.

Using Microcks Jenkins plugin

Jenkins plugins may be used in 2 ways:

  • As a simple Build Step using a form to define what service to test,
  • As an action defined using Domain Specific Language within a Pipeline stage.

Simple build step usage

When defining a new project into Jenkins GUI, you may want to add a new Launch Microcks Test Runner step as shown in the capture below.

The parameters that can be set here are:

  • The API URL of Microcks server: this is your running instance of Microcks where services or API are defined,
  • The Service Identifier to launch tests for: this is simply a service_name:service_version expression,
  • The Test Endpoint to test: this is a valid endpoint where your service or API implementation has been deployed,
  • The Runner Type to use: this is the test strategy you may want to have regarding endpoint,
  • The Verbose flag: allows to collect detailed logs on Microcks plugin execution,
  • The Timeout configuration: allows you to override default timeout for this tests.

DSL plugin usage

When defining a new CI/CD pipeline - even through the Jenkins or OpenShift GUI or through a Jenkinsfile within your source repository - you may want to add a specific microcksTest within your pipeline script as the example below:


node('maven') {
  stage ('build') {
    // ...
  }
  stage ('deployInDev') {
    // ...
  }
  stage ('testInDev') {
    // Add Microcks test here.
    microcksTest(apiURL: 'http://microcks-microcks.52.174.149.59.nip.io/api',
      serviceId: 'Beer Catalog API:0.9',
      testEndpoint: 'http://beer-catalog-impl-beer-catalog-dev.52.174.149.59.nip.io/api/',
      runnerType: 'POSTMAN', verbose: 'true')
  }
  stage ('promoteToProd') {
    // ...
  }
  stage ('deployToProd') {
    // ...
  }
}
				

The parameters that can be set here are the same that in Build Step usage but take care to cases and typos:

  • The apiURL of Microcks server: this is your running instance of Microcks where services or API are defined,
  • The serviceId to launch tests for: this is simply a service_name:service_version expression,
  • The testEndpoint to test: this is a valid endpoint where your service or API implementation has been deployed,
  • The runnerType to use: this is the test strategy you may want to have regarding endpoint,
  • The verbose flag: allows to collect detailed logs on Microcks plugin execution,
  • The waitTime configuration: allows you to override the default time quantity for this tests.
  • The waitUnit configuration: allows you to override the default time unit for this tests (values in milli, sec or min).

Using Microcks and its Jenkins plugin, you may achieve some clean CI/CD pipelines that ensures your developed API implementation is fully aligned to expectations. See below a visualization of such a pipeline for our Beer Catalog API (full project to come soon).