テスト
spring_boot_starter_test は Web 層を二つの方法でテストします。MockMvc でメモリー内で、サーバーと同じディスパッチャー、フィルター、バインド、エラー処理を通す方法と、空いているポートでサーバーを起動し、実際のソケットを通す方法です。
使う理由
コントローラーのテストは、クライアントに見えるもの、つまりステータス、ヘッダー、JSON、エラーの ProblemDetail を確認するべきです。コントローラーメソッドを直接呼ぶと、マッピング、バインド、@Valid、フィルター、例外ハンドラーを飛ばしてしまいますが、Web の誤りの多くはそこにあります。MockMvc はリクエストをアプリケーションの dispatcherHandler Bean、つまりサーバーが呼ぶものに、ソケットなしで送ります。ここで通るテストは HTTP 越しでも同じように動き、速く、空いているポートも必要ありません。
テスト対象のクライアントが接続を必要とする場合 (Feign クライアント、dart:io の HttpClient、WebSocket クライアント) は、実際のサーバーを起動します。
セットアップ
# 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
テストは、ジェネレーターが main のために書き出したアプリケーション、つまり生成された main.spring.dart の springApplication を起動します。テスト用の設定は test/resources/ (たとえば application-test.properties) に置きます。テスト中はこれが lib/resources/ より優先されます。
例
関数として:
// 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() {
// アプリケーション全体を一度だけ、サーバーなしで起動する。
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');
});
}
テストクラスとして (ジェネレーターが同じ呼び出しに変換します):
// 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'; // 生成される
@SpringBootTest()
@AutoConfigureMockMvc() // 省略可能: 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();
dart run build_runner build を実行して test/spring_gen/...test.spring.dart を書き出し、それから dart test を実行します。
各呼び出しは ResultActions を返し、これは Future です。必ず await してください。await されないチェーンは、失敗した期待値を報告しません。
リクエストの送信
| 呼び出し | リクエスト |
|---|---|
get(path, headers:, params:) |
GET。params: {'q': 'dune', 'id': [1, 2]} はクエリパラメーターを追加し、リストは要素ごとにパラメーターを一度ずつ送る |
post(path, json:, body:, headers:) |
POST。json は Content-Type: application/json でエンコードされる。body (String またはバイト) はそのまま送られ、コンテンツタイプは追加されない。両方を指定すると json が優先される |
put(...)、patch(...) |
PUT と PATCH について同じ |
delete(path, headers:) |
DELETE |
multipart(path, files:, params:, headers:, method:) |
MockMultipartFile とテキストフィールドの multipart/form-data アップロード。method で指定しない限り POST |
perform(MockRequestBuilder(...)) |
その他のすべてのリクエスト |
webSocket(path, headers:, postProcessors:) |
spring_boot_starter_websocket によるメモリー内の WebSocket ハンドシェイク (WebSocket を参照) |
MockRequestBuilder(method, path, [uriVariables]) は任意のリクエストを表します。パスの各 {name} は、uriVariables から順に URL エンコードされて埋められます。
| メンバー | 意味 |
|---|---|
headers |
送るヘッダーの Map<String, String> |
params |
クエリパラメーターの Map<String, Object>。List の値はパラメーターを繰り返す |
cookies |
Cookie の Map<String, String> |
principal |
認証済みのユーザー (Principal?)。匿名のリクエストでは null |
content(body) |
ボディ。String (UTF-8) またはバイト。Content-Type は追加されない |
json(value) |
JSON としてのボディ。設定されていなければ Content-Type: application/json を付ける |
with_(postProcessor) |
送信の直前にリクエストを変更する RequestPostProcessor |
await app.mockMvc.perform(
MockRequestBuilder(HttpMethod.head, '/api/books/{isbn}', ['978-0'])
..headers['Accept'] = 'application/json'
..cookies['theme'] = 'dark',
).andExpect(status: 200);
レスポンスの確認
andExpect は与えられたものだけを確認します。
| 引数 | 確認内容 |
|---|---|
status |
ステータスコードの完全一致 |
contentType |
レスポンスのものと互換性のあるメディアタイプ (application/json は application/json;charset=utf-8 に一致する) |
headers |
列挙した各ヘッダーがちょうどこの値を持つこと |
body |
テキストとしてのボディ。String と等しいか、マッチャーに一致すること |
json |
JSON からデコードしたボディ。値と等しいか、マッチャーに一致すること (hasLength(1)、containsPair('title', 'Dune'))。JSON でないボディは FormatException を投げる。 |
失敗した確認は TestFailure で、リクエストを示し、レスポンス全体を表示します: GET http://localhost/api/books/978-0: expected status 404, got 200 に続いて、ステータス、ヘッダー、ボディです。
ResultActions に対して |
動作 |
|---|---|
andExpect(...) |
確認し、チェーンを返す |
andDo((result) => ...) |
結果を使ってコードを実行する。テストを書いている間にボディをログに出すなど |
andReturn() |
MvcResult。チェーンを await するのと同じ |
MvcResult には request (送られたとおりの MockServerHttpRequest)、response、completion (アプリケーションがリクエストを終えたときに完了する)、cancel() (クライアントが去ったかのようにストリーミングされたレスポンスを終える) があります。
レスポンスは MockServerHttpResponse です。
| メンバー | 値 |
|---|---|
statusCode |
ステータス |
headers |
HttpHeaders |
cookies |
アプリケーションが設定した ResponseCookie (順番どおり) |
bodyText、bodyBytes |
テキスト (UTF-8) またはバイトとしてのボディ |
json |
JSON からデコードしたボディ |
events |
これまでに書かれたサーバー送信イベント |
eventStream |
書かれるそばからのサーバー送信イベント |
chunks |
今から先の生のボディ (ストリームとして) |
サーバー送信イベント
ストリームは終わる前に応答するので、andReturn() はヘッダーが送られるとすぐに完了します。イベントを届くそばから読み、クライアント側からストリームを終えます。
test('streams changes', () async {
final result = await app.mockMvc.get('/api/books/changes').andReturn();
expect(result.response.headers.contentType, startsWith('text/event-stream'));
// 先頭の ':' コメント行を飛ばし、最初の本当のイベントを待つ。
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')); // 送られたとおりのデータ: JSON テキスト
await result.cancel(); // クライアントが去る
});
SseEmitter と application/x-ndjson のストリームも同じように読みます (サーバー送信イベント を参照)。
アップロードとダウンロード
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, // ファイル名なし: 通常のパート。application/json はオブジェクトを埋める
'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) は spring_boot_starter_test に含まれます。アップロードはサーバー上と同じマルチパートの解析と上限を通ります。テストで上限を設定するには properties: {'spring.web.multipart.max-file-size': '64KB'} を使います (アップロード、ダウンロード を参照)。
すべてのリクエストを変更する: RequestPostProcessor
RequestPostProcessor は送信の直前にリクエストを変更します。spring_boot_starter_security はセキュリティ用のもの (ログイン済みのユーザー、JWT、CSRF トークン) を提供します。独自のものは FunctionRequestPostProcessor で書きます。
// すべてのリクエストが、本番の HTTPS プロキシを通ったかのように届く。
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);
});
defaultPostProcessors は、リクエスト自身のものより先に実行されます。MockMvc.of(context) は、Web スターターを持つ任意のコンテキストに対して MockMvc を作ります。Web スターターがなければ StateError になります。
実際のサーバー: 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 |
起動するもの | Spring |
|---|---|---|
WebEnvironment.mock (デフォルト) |
サーバーなし。MockMvc は動く |
MOCK |
WebEnvironment.randomPort |
空いているポートのサーバー。待ち受けを始めた時点でコンテキストは起動済みとみなされる | RANDOM_PORT |
WebEnvironment.definedPort |
server.port のサーバー。ポートが使用中なら起動は失敗する |
DEFINED_PORT |
WebEnvironment.none |
サーバーなし。MockMvc はそれでも動く |
NONE |
app.localServerPortはlocal.server.portプロパティを読みます。実行中のサーバーがなければStateErrorを投げます。- テストクラスでは:
@SpringBootTest(webEnvironment: WebEnvironment.randomPort)と@LocalServerPort() late int port;フィールドを使います。 MockMvcはどの Web 環境でも動き、実際のサーバーと並べても使えます。- 選択は
spring.test.web-environmentプロパティ (mock、random-port、defined-port、none) としてスターターに届きます。
自動設定のテスト
ApplicationContextRunner もサーバーを起動しません。spring.test.web-environment=mock を設定するためです。ランナーで実際のサーバーを使うには .withPropertyValues(['spring.test.web-environment=random-port']) を追加します。すると await context.getBean<WebServerStartStopLifecycle>().started が WebServer とそのポートを返します。
ルール
springBootTestの呼び出しごとに一つのコンテキスト。最初のテストの前にsetUpAllで起動され、最後のテストの後に閉じられます。ハンドルはテストの中かsetUpで使ってください。properties:はこれらのテストの設定を上書きします:springBootTest(springApplication, properties: {'logging.level.root': 'warn'})。MockMvcはソケットを飛ばします。そのため、ディスパッチャーより前にサーバー自身が応答するもの (不正なHost、パス中のエンコードされた/、停滞したボディの 408) はメモリー内では見えません。それらは実際のサーバーに対してテストしてください。- ストリームは終える必要があります。
result.cancel()で (またはアプリケーションが) 終えないと、テストはリクエストを開いたままにします。
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"));
}
}
重要な違い:
andExpectはstatus().isOk()とjsonPath(...)の代わりに名前付き引数 (status: 200、json: containsPair(...)、マッチャーも使える) を受け取ります。- ショートカット (
mvc.get(...)) はリクエストを送ります。それ以外はperformがMockRequestBuilderを受け取ります。withは Dart のキーワードなのでwith_です。 @AutoConfigureMockMvcは省略可能です。- テストスライス (
@WebMvcTest) はまだありません。アプリケーション全体が起動します。 mainはテストファイルに残ります。dart testがそれを実行し、runSpringTests()がクラスのテストを宣言します。