
# 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

```yaml
# 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:

```dart
// 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:

```dart
// 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 `MockMultipartFile`s 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](server/websocket.md)) |

`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 |

```dart
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 `ResponseCookie`s 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:

```dart
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
});
```

`SseEmitter`s and `application/x-ndjson` streams are read the same way (see [Server-sent events](streaming/sse.md)).

## Uploads and downloads

```dart
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](streaming/uploads.md), [Downloads](streaming/downloads.md)).

## 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`:

```dart
// 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

```dart
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.localServerPort` reads the `local.server.port` property. Without a running server it throws a `StateError`.
- In a test class: `@SpringBootTest(webEnvironment: WebEnvironment.randomPort)` and a `@LocalServerPort() late int port;` field.
- `MockMvc` works 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 `springBootTest` call**, started in a `setUpAll` before the first test and closed after the last one. Use the handle inside tests or `setUp`.
- **`properties:`** override the configuration for these tests: `springBootTest(springApplication, properties: {'logging.level.root': 'warn'})`.
- **`MockMvc` skips the socket**, so what the server itself answers before the dispatcher (a malformed `Host`, 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)

```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:

- `andExpect` takes named arguments (`status: 200`, `json: containsPair(...)`, matchers allowed) instead of `status().isOk()` and `jsonPath(...)`.
- The shortcuts (`mvc.get(...)`) send the request; `perform` takes a `MockRequestBuilder` for the rest. `with` is `with_`, since `with` is a Dart keyword.
- `@AutoConfigureMockMvc` is optional.
- There are no test slices (`@WebMvcTest`) yet: the whole application starts.
- `main` stays in the test file: `dart test` runs it, and `runSpringTests()` declares the tests of the classes.

## See also

- [Controllers](controllers/index.md)
- [Errors](errors/index.md)
- [Server-sent events](streaming/sse.md)
- [The server](server/index.md)
