mockito-rest-spring

This utility supports unit testing applications which consume external REST services defined using Swagger/OpenAPI, RAML or equivalent.

In a nutshell, mocking external REST services becomes as simple as mocking any other bean using Mockito.

Users will benefit from

• full-stack integration-style unit testing - over-the-wire mocking on local ports.
• Mockito support - i.e. full method/type safety
• simple setup using JUnit
  • @Extension for JUnit 5
• Tomcat, Jetty & Undertow support

The REST API must be available either in the form of an annotated interface or a concrete implemenation at compile time.

When working with OpenAPI definitions this usually means running the code generator two times:

• once for your model + client (main scope), and
• once for the to-be-mocked server (test scope).

Bugs, feature suggestions and help requests can be filed with the issue-tracker.

License

Apache 2.0

Obtain

The project is built with Maven and is available on the central Maven repository.

Maven coordinates

Add the property

<mockito-rest-spring.version>2.0.x</mockito-rest-spring.version>

then add for Tomcat

<dependency>
    <groupId>com.github.skjolber.mockito-rest-spring</groupId>
    <artifactId>junit5-tomcat</artifactId>
    <version>${mockito-rest-spring.version}</version>
    <scope>test</scope>
</dependency>

or Undertow

<dependency>
    <groupId>com.github.skjolber.mockito-rest-spring</groupId>
    <artifactId>junit5-undertow</artifactId>
    <version>${mockito-rest-spring.version}</version>
    <scope>test</scope>
</dependency>

or Jetty

<dependency>
    <groupId>com.github.skjolber.mockito-rest-spring</groupId>
    <artifactId>junit5-jetty</artifactId>
    <version>${mockito-rest-spring.version}</version>
    <scope>test</scope>
</dependency>

or

Gradle coordinates

For

ext {
  mockitoRestSpringVersion = '2.0.x'
}

add for Tomcat

api("com.github.skjolber.mockito-rest-spring:junit5-tomcat:${mockitoRestSpringVersion}")

or Undertow,

api("com.github.skjolber.mockito-rest-spring:junit5-undertow:${mockitoRestSpringVersion}")

or Jetty

api("com.github.skjolber.mockito-rest-spring:junit5-jetty:${mockitoRestSpringVersion}")

Usage

If you prefer skipping to a full example, see this unit test.

Basics

In your JUnit test, add a MockitoEndpointExtension extension:

@ExtendWith(MockitoEndpointExtension.class)

before (above) any SpringExtension or @SpringBootTest. Then mock service endpoints by using

@MockEndpoint
private MyRestService myRestService;

where the MyRestService is either an interface or a concrete @RestController implementation. For a custom (or missing) class level RequestMapping add a path parameter:

@MockEndpoint(path = "/rest")
private MyRestService myRestService;

The returned serviceMock instance is a normal Mockito mock(..) object.

Client configuration

The mock endpoint is started on a random free local port and saved to System property mockitoRestSpringServerPort.

Configure your client to pick up this value, for example via regular properties in Spring:

my.server.url=http://localhost:${mockitoRestSpringServerPort}/rest/pet

Details

Create mock response via code

// init response
MyResponse expected = new MyResponse();
expected.setCode(0);
expected.setValue("abc");

or from JSON

MyResponse response = jsonUtil.readResource("/example/MyResponse1.xml", MyResponse.class);

using your favorite JSON utility. Then mock

when(myRestService.method3(any(MyRequest.class)).thenReturn(expected);

or with a ResponseEntity wrapper (via OpenAPI useResponseEntity parameter):

when(myRestService.method3(any(MyRequest.class)).thenReturn(new ResponseEntity<>(expected, HttpStatus.OK));

and apply standard Mockito test approach.

Verifing calls

After triggering calls to the mock service, verify number of method calls

ArgumentCaptor<MyRequest> argument1 = ArgumentCaptor.forClass(MyRequest.class);
verify(myRestService, times(1)).method3(argument1.capture());

and request details

MyRequest request = argument1.getValue();
assertThat(request.getCode(), is(1));

Alternatives

While this project offers easy-to-setup testing, you might suppliment your testing using the following projects:

• Spring Mock MVC
• WireMock
• grpcmock

History

• 2.0.2: Dependency updates
• 2.0.1: Fix Tomcat temporary folder
• 2.0.0: Update to latest Spring, drop JUnit 4 support.
• 1.0.3: JUnit 5 support for Tomcat, Jetty and Undertow.
• 1.0.2: Improved JAXB helper, fix artifact id.
• 1.0.1: Support for API interfaces, including Swagger-generated stubs. See this unit test.
• 1.0.0: Initial version