
# Testing

`MockWebSocketTransport` plays the server for clients: the test reads what the client sent, pushes messages and drops the connection to check reconnection. `MockMvc.webSocket(path)` opens a connection to a server endpoint in memory, through the same filters and handshake. Both come with `spring_boot_starter_test`.

## Why

A test that needs a real WebSocket server is slow and hard to drive: you cannot easily make it drop a connection at the right moment. The mocks keep the client's and the endpoint's code as in production, and put the test in control of the other side.

## Clients

```dart
import 'package:spring_boot_starter_test/spring_boot_starter_test.dart';
import 'package:test/test.dart';

import 'spring_gen/main.test.spring.dart';

void main() {
  final sockets = MockWebSocketTransport();
  final app = springBootTest(
    springApplication,
    overrides: [BeanOverride<WebSocketTransport>(sockets)],
    properties: {'chat.url': 'ws://chat.test/ws'},
  );

  test('chats', () async {
    final chat = app.getBean<ChatSocket>();
    final messages = <ChatMessage>[];
    chat.messages().listen(messages.add);              // opens the connection

    final server = await sockets.nextConnection;
    server.pushJson({'from': 'ann', 'text': 'hi'});    // server → client
    await chat.send(const ChatMessage(from: 'me', text: 'hello'));
    expect(server.sentJson, [{'from': 'me', 'text': 'hello'}]);

    await server.drop();                               // the connection is lost...
    await sockets.nextConnection;                      // ...and the client reconnects
  });
}
```

With an `ApplicationContextRunner`, register the mock with `.withBean<WebSocketTransport>(() => sockets)`.

## Server endpoints

```dart
final app = springBootTest(springApplication);

test('acknowledges a message', () async {
  final session = await app.mockMvc.webSocket(
    '/ws/rooms/neon',
    headers: {'Origin': 'https://chat.example'},
  );
  final replies = StreamIterator(session.messages);
  session.sendMessage('{"from": "ann", "text": "hi"}');
  // First the broadcast to the room, which includes this session...
  expect(await replies.moveNext(), isTrue);
  expect(jsonDecode(replies.current as String), {'from': 'ann', 'text': 'hi'});
  // ...then the reply of @OnMessage.
  expect(await replies.moveNext(), isTrue);
  expect(jsonDecode(replies.current as String), {'room': 'neon', 'received': 'hi'});
  await session.close();
});
```

A refused handshake (by the origin check or an interceptor) throws a `WebSocketException` with the status.

A test that builds its context by hand, without the generated application, names both modules of the starter when it has server endpoints: `springBootStarterWebsocketAutoConfiguration` (the clients) and `springBootStarterWebsocketServerAutoConfiguration` (the session registry and the handshake mapping). With the first alone no endpoint is mapped.

## Over a real socket

Start the server on a free port and connect with the client transport:

```dart
final app = springBootTest(springApplication, webEnvironment: WebEnvironment.randomPort);

test('over a socket', () async {
  final session = await platformWebSocketTransport()
      .connect(Uri.parse('ws://127.0.0.1:${app.localServerPort}/ws/rooms/neon'));
  session.sendMessage('{"from": "ann", "text": "hi"}');
  await session.close();
});
```

## In Spring (Java)

Spring tests WebSocket endpoints with a real server (`@SpringBootTest(webEnvironment = RANDOM_PORT)`) and a `StandardWebSocketClient`. `MockMvc.webSocket` and `MockWebSocketTransport` are this project's own.

## See also

- [Clients](clients.md)
- [Server endpoints](server-endpoints.md)
- [Testing in the web starter](../spring-boot-starter-web/testing.md)
