规范文档测试三合一

三合一是 hitchstory 支持的开发和自动化过程，其中单一事实来源用于维护规范、测试和文档。规范通过故事引擎执行，文档（例如 markdown、HTML 等）通过模板自动生成。

这种自动化形式有助于解决三个常见问题

• 防止文档或规范过时。如果行为发生变化但规范没有更新，则测试将失败。

• 文档没有被编写。如果你有规范，你就有文档。

• 减少无聊。借助三合一，文档和测试中最乏味的部分是自动化的。## 简单现实生活示例

我创建了这个简单的命令行应用程序来解决一个问题 - 我想从我喜欢的移动笔记应用程序org 模式输出生成一个漂亮的 LaTeX 字母，而不用使用 Emacs。

我向这个应用程序添加的一项功能是将 org 模式标记 - 链接、粗体、斜体等 - 转换为 markdown。

此功能在一个简单的操作方法页面中进行了记录。该网页是静态 HTML，使用出色的 mkdocs 从一个 markdown 文档生成，使用 mkdos 风格的 markdown。

到目前为止，一切都很正常 - 许多项目都有这样的操作方法文档。

但是，这个 markdown 文档是使用自定义 jinja2 模板和此功能的可执行规范的组合生成的，两者都使用声明式、类型安全的 YAML 定义。

这不是 Cucumber 试图做的事情吗？

不。

首先，Cucumber 不会用于生成任何类型的文档。它应该是文档本身。

由于 Gherkin 语法的设计和围绕该工具的文化，很难创建具有复杂前提条件和步骤的规范。Gherkin 故事通常最终会像这样

  Scenario: Org file that will produce markdown
    Given I have an org file and appropriate template
    When I run the orji command
    Then an output with markdown will appear

规范的许多相关细节将被埋藏在执行的步骤代码中。

这些“规范”表面上是为了促进交流，但实际上，除了编写 Cucumber 脚本的测试人员之外，所有人都忽略了它们。

这个工具可以自动生成所有文档吗？

不。

根据Diátaxis 模型，软件项目需要 4 种主要的文档类型

• 操作方法
• 参考
• 教程
• 说明

操作方法文档将包含大量与规范重叠的内容，教程也是如此。

但是，说明性文档将包含更少的重叠内容。

参考材料可能不会由 hitchstory 生成，但可能会从代码中的其他来源生成。一个很好的例子是从模式生成的 REST API 参考信息。

截图怎么办？

如果可执行规范是通过类似 Appium 或 Playwright 的工具执行的，则运行测试套件时可以生成屏幕截图工件。

生成的 Markdown/HTML/任何文档可以直接将这些文件引用为图像。

我能用它做什么？

规范到文档的自动生成有很多用途，包括：

• 为您的 REST API 生成操作指南，供移动应用开发者使用。
• 为 Python 库生成操作指南（本网站上的所有项目都是以这种方式生成的）。
• 生成详细报告，向高层管理人员展示您的应用程序的功能，而无需开会。
• 生成文档，展示多语言网站上的所有用户流程，以便翻译人员进行质量控制。
• 为监管机构生成报告，证明应用程序已通过严格的测试。
• …等等。