测试与命令列表

Goat 将最常见的开发操作归类为位于 herd/ 目录中的 .goat 脚本。

你无需手动依次运行 Docker、生成器、迁移、测试或前端工具的各个命令，而是可以将整个过程描述为一个可重复执行的工作流，并通过单个命令启动它。

这些脚本通过 Goat 隔离层执行。因此，项目所需的依赖项和工具可以在容器中运行，无需直接安装到宿主系统上。

这种方式具有以下优点：

  • 统一了在不同操作系统上启动项目的方式，
  • 降低了对开发者计算机本地配置的依赖，
  • 可以控制 Go、Node.js、浏览器及其他工具的版本，
  • 将脚本执行变更的范围限制在项目共享的资源内，
  • 简化了在本地和 CI 中运行相同流程的操作。

日常工作

最常用的命令：

目标命令
启动开发环境bash child/dev.sh
重新生成应用程序goat re
运行数据库迁移goat run:script --path=herd/db/migrate.goat
清理本地数据库goat run:script --path=herd/db/clean.goat
运行完整测试套件goat run:script --path=herd/test.goat
同步翻译goat run:script --path=herd/translate.goat

goat run:script

run:script 命令会运行指定的 .goat 文件：

bash child/dev.sh

脚本文件可以描述由多个步骤组成的完整流程，例如：

  • 启动容器，
  • 准备依赖项，
  • 生成代码，
  • 执行迁移，
  • 运行测试，
  • 构建前端，
  • 启动应用程序。

这样一来，开发环境逻辑将保留在项目中，而不会分散在文档、本地脚本以及各个开发者计算机的配置之间。

goat re

命令：

goat re

会根据当前模型和项目配置重新运行应用程序生成流程。

通常会在以下内容发生变更后使用它：

  • 领域模型，
  • 实体定义，
  • 关系，
  • 生成器配置，
  • 生成代码的模板。

生成器应以可控方式引入变更，以便能够继续手动开发生成的应用程序。

重新生成后，建议在提交前检查 Git 中的差异。

测试

可通过以下命令运行完整测试套件：

goat run:script --path=herd/test.goat

herd/test.goat 定义了应用程序的完整验证流程。

在运行实际测试之前，脚本会重新生成项目中自动生成的部分。这样，测试的代码将对应于当前应用程序模型，而不是生成文件的某个随机本地状态。

随后将运行的内容包括：

  • Go 后端测试，
  • 前端应用程序构建，
  • 前端测试，
  • 使用 Playwright 的端到端测试。

在可能的情况下，独立阶段可以并行执行，从而缩短整个流程的耗时。

可重复的测试环境

测试使用容器来减少开发人员环境与 CI 环境之间的差异。

这尤其适用于以下组件：

  • Go，
  • Node.js，
  • npm，
  • Playwright 使用的浏览器，
  • PostgreSQL，
  • 构建应用程序时所需的其他工具。

因此，测试结果不应取决于开发人员当前在其计算机上安装的 Node.js 或 Go 版本。

这对于 E2E 测试尤为重要，因为它们通常对浏览器版本和系统依赖较为敏感。

测试和构建期间的隔离

在容器中运行工具也具有安全作用。

诸如以下操作：

npm install
npm test
npm run build

无需直接在宿主机上执行。

由依赖项执行的代码会在受控环境中运行，并且只能访问 Goat 和项目配置所提供的资源。

这可以降低与依赖项安装脚本相关的风险，例如 preinstall、install 或 postinstall。

同时，隔离并不能替代依赖项审查。仍然建议：

  • 审查库的更新，
  • 使用 lockfile，
  • 控制依赖项来源，
  • 在提交前检查变更。

生成后检查变更

执行以下操作后：

goat re

或完成完整测试流程后，建议检查变更：

git status
git diff

这样可以准确查看哪些应用程序元素被生成器修改了。

这在修改领域模型时尤其有用。Goat 不会将重新生成视为“覆盖整个应用程序”的操作，而是允许像处理手动引入的变更一样处理生成的变更。

你可以只将确实应包含在当前提交中的文件提交到仓库。

调试脚本

如果某个工作流未能正确完成，首先直接运行与其对应的脚本。

例如，可以通过以下方式重现迁移问题：

goat run:script --path=herd/db/migrate.goat

测试问题则可以通过以下方式重现：

goat run:script --path=herd/test.goat

将流程拆分为较小的 .goat 脚本，有助于确定问题是否涉及：

  • 生成，
  • 数据库，
  • 后端，
  • 前端，
  • E2E 测试，
  • 环境配置。

应用程序命令帮助

生成的应用程序还包含自己的 CLI。

构建完成后，可以使用 --help 标志显示各个命令的文档。

例如：

myapp crud:doc:persist --help
myapp db:migrate --help
myapp serve --help

建议使用 --help，而不是仅依赖文档中的示例，因为它会显示当前所用应用程序版本中可用的参数。

示例：crud:doc:persist

命令：

myapp crud:doc:persist --help

会显示用于创建或更新文档的选项。

可用参数包括：

  • --lang，
  • --slug，
  • --title，
  • --description，
  • --body-markdown，
  • --body-markdown-file。

对于较大的内容，传递文件会更方便：

myapp crud:doc:persist \
  --lang=pl \
  --slug=testowanie \
  --title="Testowanie" \
  --body-markdown-file=./doc/testowanie.md

这样，文档内容可以存储在仓库中，并借助 CLI 与应用程序同步。

发布

新版本的准备流程由以下文件描述：

RELEASING.md

其中包含的流程包括：

  • 选择并设置新版本，
  • 准备所需的密钥，
  • 构建制品，
  • 运行测试，
  • 验证软件包，
  • 发布版本。

在发布前，不要跳过完整的测试集。

在开始发布流程之前，还应检查：

git status

并确保仓库中不包含意外的本地更改。

仅当满足以下条件时，才应准备发布：

  • 生成器能够针对当前模型正常运行，
  • 后端测试通过，
  • 前端能够正确构建，
  • E2E 测试通过，
  • 目标环境配置已完成验证，
  • 所有计划发布的更改均已包含在仓库中。

典型工作流

在日常工作中，通常以下流程已足够：

# 修改应用程序模型
vim herd/_model.goat

# 生成由此产生的更改
goat re

# 检查生成的代码
git diff

# 运行测试
goat run:script --path=herd/test.goat

# 检查最终的更改范围
git status

这种工作方式能够保持清晰的职责划分：

模型描述意图，生成器创建可重复的代码，测试验证结果，而 Git 始终是关于项目中实际发生了哪些更改的最终信息来源。