orlangure/gnomock-cleaner

Gnomock – 无需模拟的测试工具

无需模拟的测试

🏗️ 快速搭建完整依赖栈
🎁 轻松设置依赖初始状态
🏭 基于接近生产环境的真实软件进行测试
⏳ 无需花费时间编写模拟代码
🕹️ 测试实际程序行为和副作用

![PkgGoDev]([] !https://github.com/orlangure/gnomock/workflows/Test/badge.svg ![Go Report Card]([] ![codecov]([***]

Gnomock 是一个集成和端到端测试工具包。它使用 Docker 创建临时容器来运行应用依赖，设置其初始状态，并在测试结束后自动清理。Gnomock 允许在可能的情况下使用无模拟方式测试代码。

Gnomock 的强大之处在于其丰富的预设，每个预设针对特定数据库、服务或工具实现集成。每个预设都提供了简便的初始状态设置方式：创建 SQL schema、向 S3 上传测试数据、向 Splunk 发送测试事件等。

"Gnomock" 名称代表 "no mock"（无模拟），前缀 "G" 代表 "Go" 😼。同时它发音类似 "gnome"（地精），因此采用了友好的花园地精形象（由 Michael Zolotov 设计）。

演示

亲自体验使用临时 Docker 容器中的真实服务编写测试是多么简单快捷：

![asciicast]([***]

目录

• 快速开始
  • 在 Go 应用中使用 Gnomock
  • 在其他语言中使用 Gnomock
• 官方预设
• 类似项目
• 故障排除

快速开始

Gnomock 有两种使用方式：

• 作为包直接导入Go项目
• 作为 HTTP 守护进程运行，供其他语言通过 HTTP 访问

两种方式都需要本地环境运行活跃的 Docker 守护进程。

外部 DOCKER_HOST 支持为实验性特性。目前无法可靠测试，但可能可以工作。

在 Go 应用中使用 Gnomock

以下是入门示例：

bash
go get github.com/orlangure/gnomock

设置带有 schema 的 Postgres 容器示例：

go
import (
	"database/sql"
	"fmt"

	_ "github.com/lib/pq" // postgres driver
	"github.com/orlangure/gnomock"
	"github.com/orlangure/gnomock/preset/postgres"
)

p := postgres.Preset(
    postgres.WithUser("gnomock", "gnomick"),
    postgres.WithDatabase("mydb"),
    postgres.WithQueriesFile("/var/project/db/schema.sql"),
)
container, _ := gnomock.Start(p)
defer func() { _ = gnomock.Stop(container) }()

connStr := fmt.Sprintf(
    "host=%s port=%d user=%s password=%s dbname=%s sslmode=disable",
    container.Host, container.DefaultPort(),
    "gnomock", "gnomick", "mydb",
)
db, _ := sql.Open("postgres", connStr)
// db 已包含所需的 schema 和数据，可直接使用

查看包参考文档。有关预设文档，请参阅预设部分。

在其他语言中使用 Gnomock

如果使用 Go，请参考在 Go 应用中使用 Gnomock部分。其他语言请参考文档。

官方预设

Gnomock 的强大之处在于预设。以下是现有预设及其支持^*版本列表。

* 支持的版本会作为 CI 流水线的一部分进行测试。其他版本可能也能工作。

可以直接从 Go 代码使用 Gnomock 而无需任何预设。HTTP API 仅允许使用本仓库中存在的预设来设置容器。

类似项目

Gnomock 并非唯一旨在通过临时 Docker 容器简化集成和端到端测试的项目：

• testcontainers/testcontainers-go
• ory/dockertest

这些项目非常出色，为用户提供了极大的灵活性和功能。它们能实现许多 Gnomock 无法实现的功能。但以下是 Gnomock 有时具有优势的地方：

• Gnomock 提供一站式解决方案。Gnomock 拥有不断增长的预设库，每个预设都实现了与流行外部服务的集成。每个预设都包含许多"隐形"工具，无需您自己实现：
  • 内置健康检查函数，您甚至不需要知道它的存在。确保您只有在容器准备好使用时才获得控制权。
  • 部分配置的包装器，如默认用户名/密码。您可以轻松提供自己的凭据连接容器。
  • 种子数据注入功能。有时您只需要确保查询在特定数据下工作，Gnomock 一行代码即可注入数据。有时您只需测试从 Kafka 消费消息的程序，Gnomock 另一行代码即可为您生成消息。
• 简洁 API，大多数时候不会暴露"底层"实现。但必要时，Gnomock 允许额外配置和自定义预设实现。
• Gnomock 的愿景包括不仅在 Go 项目中有用，还能通过 HTTP 供任何项目使用。它已通过 HTTP 层支持几乎所有功能，具有清晰的 OpenAPI 规范，甚至有 Python 包装器的概念验证。
• Gnomock 有友好的花园地精吉祥物😻

故障排除

Gnomock 测试耗时过长并最终超时

如果您的网络不够快，无法拉取测试中使用的 Docker 镜像，本地运行时经常会发生这种情况。在 CI（如 Github Actions）中，镜像下载速度非常快。要解决本地此问题，请在运行测试前手动拉取镜像。只需执行一次，镜像会保留在本地缓存中直到删除。例如，要拉取 Postgres 11 镜像：

bash
docker pull postgres:11

镜像已本地存在但测试仍超时

这可能是因为容器在超时前无法准备就绪。默认情况下，Gnomock 对新容器使用相当高的超时（启动和设置）。如果您使用 WithTimeout（HTTP 中的 timeout）更改默认超时，可能设置的值过短。

单独运行测试通过，并行运行失败

当同时启动大量容器时会发生这种情况。系统（尤其是 Github Actions 等 CI 环境）无法处理负载，容器在超时前无法变为健康状态。因此 Gnomock 有多个独立构建任务，每个任务只运行一小部分测试，一次一个包。

容器设置失败并显示"文件未找到"错误

如果以服务器模式运行 gnomock，需要确保设置中使用的文件在 gnomock 容器内可用。使用 docker run 的 -v $(pwd):$(pwd) 参数将当前工作目录挂载到 gnomock 容器内的相同路径。如果希望永久运行 gnomock 容器，可以挂载整个 $HOME 目录（或存放代码的任何其他目录）。