Lib.rs

准备您的文档后，您可以从测试中运行 DocAssert，如下所示

use doc_assert::DocAssert;

#[cfg(test)]
mod tests {
    #[tokio::test]
    async fn test_docs() {
        let result = DocAssert::new()
            .with_url("https://127.0.0.1:8080")
            .with_doc_path("README.md")
            .assert()
            .await;
        match result {
            Ok(report) => {
                // handle report
            }
            Err(err) => {
                // handle error
            }
        }
    }
}

如果在 Err 的情况下，结果将包含一个错误列表，其中包含关于出错原因的详细信息。

变量

在某些情况下，我们可能需要设置一些将在请求之间共享的值。例如测试认证令牌。

在运行测试之前，我们可以在API中定义变量

use doc_assert::DocAssert;

#[cfg(test)]
mod tests {
    #[tokio::test]
    async fn test_docs() {
        let result = DocAssert::new()
            .with_url("https://127.0.0.1:8080")
            .with_doc_path("README.md")
            .with_variable("auth_token", "some_token")
            .assert()
            .await;
        match result {
            Ok(report) => {
                // handle report
            }
            Err(err) => {
                // handle error
            }
        }
    }
}

变量也可以在文档中动态定义。首先我们有一个请求

```docassertrequest
POST /blog
Content-Type: application/json
{
    "title": "My First Blog",
    "body": "Blog content"
}
```

这将导致一个响应

```docassertresponse
HTTP 201
Content-Type: application/json
{
    "id": "d8f7d454-c436-4e0f-9613-1d69036ad421",
    "title": "My First Blog",
    "body": "Blog content"
}
```

[ignore]: # ($.id)
[ignore]: # ($.date_upd)
[ignore]: # ($.comments)
[let id]: # ($.id)

在上面的例子中，一些字段被忽略，但我们还定义了一个变量 id，它将在下一个请求中使用。注意，变量也可以在忽略的字段上定义。

现在我们可以在下一个请求中使用这个变量

```docassertrequest
GET /blog/`id`
```

这将导致一个响应

```docassertresponse
HTTP 200
Content-Type: application/json
{
    "id": `id`,
    "title": "My First Blog",
    "body": "Blog content"
}
```
[ignore]: # ($.date_upd)
[ignore]: # ($.comments)

注意，id 也被用于响应，并在断言期间进行评估。

使用命令行工具

您可以将DocAssert集成到测试中，也可以将其用作独立的命令行工具

doc-assert --url https://127.0.0.1:8081 --variables '{"auth_token": "some_token"}' README.md

重试策略

在某些情况下，如果请求失败，您可能希望重试请求。您可以在文档中定义重试策略

```docassertrequest
GET /blog/`id`
```

```docassertresponse
HTTP 200
Content-Type: application/json
```
[retry]: # (3,4500)

重试策略中的第一个数字是重试次数，第二个数字是重试之间的延迟（以毫秒为单位）。

安装

要使用DocAssert作为CLI工具，您可以使用cargo进行安装

cargo install doc-assert --features="binary"

为了直接从源代码构建它，请运行

cargo build --features="binary"