Lesson 1: End-To-End API Tests - WebTestClient
Let’s take a quick peek at the Javadoc describing this interface:
As we can see, WebTestClient uses WebClient internally to carry out the requests and provides different convenience methods to instantiate WebTestClient variables according to the various testing requirements we might have.
Let’s move forward and analyze which one is most suitable for our case.
2.4. Live API Tests
As we said, to test the API of our RESTful service from end to end, we want to make requests to a fully functional instance of the application. The most straightforward way of doing this is simply launching the application locally and creating tests that consume from it.
We call these “Live Tests” because we’re assessing a live instance independent of the lifecycle of the test (no matter if it’s live just locally or in production).
So let’s start our application by running the RwsbApp class from the IDE, or using the “mvn spring-boot:run” command in the console.
With this, we can go back to the CampaignEndToEndApiTest class and create our test case:
The code is simple and self-explanatory, but shows how powerful and valuable the WebTestClient functionality is.
First, we’re declaring and initializing a WebTestClient variable using the bindToServer method in order to indicate that we’ll connect to a live server and provide the base URL for it. We’re pointing to localhost:8080 because that’s the port our application is listening to locally.
Then, in the test method, we’re simply instructing the request that should be carried out and the expected response aspects that we want to check.
For this, the testing framework provides a fluent API to indicate the following:
- the HTTP Method of the request we want to execute (in this case, GET)
- the endpoint of the service we want to call (“//3”)
- to perform the request afterwards with the exchange() method
- to verify that the status of the response is “200 OK”
Let’s run the test and see what happens:
As we can see, the test is successful, indicating the endpoint is valid and healthy.
Next, let’s analyze how we can improve this test case by changing the approach we use to test the REST API.
2.5. End-to-End Integration API Tests
As we can see, this test requires manually launching the application before running the tests, which can be very inconvenient, especially for a CI environment.
Ideally, we’d like to avoid performing any manual setup to test the service API, and for this, we’ll rely on some handy Spring Boot features.
Let’s update the test accordingly:
What’s happening here is:
- The @SpringBootTest annotation tells the framework to start a Spring application context.
- The “webEnvironment=RANDOM_PORT” argument instructs to start the server in a random port.
- To point to this running service, we let the framework inject the assigned random port into a variable via the @LocalServerPort annotation.
- Use this port variable to form the baseUrl when initializing the WebTestClient instance dynamically
- For this, we have to move the WebTestClient initialization logic inside the test case (or alternatively in a @BeforeEach method), since we need to wait for Boot to inject the port value first
We can now stop the service we previously launched, and execute the test again:
As we can see, the test passed successfully. Even though we’re still technically running the validations against a Live instance (which is started ad hoc), we can consider this a simple Integration Test because it doesn’t test a pre-existing Live instance of a service.
It’s worth noting that, as we can see in the image above, this test took a significant amount of time to get executed compared to our previous run, as it has to go over the whole application initialization process before finally executing the test case.
2.6. Spring Boot WebTestClient Autoconfiguration
There’s one final step to further simplify our test case by using a helpful Spring Boot feature.
Simply put, when we use @SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT), Spring Boot automatically sets up a WebTestClient instance in the context pointing to the assigned port, in order to avoid the overhead of having to do this ourselves.
So, knowing this, we can simplify the test by directly autowiring the variable
We can execute the test one last time to confirm it works as expected:
2.7. Conclusion
In summary, in this lesson, we learned how to use the WebTestClient to validate our service’s API with End-to-End tests.
We also explored the practical support Spring Boot provides for this, but not without analyzing in detail what the different Boot mechanisms bring to the table, and how they fit together to simplify the test class as much as possible.
In a future lesson, we’ll go further into detail on the functional capabilities offered by WebTestClient.