https://github.com/neiljbrown/restassured-example
An example of how to use the REST-assured library to write black-box, functional tests for REST APIs in Java.
https://github.com/neiljbrown/restassured-example
api examples rest restassured test-automation testing testing-tools wiremock
Last synced: 6 months ago
JSON representation
An example of how to use the REST-assured library to write black-box, functional tests for REST APIs in Java.
- Host: GitHub
- URL: https://github.com/neiljbrown/restassured-example
- Owner: neiljbrown
- Created: 2017-12-29T15:51:41.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2018-06-09T20:56:11.000Z (over 7 years ago)
- Last Synced: 2025-03-28T02:11:11.739Z (7 months ago)
- Topics: api, examples, rest, restassured, test-automation, testing, testing-tools, wiremock
- Language: Java
- Homepage:
- Size: 81.1 KB
- Stars: 7
- Watchers: 1
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# REST-assured Example
## Overview
This project provides an example of how to use the [REST-assured](http://rest-assured.io/) library to write black-box,
functional tests for REST APIs in Java.REST-assured is a Java library that aims to make it simpler to write out-of-process, functional tests for REST APIs,
that are written in Java (or other JVM languages). It runs on top of existing Java testing frameworks (JUnit), and
includes a DSL for building API requests and asserting API responses.
In this example project, REST-assured is used to implement a suite of functional tests for a couple of REST APIs
hosted by an imaginary User service that supports creating and retrieving a resource/entity known as a (user) 'realm',
via HTTP POST and GET methods. An outline spec. of these APIs is included below.
## Code
The example REST-assured test cases are implemented in Java (8.x) using JUnit (4.x), REST-assured (3.x) and AssertJ.The tests can be found in two Java classes in the project's src/main/test/java folder:
* com.neiljbrown.service.user.CreateRealmApiTest - Test suite for the [Create Realm API](#createRealm)
* com.neiljbrown.service.user.GetRealmApiTest - Test suite for the [Get Realm API](#createRealm)The APIs under test have been stubbed-out (using the [WireMock](http://wiremock.org/) library). This makes the example
tests simple to run, by avoiding a dependency on a real API service having been deployed, and needing to be
running in a separate process. For the purposes of this project you can ignore the stubbing and use of WireMock.## Building and Running the Examples
The example tests can be compiled and run from within the comfort of your IDE (or from the command line using
Gradle).First ensure you have JDK 8+ installed.
Then cd to the directory into which you cloned/checked-out the project and use the supplied Gradle build script to
generate an IDE project for either Eclipse or IntelliJ IDEA, using one of the following commands
``./gradlew eclipse`` or ``./gradlew idea``Import the generated project into your IDE.
Open the project in your IDE and run the tests contained in one of the aforementioned test classes as you would a
JUnit test.To compile and run the tests from the command line enter the command ``./gradlew test``
## Debugging the Examples
You can debug execution of the tests from within your IDE by setting breakpoints as you would with any other JUnit test.The example tests also support logging of the HTTP requests and responses which they make to the console, using
REST-assured's underlying logging support. By default only failed requests and responses are logged (which is also the
REST-assured default). You can additionally enable logging of successful requests and responses by setting the Java
system property 'qatest.alwaysLogReqAndResp' to 'true', e.g. java ... -Dqatest.alwaysLogReqAndResp=true.An example of an HTTP request and response logged by REST-assured is shown below -
```
Request method: POST
Request URI: http://localhost:52650/user/realm
Proxy:
Request params:
Query params:
Form params:
Path params:
Headers: Accept=application/xml
Content-Type=application/xml; charset=ISO-8859-1
Cookies:
Multiparts:
Body:iNuZRnYHQNvGIgxKnnBmfLbzuPvuRlpdIilHhFxmpKAKCaUMBlkYQePxcHJkfcEFqwhFyWcXLnWEDMUMTHXhBEzHyyIdipHceXhovqarMpPZUGCcpCKtGDRmJLckMuHmHYbNOCzdAAzvuLsBxucrmMnLFWbDvwsyZFNlEkzZRzBVJFUunXkDIjPnwoPlKceuOjwMsLOUPXdbKwQWmKoTIxXqTadTkEyxhfkATjsQkfElnPSZVwKSfXRfDyWaogUQ
```
## API Specification
This section contains the spec. of the couple of APIs for which the tests have been written.The APIs specified support creating, retrieving and deleting a (User) Realm.
### Realm Resource
A (User) Realm is a context for the registration and authentication of a user. The resource comprises the following
fields. All fields are mandatory unless otherwise stated.|Field Name|Description & Constraints|
|----------|-------------------------|
|id|Unique, system-generated identifier for the realm. An integer value in the range 1 to 9999.
|name|Unique name of the realm. Serves as an alias for the realm ID. Max length of 100 chars.|
|description|Description of the realm. Optional. Max length of 255 chars.|
|key|System generated encryption key. Fixed length 32 char hex-encoded string.|### Resource Representation
The APIs only support producing and consuming XML representations of a Realm. The schema for this representation,
specified by example, is as follows -```xml
Realm for authenticated users of Acme corp.
92f1aea4bb92c3661a9c85ee81503e28
```### API Error Handling
The APIs report errors by returning an HTTP response with a status code in the 4xx (client) or 5xx (server) range. An
“error” resource may also be returned in the response body to distinguish errors reported by the API, and to
further classify an error. An error resource contains a unique code and a message. The error code is a unique string
in camel-case intended for interpretation by API clients. An example HTTP response for an error returned by the APIs
is shown below -```
HTTP/1.1 404 Not Found
Content-type: application/xml; charset=utf-8
...
RealmNotFound
Realm [123] not found.```
### Create Realm API
Creates a new realm including the generation of an encryption key.#### Supported Methods
|Method|URL|
|------|---|
|POST|http://{host}:8080/user/realm|#### Example Request
```
POST /user/realm HTTP/1.1
Content-Type: application/xml; charset=utf-8
{description}```
#### Example Success Response
```
HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8
{description}
{key}```
#### Example Error Response
If the mandatory realm name is not supplied or if supplied is blank/empty:
```
HTTP/1.1 400 Bad Request
Content-type: application/xml; charset=utf-8
MissingRealmName
Realm name is mandatory and must be supplied.```
If the requested realm name matches the name of an existing realm.
```
HTTP/1.1 400 Bad Request
Content-type: application/xml; charset=utf-8
DuplicateRealmName
Duplicate realm name [{realmName}].
```If the requested realm name is longer than 100 chars.
```
HTTP/1.1 400 Bad Request
Content-type: application/xml; charset=utf-8
InvalidRealmName
Realm name should not be longer than 100 chars.
```If the requested realm description is longer than 255 chars.
```
HTTP/1.1 400 Bad Request
Content-type: application/xml; charset=utf-8
InvalidRealmDescription
Realm description should not be longer than 255 chars.```
Other error responses
|HTTP Status Code & Phrase|Cause|
|-------------------------|-----|
|415 Unsupported Media Type|The entity supplied in the body of the request cannot be processed in the media-type specified in the Content-Type request header.|### Get Realm API
Returns the details of an individual realm, identified by its unique id.#### Supported Methods
|Method|URL|
|------|---|
|GET|http://{host}:8080/user/realm/{realmId}|#### Example Request
```
GET /user/realm/{realmId} HTTP/1.1
Accept: application/xml
```
#### Example Success Response
```
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
{description}
{key}
```#### Example Error Response
If the requested realm id is not an integer value or if it is an integer value larger than the allowed maximum (9999).
```
HTTP/1.1 400 Bad Request
Content-type: application/xml; charset=utf-8
InvalidRealmId
Invalid realm id [{realmId}].```
If the requested realm id does not identify an existing realm.
```
HTTP/1.1 404 Not Found
Content-type: application/xml; charset=utf-8
RealmNotFound
Realm [123] not found.```
### Delete Realm API
Deletes a user realm by id.#### Supported Methods
|Method|URL|
|------|---|
|DELETE|http://{host}:8080/user/realm/{realmId}|#### Example Request
```
DELETE /user/realm/{realmId} HTTP/1.1
```#### Example Success Response
```
HTTP/1.1 204 No Content
Date: Tue, 15 Nov 2017 08:12:31 GMT
```#### Example Error Response
If the requested realm id is not an integer value
```
HTTP/1.1 400 Bad Request
Content-type: application/xml; charset=utf-8
InvalidRealmId
Invalid realm id [{realmId}].```
### Common Errors
The following error responses that could be returned by any of the APIs above:|HTTP Status Code & Phrase|Cause|
|-------------------------|-----|
|405 Method Not Allowed|The specified HTTP method is not supported for the requested resource.|
|406 Not Acceptable|The requested resource cannot be returned in the media-type specified by the Accept header.|