本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 適用於 Rust 的 AWS SDK `aws-smithy-mocks`中的 單位測試
<a name="testing-smithy-mocks"></a>

 適用於 Rust 的 AWS SDK 提供多種方法來測試與 互動的程式碼 AWS 服務。本主題說明如何使用 [https://docs.rs/aws-smithy-mocks/latest/aws_smithy_mocks/](https://docs.rs/aws-smithy-mocks/latest/aws_smithy_mocks/) 木箱，它提供簡單但強大的方法來模擬 AWS SDK 用戶端回應以進行測試。

## 概觀
<a name="overview-smithy-mock"></a>

為 使用的程式碼撰寫測試時 AWS 服務，您通常想要避免進行實際的網路呼叫。`aws-smithy-mocks` 木箱可讓您：
+ 建立模擬規則，定義 SDK 應如何回應特定請求。
+ 傳回不同類型的回應 （成功、錯誤、HTTP 回應）。
+ 根據請求的屬性進行比對。
+ 定義用於測試重試行為的回應序列。
+ 確認您的規則已如預期般使用。

## 新增相依性
<a name="dependency-smithy-mock"></a>

在專案目錄的命令提示中，新增[https://crates.io/crates/aws-smithy-mocks](https://crates.io/crates/aws-smithy-mocks)木箱做為相依性：

```
$ cargo add --dev aws-smithy-mocks
```

使用 `--dev`[選項](https://doc.rust-lang.org/cargo/commands/cargo-add.html)會將 木箱新增至 `Cargo.toml` 檔案的 `[dev-dependencies]`區段。作為[開發相依性](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#development-dependencies)，它不會編譯並包含在用於生產程式碼的最終二進位檔中。

此範例程式碼也使用 Amazon Simple Storage Service 做為範例 AWS 服務，且需要功能 `test-util`。

```
$ cargo add aws-sdk-s3 --features test-util
```

這會將 木箱新增至 `Cargo.toml` 檔案的 `[dependencies]`區段。

## 基本使用
<a name="basic-smithy-mocks"></a>

 以下是如何使用 `aws-smithy-mocks`測試與 Amazon Simple Storage Service (Amazon S3) 互動之程式碼的簡單範例：

```
use aws_sdk_s3::operation::get_object::GetObjectOutput;
use aws_sdk_s3::primitives::ByteStream;
use aws_smithy_mocks::{mock, mock_client};

#[tokio::test]
async fn test_s3_get_object() {
    // Create a rule that returns a successful response
    let get_object_rule = mock!(aws_sdk_s3::Client::get_object)
        .then_output(|| {
            GetObjectOutput::builder()
                .body(ByteStream::from_static(b"test-content"))
                .build()
        });

    // Create a mocked client with the rule
    let s3 = mock_client!(aws_sdk_s3, [&get_object_rule]);

    // Use the client as you would normally
    let result = s3
        .get_object()
        .bucket("test-bucket")
        .key("test-key")
        .send()
        .await
        .expect("success response");

    // Verify the response
    let data = result.body.collect().await.expect("successful read").to_vec();
    assert_eq!(data, b"test-content");

    // Verify the rule was used
    assert_eq!(get_object_rule.num_calls(), 1);
}
```

## 建立模擬規則
<a name="creating-rules-smithy-mocks"></a>

規則是使用 `mock!`巨集建立，這會採用用戶端操作做為 引數。然後，您可以設定規則的行為方式。

### 比對請求
<a name="matching-requests-smithy-mocks"></a>

 您可以比對請求屬性，讓規則更具體：

```
let rule = mock!(Client::get_object)
    .match_requests(|req| req.bucket() == Some("test-bucket") && req.key() == Some("test-key"))
    .then_output(|| {
        GetObjectOutput::builder()
            .body(ByteStream::from_static(b"test-content"))
            .build()
    });
```

### 不同的回應類型
<a name="diff-response-smithy-mocks"></a>

您可以傳回不同類型的回應：

```
// Return a successful response
let success_rule = mock!(Client::get_object)
    .then_output(|| GetObjectOutput::builder().build());

// Return an error
let error_rule = mock!(Client::get_object)
    .then_error(|| GetObjectError::NoSuchKey(NoSuchKey::builder().build()));

// Return a specific HTTP response
let http_rule = mock!(Client::get_object)
    .then_http_response(|| {
        HttpResponse::new(
            StatusCode::try_from(503).unwrap(),
            SdkBody::from("service unavailable")
        )
    });
```

## 測試重試行為
<a name="testing-retry-behavior-smithy-mocks"></a>

最強大的功能之一`aws-smithy-mocks`是能夠透過定義回應序列來測試重試行為：

```
// Create a rule that returns 503 twice, then succeeds
let retry_rule = mock!(aws_sdk_s3::Client::get_object)
    .sequence()
    .http_status(503, None)                          // First call returns 503
    .http_status(503, None)                          // Second call returns 503
    .output(|| GetObjectOutput::builder().build())   // Third call succeeds
    .build();

// With repetition using times()
let retry_rule = mock!(Client::get_object)
    .sequence()
    .http_status(503, None)
    .times(2)                                        // First two calls return 503
    .output(|| GetObjectOutput::builder().build())   // Third call succeeds
    .build();
```

## 規則模式
<a name="rule-modes-smithy-mocks"></a>

您可以使用規則模式來控制規則的比對和套用方式：

```
// Sequential mode: Rules are tried in order, and when a rule is exhausted, the next rule is used
let client = mock_client!(aws_sdk_s3, RuleMode::Sequential, [&rule1, &rule2]);

// MatchAny mode: The first matching rule is used, regardless of order
let client = mock_client!(aws_sdk_s3, RuleMode::MatchAny, [&rule1, &rule2]);
```

## 範例：測試重試行為
<a name="example-retry-smithy-mocks"></a>

以下是示範如何測試重試行為的更完整範例：

```
use aws_sdk_s3::operation::get_object::GetObjectOutput;
use aws_sdk_s3::config::RetryConfig;
use aws_sdk_s3::primitives::ByteStream;
use aws_smithy_mocks::{mock, mock_client, RuleMode};

#[tokio::test]
async fn test_retry_behavior() {
    // Create a rule that returns 503 twice, then succeeds
    let retry_rule = mock!(aws_sdk_s3::Client::get_object)
        .sequence()
        .http_status(503, None)
        .times(2)
        .output(|| GetObjectOutput::builder()
            .body(ByteStream::from_static(b"success"))
            .build())
        .build();

    // Create a mocked client with the rule and custom retry configuration
    let s3 = mock_client!(
        aws_sdk_s3,
        RuleMode::Sequential,
        [&retry_rule],
        |client_builder| {
            client_builder.retry_config(RetryConfig::standard().with_max_attempts(3))
        }
    );

    // This should succeed after two retries
    let result = s3
        .get_object()
        .bucket("test-bucket")
        .key("test-key")
        .send()
        .await
        .expect("success after retries");

    // Verify the response
    let data = result.body.collect().await.expect("successful read").to_vec();
    assert_eq!(data, b"success");

    // Verify all responses were used
    assert_eq!(retry_rule.num_calls(), 3);
}
```

## 範例：根據請求參數的不同回應
<a name="example-request-param-smithy-mocks"></a>

您也可以建立規則，根據請求參數傳回不同的回應：

```
use aws_sdk_s3::operation::get_object::{GetObjectOutput, GetObjectError};
use aws_sdk_s3::types::error::NoSuchKey;
use aws_sdk_s3::Client;
use aws_sdk_s3::primitives::ByteStream;
use aws_smithy_mocks::{mock, mock_client, RuleMode};

#[tokio::test]
async fn test_different_responses() {
    // Create rules for different request parameters
    let exists_rule = mock!(Client::get_object)
        .match_requests(|req| req.bucket() == Some("test-bucket") && req.key() == Some("exists"))
        .sequence()
        .output(|| GetObjectOutput::builder()
            .body(ByteStream::from_static(b"found"))
            .build())
        .build();

    let not_exists_rule = mock!(Client::get_object)
        .match_requests(|req| req.bucket() == Some("test-bucket") && req.key() == Some("not-exists"))
        .sequence()
        .error(|| GetObjectError::NoSuchKey(NoSuchKey::builder().build()))
        .build();

    // Create a mocked client with the rules in MatchAny mode
    let s3 = mock_client!(aws_sdk_s3, RuleMode::MatchAny, [&exists_rule, &not_exists_rule]);

    // Test the "exists" case
    let result1 = s3
        .get_object()
        .bucket("test-bucket")
        .key("exists")
        .send()
        .await
        .expect("object exists");

    let data = result1.body.collect().await.expect("successful read").to_vec();
    assert_eq!(data, b"found");

    // Test the "not-exists" case
    let result2 = s3
        .get_object()
        .bucket("test-bucket")
        .key("not-exists")
        .send()
        .await;

    assert!(result2.is_err());
    assert!(matches!(result2.unwrap_err().into_service_error(),
                    GetObjectError::NoSuchKey(_)));
}
```

## 最佳實務
<a name="best-practices-smithy-mocks"></a>

使用 `aws-smithy-mocks` 進行測試時：

1.  符合特定請求：使用 `match_requests()` 來確保您的規則僅適用於預期的請求，特別是使用 `RuleMode:::MatchAny`。

1.  驗證規則使用情況：檢查 `rule.num_calls()`以確保您的規則已實際使用。

1.  測試錯誤處理：建立傳回錯誤的規則，以測試程式碼處理失敗的方式。

1.  測試重試邏輯：使用回應序列來驗證程式碼是否正確處理任何自訂重試分類器或其他重試行為。

1. 專注於測試：為不同的案例建立單獨的測試，而不是嘗試在一個測試中涵蓋所有內容。