Testing
spring_boot_starter_test tests the web layer in two ways: in memory with MockMvc, through the same dispatcher, filters, binding and error handling as the server, or over a real socket, with the server started on a free port.
Why
A controller test should check what a client sees: the status, the headers, the JSON, the ProblemDetail of an error. Calling the controller method directly skips the mapping, the binding, @Valid, the filters and the exception handlers, which is where most web mistakes are. MockMvc sends a request to the application's dispatcherHandler bean, the one the server calls, only without a socket. A test that passes here behaves the same over HTTP, runs fast and needs no free port.
Start the real server when the client under test needs a connection: a Feign client, dart:io's HttpClient, a WebSocket client.
Setup
# pubspec.yaml
dev_dependencies:
build_runner: ^2.17.0
spring_core_dart_generator: ^0.9.0
spring_boot_starter_test: ^0.9.0
test: ^1.33.0
The tests start the application that the generator wrote for main: springApplication, in the generated main.spring.dart. Configuration for the tests goes to test/resources/ (for example application-test.properties), which comes before lib/resources/ during the tests.
Example
As functions:
// test/book_controller_test.dart
import 'package:spring_boot_starter_test/spring_boot_starter_test.dart';
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
import 'package:test/test.dart';
import '../bin/spring_gen/main.spring.dart';
void main() {
// Starts the whole application once, without a server.
final app = springBootTest(springApplication);
test('finds a book', () async {
await app.mockMvc.get('/api/books/978-0').andExpect(
status: 200,
contentType: MediaType.applicationJson,
json: {'isbn': '978-0', 'title': 'Dune'},
);
});
test('rejects an invalid book', () async {
await app.mockMvc
.post('/api/books', json: {'isbn': '', 'title': ''})
.andExpect(
status: 400,
contentType: MediaType.applicationProblemJson,
json: containsPair('detail', 'Invalid request content.'),
);
});
test('an unknown book is a 404 problem', () async {
await app.mockMvc
.get('/api/books/123')
.andExpect(status: 404, json: containsPair('detail', 'No book 123'));
});
test('creates a book', () async {
final result = await app.mockMvc
.post('/api/books', json: {'isbn': '978-1', 'title': 'Emma'})
.andExpect(status: 201, headers: {'Location': '/api/books/978-1'})
.andReturn();
expect((result.response.json! as Map)['title'], 'Emma');
});
}
As a test class, which the generator turns into the same calls:
// test/book_controller_class_test.dart
import 'package:spring_boot_starter_test/spring_boot_starter_test.dart';
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
import 'package:test/test.dart';
import 'spring_gen/book_controller_class.test.spring.dart'; // generated
@SpringBootTest()
@AutoConfigureMockMvc() // optional: states the intent, as in Spring
class BookControllerTest {
@Autowired()
late MockMvc mvc;
@Test()
Future<void> findsABook() async {
await mvc.get('/api/books/978-0').andExpect(
status: 200,
json: containsPair('title', 'Dune'),
);
}
}
void main() => runSpringTests();
Run dart run build_runner build to write test/spring_gen/...test.spring.dart, then dart test.
Each call returns a ResultActions, which is a Future. Always await it: a chain that is not awaited never reports a failed expectation.
Sending requests
| Call | Request |
|---|---|
get(path, headers:, params:) |
GET; params: {'q': 'dune', 'id': [1, 2]} adds query parameters, a list sends the parameter once per element |
post(path, json:, body:, headers:) |
POST; json is encoded with Content-Type: application/json; body (a String or bytes) is sent as it is, with no content type added; json wins when both are given |
put(...), patch(...) |
the same for PUT and PATCH |
delete(path, headers:) |
DELETE |
multipart(path, files:, params:, headers:, method:) |
a multipart/form-data upload of MockMultipartFiles and text fields, a POST unless method says otherwise |
perform(MockRequestBuilder(...)) |
any other request |
webSocket(path, headers:, postProcessors:) |
a WebSocket handshake in memory, with spring_boot_starter_websocket (see WebSocket) |
MockRequestBuilder(method, path, [uriVariables]) describes any request. Each {name} of the path is filled, in order, from uriVariables, URL-encoded.
| Member | Meaning |
|---|---|
headers |
Map<String, String> of headers to send |
params |
Map<String, Object> of query parameters; a List value repeats the parameter |
cookies |
Map<String, String> of cookies |
principal |
the authenticated user (Principal?); null for an anonymous request |
content(body) |
the body, a String (UTF-8) or bytes; no Content-Type is added |
json(value) |
the body as JSON, with Content-Type: application/json unless one is set |
with_(postProcessor) |
a RequestPostProcessor that changes the request just before it is sent |
await app.mockMvc.perform(
MockRequestBuilder(HttpMethod.head, '/api/books/{isbn}', ['978-0'])
..headers['Accept'] = 'application/json'
..cookies['theme'] = 'dark',
).andExpect(status: 200);
Checking responses
andExpect checks only what it is given:
| Argument | Check |
|---|---|
status |
the status code, exactly |
contentType |
a media type compatible with the response's (application/json matches application/json;charset=utf-8) |
headers |
each listed header has exactly this value |
body |
the body as text: equal to a String, or matching a matcher |
json |
the body decoded from JSON: equal to a value, or matching a matcher (hasLength(1), containsPair('title', 'Dune')). A body that is not JSON throws a FormatException. |
A failed check is a TestFailure that names the request and shows the whole response: GET http://localhost/api/books/978-0: expected status 404, got 200, then the status, headers and body.
On a ResultActions |
Does |
|---|---|
andExpect(...) |
checks, and returns the chain |
andDo((result) => ...) |
runs code with the result, such as logging the body while writing a test |
andReturn() |
the MvcResult; the same as awaiting the chain |
An MvcResult has request (the MockServerHttpRequest as sent), response, completion (completes when the application has finished the request) and cancel() (ends a streamed response as if the client went away).
The response is a MockServerHttpResponse:
| Member | Value |
|---|---|
statusCode |
the status |
headers |
the HttpHeaders |
cookies |
the ResponseCookies the application set, in order |
bodyText, bodyBytes |
the body as text (UTF-8) or bytes |
json |
the body decoded from JSON |
events |
the server-sent events written so far |
eventStream |
the server-sent events as they are written |
chunks |
the raw body from now on, as a stream |
Server-sent events
A stream answers before it ends, so andReturn() completes as soon as the headers are out. Read the events as they come, then end the stream from the client's side:
test('streams changes', () async {
final result = await app.mockMvc.get('/api/books/changes').andReturn();
expect(result.response.headers.contentType, startsWith('text/event-stream'));
// Skip the leading ':' comment line: wait for the first real event.
final next = result.response.eventStream.firstWhere((e) => e.data != null);
await app.mockMvc.post('/api/books', json: {'isbn': '5555', 'title': 'Vurt'});
final event = await next;
expect(event.id, '5555');
expect(event.data, contains('Vurt')); // the data as sent: JSON text
await result.cancel(); // the client goes away
});
SseEmitters and application/x-ndjson streams are read the same way (see Server-sent events).
Uploads and downloads
import 'dart:convert';
test('uploads a cover with the book as a JSON part', () async {
await app.mockMvc.multipart('/api/books', files: [
MockMultipartFile('cover', 'dune.png', 'image/png', [1, 2, 3]),
MockMultipartFile(
'book',
null, // no file name: a plain part; application/json fills an object
'application/json',
utf8.encode('{"isbn": "9780441013593", "title": "Dune"}'),
),
], params: {'note': 'first edition'}).andExpect(status: 200);
});
test('downloads part of a cover', () async {
final result = await app.mockMvc
.get('/api/books/9780441013593/cover', headers: {'Range': 'bytes=0-99'})
.andExpect(status: 206, headers: {'Accept-Ranges': 'bytes'})
.andReturn();
expect(result.response.bodyBytes, hasLength(100));
});
MockMultipartFile(name, originalFilename, contentType, bytes) comes with spring_boot_starter_test. The upload goes through the same multipart parsing and limits as on the server; set a limit for a test with properties: {'spring.web.multipart.max-file-size': '64KB'} (see Uploads, Downloads).
Changing every request: RequestPostProcessor
A RequestPostProcessor changes a request just before it is sent. spring_boot_starter_security provides the security ones (a logged-in user, a JWT, a CSRF token). Write your own with FunctionRequestPostProcessor:
// Every request arrives as if through the HTTPS proxy of production.
final viaProxy = FunctionRequestPostProcessor(
(request) => request..headers.set('X-Forwarded-Proto', 'https'),
);
test('one request through the proxy', () async {
await app.mockMvc
.perform(MockRequestBuilder(HttpMethod.get, '/api/books/978-0')..with_(viaProxy))
.andExpect(status: 200);
});
test('every request of a MockMvc through the proxy', () async {
final mvc = MockMvc(
app.getBean<DispatcherHandler>(),
defaultPostProcessors: [viaProxy],
);
await mvc.get('/api/books/978-0').andExpect(status: 200);
});
The defaultPostProcessors run before those of the request itself. MockMvc.of(context) makes a MockMvc for any context that has the web starter; without it, a StateError.
A real server: webEnvironment
import 'dart:io' as io;
void main() {
final app = springBootTest(
springApplication,
webEnvironment: WebEnvironment.randomPort,
);
test('answers over HTTP', () async {
final client = io.HttpClient();
try {
final request = await client.getUrl(
Uri.parse('http://localhost:${app.localServerPort}/api/books/978-0'),
);
final response = await request.close();
expect(response.statusCode, 200);
} finally {
client.close();
}
});
}
webEnvironment |
What starts | Spring |
|---|---|---|
WebEnvironment.mock (default) |
no server; MockMvc works |
MOCK |
WebEnvironment.randomPort |
the server on a free port; the context counts as started once it listens | RANDOM_PORT |
WebEnvironment.definedPort |
the server on server.port; the start fails when the port is taken |
DEFINED_PORT |
WebEnvironment.none |
no server; MockMvc still works |
NONE |
app.localServerPortreads thelocal.server.portproperty. Without a running server it throws aStateError.- In a test class:
@SpringBootTest(webEnvironment: WebEnvironment.randomPort)and a@LocalServerPort() late int port;field. MockMvcworks in every web environment, also next to a real server.- The choice reaches the starter as the property
spring.test.web-environment(mock,random-port,defined-port,none).
Tests of auto-configuration
ApplicationContextRunner starts no server either: it sets spring.test.web-environment=mock. For a real server in a runner, add .withPropertyValues(['spring.test.web-environment=random-port']); await context.getBean<WebServerStartStopLifecycle>().started then gives the WebServer and its port.
Rules
- One context per
springBootTestcall, started in asetUpAllbefore the first test and closed after the last one. Use the handle inside tests orsetUp. properties:override the configuration for these tests:springBootTest(springApplication, properties: {'logging.level.root': 'warn'}).MockMvcskips the socket, so what the server itself answers before the dispatcher (a malformedHost, an encoded/in the path, the 408 of a stalled body) is not seen in memory; test those against a real server.- A stream must be ended with
result.cancel()(or by the application), or the test leaves the request open.
In Spring (Java)
@SpringBootTest
@AutoConfigureMockMvc
class BookControllerTest {
@Autowired MockMvc mvc;
@Test
void findsABook() throws Exception {
mvc.perform(get("/api/books/978-0"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.title").value("Dune"));
}
}
Differences that matter:
andExpecttakes named arguments (status: 200,json: containsPair(...), matchers allowed) instead ofstatus().isOk()andjsonPath(...).- The shortcuts (
mvc.get(...)) send the request;performtakes aMockRequestBuilderfor the rest.withiswith_, sincewithis a Dart keyword. @AutoConfigureMockMvcis optional.- There are no test slices (
@WebMvcTest) yet: the whole application starts. mainstays in the test file:dart testruns it, andrunSpringTests()declares the tests of the classes.