Bastion User Guide (0.7-BETA)

For Java projects with a pom.xml file, you can add the following dependency to your <dependencies> section to download Bastion and make it available for your project’s tests.

If you are using Groovy scripts for your tests, you can easily download Bastion directly from within your script files, using Groovy Grapes. Add the following line to your import statement to download Bastion and make it available to your script.

If you’re using Gradle as your dependency management tool, add the following line to your Gradle file to use Bastion.

GeneralRequest is the universal HTTP request, able to take any arbitrary entity data string. To initialise a new GeneralRequest use any of the following static factory methods, giving the URL you want to send the request on:

Calling any of the above methods will give you an initialised GeneralRequest object which can be used with Bastion.request(). The request will not initially have any HTTP headers, query parameters or route parameters.

Once you have an instance of GeneralRequest, you can call methods to modify Headers, Query Parameters, Route Parameters as explained in section [request-attributes].

If you want to load entity data from a file instead of typing it out in source code, use FileRequest. This is very similar to GeneralRequest, in that you are not restricted to the type of data you’re sending. To initialise a new FileRequest use any of the following static factory methods, giving the URL you want to send the request on and a resource URL. Bastion will load the data from the specified URL and send it as the request data.

Bastion will attempt to guess what should go into the Content-type header depending on the filename. If a MIME type could not be chosen, application/octet-stream will be used as the MIME type.

JsonRequest is a request object specially designed to handle JSON data. Unlike GeneralRequest, JsonRequest will set the appropriate content type header to indicate that the data being sent has mime-type application/json. The request object is initialised using a JSON string (or file) and will validate the given data to ensure that it is valid JSON (if you don’t want this validation, use GeneralRequest instead). To initialise a new JsonRequest use any of the following static factory methods, giving the URL you want to send the request on:

The factory methods above also have utility methods which do not take an HttpMethod argument as follows:

Use the fromString() family of static factory methods to directly supply the JSON data to use in the test. You can simply type in your JSON request, as you would using an HTTP client, and Bastion will take care of all the other details related to JSON requests for you.

Use the fromResource() family of static factory methods to load a simple JSON file as the HTTP entity body. The fromResource() methods can take any URL including those beginning with the classpath: prefix (which loads a file from the classpath).

The fromTemplate() family of static factory methods are similar to fromResource() but they also take any additional argument containing a map where the keys are variable names and the values are the replacement values for the variable placeholders in the template.

The template files must be Mustache templates. An example Mustache template is shown below:

Notice the food variable in the template: this will get replaced by the value apples in the test above.

Use the fromModel() family of static factory methods to send any Java object serialized as a JSON string. You can annotate your object’s class with Jackson annotations to customise how the provided object is serialized.

Once you have an instance of JsonRequest, you can call methods to modify Headers, Query Parameters and Route Parameters as explained in section Request Attributes. You can also change the Content type header that is sent using overrideContentType() (by default, application/json is sent).

FormUrlEncodedRequest is a request object that allows you send URL encoded data as part of the HTTP request. This request is equivalent to requests sent by HTML forms (hence the Form in the name). The request will automatically be configured to have the mime-type application/x-www-form-urlencoded. Unlike JsonRequest, after initialising a ForumUrlEncodedRequest, you will need to call additional methods to fill in the request’s data.

First, use any of the following static factory methods and specify the URL to send the request to:

Use the addDataParameter() or addDataParameters() methods to add the data which will go into the request’s entity body. The FormUrlEncodedRequest will automatically format the data you supply, internally, into a URL encoded string. An example, using FormUrlEncodedRequest follows below,

Once you have an instance of FormUrlEncodedRequest, you can call methods to modify Headers, Query Parameters and Route Parameters as explained in section Request Attributes. You can also change the Content type header that is sent using overrideContentType() (by default, application/x-www-form-urlencoded is sent).

Bastion gives you the option of developing your own request classes. This is useful if you notice that you are repeatedly using a particular request in your tests. For the sake of maintainability and better software design, you can avoid repeatedly initialising the same request, over and over again, by implementing your own request type.

The relevant interface to implement is HttpRequest. This interface defines the following methods which you need to implement:

Once you’ve implemented your own HttpRequest, you can then pass it, as if it was any other request, to the Bastion.request() method.

The built-in HttpRequest implementations provided with Bastion are good examples. A simpler example is found in the test sources called CreateSushiRequest.

JsonResponseAssertions lets you test that specific JSON data has been received. The expected JSON data can be given as a JSON string, loading from a file or loaded and compiled from a template file.

It is important to realise that when comparing the expected JSON with the actual JSON received in the response, Bastion will be smart enough to ignore any trivial differences in the data. In particular, JSON is compared structurally as opposed to a straight-up string equality check. Properties (not array values!) may be in a different order and there might be whitespace in the received data, but unless the JSON structure is different, the test will pass.

First, you must initialise a JsonResponseAssertions object using one of the three static factory methods:

JsonResponseAssertions give some very useful insight into what your API under test is doing wrong. For example, the following test has been set up to fail.

Since the expected and actual JSON is compared structurally, Bastion outputs a JSON patch which describes exactly how to transform the actual JSON into the received JSON. For the test above, for example, we get:

For the above test to pass, we need to replace the value of the price property in the API with the value EUR 5.60.

Once you have a JsonResponseAssertions object, you can call the following methods on it, which will change the behaviour of the assertions Bastion performs:

This assertions object is similar to JsonResponseAssertions but takes a JSON schema as its input. The assertions object will check that the received response conforms to the given JSON schema. This is useful when you do not care about the actual content of the response (or perhaps you don’t know what it will be yet) but do care that it is always in a consistent format.

First, you must initialise a JsonSchemaAssertions object using one of the two static factory methods:

This is a simple assertions object which asserts that the HTTP status code of the response is as expected. You can supply multiple expected status codes and the assertion will pass if the status code matches any of the given expected status codes.

To instantiate a StatusCodeAssertions object use the StatusCodeAssertions.expecting() static factory method. The static factory method takes any number of HTTP status codes which will all be considered as valid response codes.

Bastion gives you the option of developing your own assertions classes. This is useful if you notice that you are repeatedly using a particular assertion in your tests. For the sake of maintainability and better software design, you can avoid repeatedly initialising the same assertions, over and over again, by implementing your own assertions type.

The relevant interface to implement is Assertions. This interface defines a single method which you need to implement: execute(). The execute() method takes the following parameters, which Bastion will provider when the test runs:

Notice that Assertions takes a generic type parameter. This type parameter describes the type of response model that the Assertions object is expecting. By supplying a good generic type argument in your Assertions subclass, the user will always have to bind() that model type before using your Assertions object (see Binding a Model section).

Once you’ve implemented your own Assertions, you can then pass it, as if it was any other assertions object, to the withAssertions() method.

The built-in Assertions implementations provided with Bastion are good examples.

Since the Assertions interface explained in Custom Assertions contains only one method, it is a functional interface which you can implement using a lambda as shown in the next example (the example below contains AssertJ assertions):