- April 03, 2017

This article is part of a blog posts series on how to automate your API test scenarios with different CI/CD platforms. This issue will help you get started with Circle CI. You may want to take a look at the Travis CI tutorial as well. Interested to see one in particular? Please let us know by writing a comment!

Restlet Client Test Scenarios

Restlet Client is a powerful tool for not only calling APIs and inspecting HTTP responses, but it also helps developers and testers validate their API behavior. Specifically, Scenarios let you build test APIs that reflect real-life API usage. Designing test scenarios is simple and visual. Expressions can be used to chain requests and set expectations on responses.

Here’s an example of a basic scenario that does some data validation on Paul Hallett’s Star Wars API:

Here’s the scenario to import into your Restlet Client so that you can quickly try this example.

Once your test scenarios are defined in Restlet Client, chances are that you would like to integrate them as part of your Continuous Integration / Continuous Delivery pipeline. This is made possible by the Restlet Client Maven test runner.

You can export a runnable scenario by clicking on the “export to Maven” button. You’ll be offered an option to download a pre-configured Maven project to get started quickly. It’s composed of two files: the test scenario in the form of a JSON file and a Maven pom.xml configuration file.

By typing mvn test in your terminal, you’ll trigger the execution of your scenario on your computer:

In real life, you’ll probably want to have a single project storing all your test scenarios. You’ll find the same export options on Restlet Client projects.

Circle CI

Circle CI is a modern continuous integration and delivery platform. It allows projects to tackle both continuous testing and deployment easily. Your first execution container is given for free, so just login with your Github account and you’re set.

Running your scenarios on Circle CI

First thing to do in order to run your scenario on Circle CI is to push it to a Github repository. Make sure you push the two files mentioned above: the JSON file containing your scenario and the pom.xml configuration file.

Second step is to enable this project through the Circle CI console in the “Projects” tab. Select the Github user or organization the project belongs to and click on “Build project”:

To use the defaults in Circle CI, nothing more is necessary. The platform will detect the project kind and execute tests if any.
To provide a specific Circle CI configuration into our project, simply add a circle.yml file at the root of your repository. We define here the JVM we want to use and the command to execute to run tests.

    version: openjdk8
    - mvn test

Setting up your license key

Test scenario automation through Maven is a premium feature, so you’ll be asked to enter your license key. Your license key is only for you and should not be published on a Github repository.
A simple way to securely manage your key is to add it as an environment variable in the project settings within Circle CI:

Simply add it using the “Add Variable” button:


To use this environment variable, just update the command to start tests within the previous circle.yml file, as described below:

    version: openjdk8
    - mvn test -Dlicense_key=$LICENSE_KEY

license_key property can then be used in your pom.xml:


See an example of circle.yml and pom.xml files.

Automating scenario execution in Circle CI

As a team developing an Web API, we would like to run our API Tests each time the Web API project is built and deployed successfully.

To do so with Circle CI, we’ll have two builds: one responsible for building and deploying the actual Web API, the other one responsible for the testing the deployed API. We’ll configure the first build so that it will trigger the second one after each successful deployment. 

The following figure provides an overview of this approach:


To trigger the execution of test scenarios after the Web API is successfully deployed,  we need to leverage the deployment part of Circle CI configuration and add a second command after the actual deployment. The second command is a call to the Circle CI API which will trigger the API test execution.

Here is an example of such configuration (with a deployment on Heroku):

    branch: master
      - git push $CIRCLE_SHA1:master
      - curl -v -X POST$CIRCLE_TOKEN

This way, each time we’ll push a change, the API will be built, deployed and tested thanks to Circle CI and Restlet Client Test Scenarios!


Are you interested in automating your API tests on Circle CI? Start now with a free trial of the Restlet Platform!