Introduction

Stubit

Stubit is a collection of extremely simple stubs to replace typical infrastructure dependencies.

To review the code, file issues or suggest changes, please visit the project’s GitHub page.

Getting Started

Requirements

In oder to use Stubit you need a JDK 17 or higher.

Dependencies

To use Stubit in your own project, you need to add it as a dependency to your project.

Gradle
implementation 'org.stubit:http:0.3-SNAPSHOT'
Maven
<dependency>
  <groupId>org.stubit</groupId>
  <artifactId>http</artifactId>
  <version>0.3-SNAPSHOT</version>
</dependency>
The http is an example module.

Bill of Materials (BOM)

If you want to use more than one module in the same project, you can use Stubit’s bill of materials (BOM) and omit the explicit version for the other modules.

Gradle
implementation platform('org.stubit:bom:0.3-SNAPSHOT')
implementation 'org.stubit:http'
Maven
<project>
  <!--…-->
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.stubit</groupId>
        <artifactId>bom</artifactId>
        <version>0.3-SNAPSHOT</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <!-- … -->
  <dependencies>
    <dependency>
      <groupId>org.stubit</groupId>
      <artifactId>http</artifactId>
    </dependency>
  </dependencies>
  <!-- … -->
</project>

HTTP

The HTTP module contains a simple HTTP server, which can be started locally to stub an HTTP service.

Create and Start the Stub

Instantiating the HttpStub class automatically starts the stub at a random local port.

try (var httpStub = new HttpStub()) {
  String stubAddress = httpStub.address();

  assertThat(stubAddress).isNotNull().startsWith("http://localhost:");
}

You can get its address via the address method

String stubAddress = httpStub.address();

Unstubbed Behaviour

By default, the stub will return a 404 response for any path and any method but POST.

var request = new Request.Builder().url(httpStub.address() + "/nothing/here").build();
var response = okHttpClient.newCall(request).execute();

assertThat(response.code()).isEqualTo(404);
assertThat(response.body().string()).isEqualTo("No stubbing for GET /nothing/here");

POST Requests

POST requests will by default return a 201 response for any path.

var postRequest =
    new Request.Builder()
        .url(httpStub.address() + "/nothing/here")
        .post(RequestBody.create("Hello".getBytes(StandardCharsets.UTF_8)))
        .build();
var postResponse = okHttpClient.newCall(postRequest).execute();

assertThat(postResponse.code()).isEqualTo(201);
assertThat(postResponse.body().string()).isEqualTo("Added stubbing for /nothing/here");
assertThat(postResponse.header("Location")).startsWith("http://localhost");

The body of the request will be returned for subsequent GET requests.

var request = new Request.Builder().url(postResponse.header("Location")).build();
var response = okHttpClient.newCall(request).execute();

assertThat(response.code()).isEqualTo(200);
assertThat(response.body().string()).isEqualTo("Hello");
This behaviour is likely to change in future releases!

Stub a Response

You can create a stubbing via the Stubbing.stub() method

Stubbing stubbing =
    Stubbing.stub()
        .path("/some/where") (1)
        .method("GET") (2)
        .returns(StubbedResponse.response().body("Hello").statusCode(200)); (3)
1 Specifies the path for the stubbing.
2 Specifies the method.
3 Specifies the response that will be returned.

The Stubbing then needs to be added via the add method

httpStub.add(stubbing);

Further requests matching the Stubbing will now return the StubbedRequest instead of the default response.

var request = new Request.Builder().url(httpStub.address() + "/some/where").build();
var response = okHttpClient.newCall(request).execute();

assertThat(response.code()).isEqualTo(200);
assertThat(response.body().string()).isEqualTo("Hello");