
# テスト

`package:spring_boot_starter_security/testing.dart` は、実際のログインなしで、指定したユーザーとして `MockMvc` のリクエストを行い、求めに応じて CSRF のチェックを通します。セキュリティチェーンはそのまま実行されます。ルール、ヘッダー、CSRF は本番と同じくチェックされます。

## 使う理由

保護されたエンドポイントのテストでは、誰が呼ぶのかを指定しなければなりません。すべてのテストで実際にログインすると遅く、各テストがログインに依存します。リクエストのポストプロセッサーはユーザーを直接リクエストに入れるため、テストは「管理者は管理 API を開ける」を一行で表せます。

## 例

```dart
import 'package:spring_boot_starter_security/testing.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 app = springBootTest(springApplication);

  test('an admin may open the admin API', () async {
    await app.mockMvc
        .perform(MockRequestBuilder(HttpMethod.get, '/api/admin')
          ..with_(user('ada').roles(['ADMIN'])))
        .andExpect(status: 200);
  });

  test('a user may not', () async {
    await app.mockMvc
        .perform(MockRequestBuilder(HttpMethod.get, '/api/admin')..with_(user('bob')))
        .andExpect(status: 403);
  });

  test('a POST needs a CSRF token as well as a user', () async {
    await app.mockMvc
        .perform(MockRequestBuilder(HttpMethod.post, '/api/books')
          ..with_(user('ada'))
          ..with_(csrf()))
        .andExpect(status: 201);
  });

  test('a token with the right scope', () async {
    await app.mockMvc
        .perform(MockRequestBuilder(HttpMethod.get, '/api/orders')
          ..with_(jwt().subject('ada').claim('scope', 'orders.read')))
        .andExpect(status: 200);
  });
}
```

## リクエストのポストプロセッサー

| ポストプロセッサー | リクエストを実行するユーザー |
|---|---|
| `user('ada')` | `ROLE_USER` を持つログイン済みのユーザー `ada`。`.roles(['ADMIN'])` はロールを置き換え (`ROLE_` なし)、`.authorities(['SCOPE_read'])` は権限をそのまま設定し、`.password('x')` はパスワードを設定する。 |
| `userDetails(user)` | プリンシパルとしての独自の `UserDetails`。 |
| `authentication(authentication)` | 独自のトークンなど、任意の `Authentication`。 |
| `anonymous()` | 匿名ユーザー (`anonymousUser`、`ROLE_ANONYMOUS`)。 |
| `jwt()` | デコードされない有効な JWT の Bearer トークン。subject は `user`、スコープは `read` (`SCOPE_read`)、今発行され、5 分で期限切れになる。`.subject(...)`、`.claim(name, value)`、`.authorities([...])` で変更できる。権限はアプリケーションの `jwt.*` プロパティではなく、デフォルトのコンバーターから来る。 |
| `httpBasic('ada', 'secret')` | `Authorization: Basic` ヘッダー。アプリケーションのユーザーに対して実際のログインが行われる。ログイン自体のテストに使う。 |
| `csrf()` | 有効なトークンが送られたかのように CSRF のチェックを通す。`.useInvalidToken()` は `403` で失敗させる。 |

CSRF 保護が有効な間、`GET`、`HEAD`、`TRACE`、`OPTIONS` 以外のリクエストには `csrf()` が必要です。CSRF のポストプロセッサーは、サーバー側にしか存在しないリクエスト属性を設定します。どのクライアントもこれを設定できないため、チェックを回避する手段にはなりません。

## メソッドセキュリティ

このライブラリは `spring_security_core` の `withMockUser`、`withAuthentication`、`withAnonymousUser` を再エクスポートしており、保護されたサービスを直接呼べます ([spring_security_core のテスト](../spring-security-core/testing.md) を参照)。

```dart
test('admins cancel any order', () async {
  final orders = app.getBean<OrderService>();
  await withMockUser(() => orders.cancel(order), roles: ['ADMIN']);
});
```

## Spring (Java) との対応

```java
mockMvc.perform(get("/api/admin").with(user("ada").roles("ADMIN"))).andExpect(status().isOk());
mockMvc.perform(post("/api/books").with(user("ada")).with(csrf())).andExpect(status().isCreated());
```

ポストプロセッサーは `spring-security-test` のものです。`with` は `with_` です (Dart のキーワードのため)。まだないもの: `oauth2Login()` と `oidcLogin()` のポストプロセッサー、`authenticated()` の結果マッチャー。

## 関連項目

- [Web スターターでのテスト](../spring-boot-starter-web/testing.md)
- [CSRF](csrf.md)
- [JWT リソースサーバー](jwt.md)
