Spock and testing RESTful API services

gowebing
Spock is a BBD testing framework that allows for easy BDD tests to be written. The framework is an extension upon JUnit which allows for easy IDE integration and using existing JUnit functionality. Spock tests are written in Groovy and can be used for writing a wide range of tests from small unit tests to full application integration tests.
Without going into too much detail on how to write Spock based tests (see below for a few excellent links), lets go through how we can use the framework to build integration tests for testing a RESTful API.

Our first RESTful API Test


package com.wolfware.integration

import groovyx.net.http.RESTClient
import spock.lang.*

import spock.lang.Specification

import com.movideo.spock.extension.APIVersion
import com.movideo.spock.extension.EnvironmentEndPoint

@APIVersion(minimimApiVersion="1.0.0.0")
class GetAuthenticationToken extends Specification {

@EnvironmentEndPoint
protected def environmentHost

def "Get authentication token XML from API for valid account"() {
given: "a valid account"
def authenticationTokenRequestParams = ['key':"AAABBBCCC123", 'user':"myauthemail@bla.com"]

and: "a client to get the authentication token XML"
def client = new RESTClient(environmentHost)

when: "we attempt to retrieve authentication token XML"
def resp = client.get(path : "/authenticate", query : authenticationTokenRequestParams)

then: "we should get a valid authentication token XML response"
assert resp.data.token.isEmpty() == false
// lots more asserts
}
}


As you can see, apart from the @APIVersion and @EnvironmentEndPoint annotations (these are Spock extensions as explained later), the spec is a fairly simple Spock test.

This specification has a feature that, as the name suggests, gets a authentication token in XML format and validates it. Lets look at each step:
Given
  • The url parameters required to get a authentication token from the RESTful service
When
  • using the Groovy RestClient to call the RESTful service for the authentication token details
Then
  • We can assert all the details of the response.
The thing I really like about Spock is the readability of the tests. From the name being a descriptive sentence rather than some short hand with _ throughout to make a valid method name to being able to easily see where setup of the test is done and then the expectations and assertions.

Trying to test any environment RESTful service

I've found that when trying to write integration tests, there has either been:
  • Hard coded environment details and the code branched for each environment making it near impossible to keep code in sync as merge hell becomes the norm.
  • Config files that define the environment are used to define environment details, again checked into each branch for each environment.
Trying to follow the principles of continuous delivery, it would be great to be able to use the same code base to test against any environment. This is where Spock Extensions come into play to help us out.

Spock Extensions

In short Spock allows us to extend it to perform other functionality during the test life-cycle (a great post on extensions can be read on this excellent blog post). I've developed two extensions which help to make the idea of running the same test suite across different environments easier.

The @EnvironmentEndPoint Extension

The aim of this Spock extension is to have a placeholder variable in code that at run-time, can be defined with the environment host of the RESTful services that we want to test. 
package com.movideo.runtime.extension.custom

import org.apache.commons.logging.Log
import org.apache.commons.logging.LogFactory
import org.spockframework.runtime.extension.AbstractAnnotationDrivenExtension
import org.spockframework.runtime.extension.AbstractMethodInterceptor
import org.spockframework.runtime.extension.IMethodInvocation
import org.spockframework.runtime.model.FieldInfo
import org.spockframework.runtime.model.SpecInfo

/**
* Spock Environment Annotation Extension
*/
class EnvironmentEndPointExtension extends AbstractAnnotationDrivenExtension<EnvironmentEndPoint> {

private static final Log LOG = LogFactory.getLog(getClass());

private static def config = new ConfigSlurper().parse(new File('src/test/resources/SpockConfig.groovy').toURL())

/**
* env environment variable
* <p>
* Defaults to {@code LOCAL_END_POINT}
*/
private static final String envString = System.getProperties().getProperty("env", config.envHost);

static {
LOG.info("Environment End Point [" + envString + "]")
}

/**
* {@inheritDoc}
*/
@Override
void visitFieldAnnotation(EnvironmentEndPoint annotation, FieldInfo field) {
def interceptor = new EnvironmentInterceptor(field, envString)

interceptor.install(field.parent.getTopSpec())
}
}

/**
* 
* Environment Intercepter
*
*/
class EnvironmentInterceptor extends AbstractMethodInterceptor {
private final FieldInfo field
private final String envString

EnvironmentInterceptor(FieldInfo field, String envString) {
this.field = field
this.envString = envString
}

private void injectEnvironmentHost(target) {
field.writeValue(target, envString)
}

@Override
void interceptSetupMethod(IMethodInvocation invocation) {
injectEnvironmentHost(invocation.target)
invocation.proceed()
}

@Override
void install(SpecInfo spec) {
spec.setupMethod.addInterceptor this
}
}
The EnvironmentEndPointExtension class defines the following:
  • config: is a ConfigSlurper that parses a config file 'SpockConfig.groovy' that is used to define the default environment host (envHost)
  • envString: gets the value of 'env' from all System Properties (these include run-time properties) and defaults to config.envHost
With the environment host able to be accessed by Spock, now we need to inject this into the placeholder variable for Spock tests to access.
An interceptor is created which is used to inject( field.writeValue method) the value of the environment host into the placeholder variable. This placeholder is the one that the @EnvironmentEndPoint is annotating.
When the test is run, the interceptor sets the placeholder variable and the test can then use this value as the host for the RestClient object.
When running the Spock tests either the default value from the config file will be used or the JVM argument -Denv=? can be used. This makes running the same test code base against any environment so much easier.

A note on Gradle builds.

By default, Gradle will not pass through JVM arguments through to forked processes such as running tests. The code snippet below shows how to achieve this: 
/*
* Required to pass all system properties to Test tasks. 
* Not default for Gradle to pass system properties through to forked processes.
*/
tasks.withType(Test) {
def config = new ConfigSlurper().parse(new File('src/test/resources/SpockConfig.groovy').toURL())

systemProperty 'env', System.getProperty('env', config.envHost)
}
This allows all tasks that are a type of 'Test' to have some custom code run. In this case, we are defining the 'SpockConfig.groovy' config file and then setting 'systemPropery' within Gradle Test tasks to 'env' and either getting the value from the passed in JVM argument or from the config file.
With this code in the build.gradle, we're able to run all tests via a Gradle test build, which will produce lovely test reports (in Gradle HTML and JUnit XML).

The @APIVersion Extension

Another integration testing problem I've found is that if we try and develop our tests first (or at least during the process of developing a feature or bug fix) that running the same tests against an environment that doesn't yet have the new code base (but we are using the same test code base everywhere), we'll have failing tests that aren't really failures as the new code isn't there yet.
To help solve this problem, I've developed the @APIVersion extension to help with this issue. As newly developed code should be deployed with a new version, we can use this version to compare to a minimum version that a test can be run against. 
package com.movideo.runtime.extension.custom

import groovyx.net.http.RESTClient

import java.lang.annotation.Annotation
import java.util.regex.Pattern

import org.apache.commons.logging.Log
import org.apache.commons.logging.LogFactory
import org.spockframework.runtime.extension.AbstractAnnotationDrivenExtension
import org.spockframework.runtime.model.FeatureInfo
import org.spockframework.runtime.model.SpecInfo

/**
* API Version Extension
*
*/
class APIVersionExtension extends AbstractAnnotationDrivenExtension<APIVersion> {

/**
* Logger
*/
private static final Log LOG = LogFactory.getLog(getClass());

/**
* 
*/
private static def config = new ConfigSlurper().parse(new File('src/test/resources/SpockConfig.groovy').toURL())

/**
* env environment variable
* <p>
* Defaults to {@code LOCAL_END_POINT}
*/
private static final String envString = System.getProperties().getProperty("env", config.envHost);

/**
* Version REGX pattern
*/
private static final def VERSION_PATTERN = Pattern.compile(".", Pattern.LITERAL);

/**
* Max version length
*/
private static final def MAX_VERSION_LENGTH = 4;

/**
* Current API Version
*/
private static final def CURRENT_API_VERSION = getDeployedAPIVersion();

/**
* {@inheritDoc}
*/
@Override
void visitFeatureAnnotation(APIVersion annotation, FeatureInfo feature) {
if(!isApiVersionGreaterThanMinApiVersion(annotation, feature.name)) {
feature.setSkipped(true)
}
}

/**
* {@inheritDoc}
*/
@Override
public void visitSpecAnnotation(APIVersion annotation, SpecInfo spec) {
if(!isApiVersionGreaterThanMinApiVersion(annotation, spec.name)) {
spec.setSkipped(true)
}
}

/**
* Get the current deployed API version
* <p>
* Performs a HTTP request to the current deployed API version. Parses the returned data and get the {@code version} node data.
* @return current deployed API version
*/
private static String getDeployedAPIVersion() {
def apiVersion = null

try {
def client = new RESTClient(envString)
def resp = client.get(path : config.versionServiceUri)

apiVersion = resp.data.version

LOG.info("Current deployed API version [" + apiVersion + "]");
} catch (ex) {
APIVersionError apiVersionError = new APIVersionError("Error occurred attempting to get current deployed API version from %s", envString + config.versionServiceUri);
apiVersionError.setStackTrace(ex.stackTrace);

throw apiVersionError;
}

return apiVersion
}

* @param annotation
* @param infoName
* @return
*/
private boolean isApiVersionGreaterThanMinApiVersion(APIVersion annotation, String infoName) {
def isApiVersionGreaterThanMinApiVersion = true

def minApiVersionRequired = annotation.minimimApiVersion();

// normalise both version id's
def apiVersionNormalised = normaliseVersion(CURRENT_API_VERSION);
def minApiVersionRequiredNormalised = normaliseVersion(minApiVersionRequired);

// compare version id's
int cmp = apiVersionNormalised.compareTo(minApiVersionRequiredNormalised);

// if the comparison is less than 0, min API version is greater than the deployed API version
if(cmp < 0) {
LOG.info("min api version [" + minApiVersionRequired + "] greater than api version [" + CURRENT_API_VERSION + "], skipping [" + infoName + "]")
isApiVersionGreaterThanMinApiVersion = false
}

return isApiVersionGreaterThanMinApiVersion
}

* @param version
* @return
*/
private String normaliseVersion(String version) {
String[] split = VERSION_PATTERN.split(version);
StringBuilder sb = new StringBuilder();

for (String s : split) {
sb.append(String.format("%" + MAX_VERSION_LENGTH + 's', s));
}

return sb.toString();
}
}
The @APIVersion extension defines the same environment config as the @EnvironmentEndPoint extension does so that the environment can be injected and used purely for accessing the API version endpoint without the need for @EnvironmentEndPoint.
The RESTful API version endpoint is required to be setup and publicly available. The @APIVersion extension will call this service to get details about the version of RESTful API.
The version response data should be as follows: 
<ServiceInformation>
  <serviceName>Media API</serviceName>
  <version>1.51.1</version>
</ServiceInformation>
The @APIVersion extension will look for the version data to define what the current deployed version of the RESTful API is. Once the version of the RESTful API is known, the extension then checks the minimum API version required.
Example 
@APIVersion(minimimApiVersion="1.0.0.0")
The extension then uses this value to compare against the response data version and if the required version is greater than that of the deployed RESTful API services, then the test is skipped.
This extension annotation can be placed on Specification's or Feature's allowing whole Specs to have a minimum version and / or Features to have their own minimum version.
This extension has made writing integration tests with Spock even more portable and allows for a 'build once' set of tests that can be run against any environment, with some small changes to allow getting the API version.

The SpockConfig.groovy file

Here is an example of the SpockConfig.groovy config file used to configure defaults for both @EnvironmentEndPoint and @APIVersion extensions. 
versionServiceUri="/public/serviceInformation"
envHost="http://api.preview.movideo.com"
  • The 'versionServiceUri' is required for @APIVersion extension as the URI for the RESTful API version
  • The 'envHost' is required for both @APIVersion and @EnvironmentEndPoint extensions as the host of the RESTful API

Go and start testing

Hopefully these Spock extensions might help your Spock integration tests. The framework is really easy and fun to use to build essential tests for the whole test stack.
Checkout my GitHub projects for the code for both extensions.
Hope this post has been helpful and hopefully I'll post something sooner for my next post.

References and really helpful links

  • Spock Homepage
  • Annotation Driven Extensions With Spock

 

 

 

 

Top