Katalon + Jira 集成：端到端质量追踪完全指南

如果某个团队既使用 Katalon Studio 执行自动化测试，又依赖 Jira 进行缺陷管理，那么下面的场景一定不会陌生：一个测试用例失败后，测试人员需要截图、打开 Jira、手动创建工单、粘贴日志、上传附件。一个迭代中如果有几十个失败用例，这样的重复操作会消耗大量时间，还容易引入人为失误。

Katalon 与 Jira 的集成可以彻底消除这种瓶颈。借助官方的 Jira Integration 插件，每一个失败的测试步骤旁都会出现一个一键提交缺陷的图标。只需在 Katalon 的结果面板上轻轻一点，一个预先填充好测试用例名称、截图和日志的 Jira 问题单就会自动打开。

这带来的直接效果是：更快地实现自动化测试缺陷跟踪，完全避免手动转录错误，并且每个 Jira 工单都可以追溯到发现它的具体测试，形成唯一的事实来源。对于任何认真对待 Katalon Studio 缺陷报告的团队来说，这种集成几乎是必选项。关于最新的界面参考和版本说明，可以查阅 Katalon 官方文档。

开始前的准备工作

在动手将 Katalon Studio 与 Jira Cloud 集成之前，请确保以下条件已经满足：

拥有有效许可证的 Katalon Studio
从 Katalon Store 获取的 Jira Integration 插件
从 Atlassian Marketplace 安装的 Katalon Test Automation for Jira 插件
一个 Jira Cloud 或 Jira Data Center 实例，并且具备管理员或项目管理员权限
Jira 账户的登录邮箱，以及专门为 Katalon 生成的 Jira API 令牌（Jira Cloud 已经不再接受密码进行 API 调用）

Katalon Jira 集成分步指南

第 1 步：安装 Jira Integration 插件

首先需要从 Katalon Store 获取 Jira Integration 插件。该插件并非 IDE 内置，因此安装是一个独立的步骤。

打开浏览器，访问 store.katalon.com。
使用 Katalon 账户登录。
在搜索栏输入 "jira" 并回车。
在搜索结果中，点击 Jira Integration 对应的卡片------这个插件的下载量约 12.9K，评分四星。注意不要和 "AIO Tests for Jira Integration" 插件搞混。

进入产品页面后，点击蓝色的 Install 按钮。

版本兼容性说明：

Katalon Studio 8.x 版本请使用 Jira Plugin 1.0.23 或更早版本
Katalon Studio 9.x 版本请使用 Jira Plugin 1.0.25 或更高版本
安装前，务必在插件的 Requirements 标签页上核对版本信息。版本不匹配是 Studio 升级后集成失效的首要原因。

此外，还需要从 Atlassian Marketplace 直接安装 Katalon Test Automation for Jira 插件。该插件在平台层面实现 Katalon 与 Jira 的双向同步，是完整集成所必需的。

第 2 步：在 Katalon Studio 中重载插件

从商店安装插件后，并不会自动在 IDE 中激活。很多指南忽略了这一步，导致部分用户始终看不到 Jira 图标。

切换回 Katalon Studio。
点击工具栏右上角的用户/头像图标。
从下拉菜单中选择 Reload Plugins。

Katalon 会拉取与账户关联的所有插件。此时会弹出一个 Plugins 对话框，列出每个已安装插件的版本和状态。确认 Jira Integration 的状态显示为 Status: Success 后再继续下一步。

第 3 步：在项目设置中打开 Jira 配置

插件成功加载后，就可以从菜单直接进入项目的 Jira 设置。

在 Katalon Studio 中，依次点击 Projects > Settings > Plugins > JIRA。

这会打开当前项目设置中的 JIRA 配置面板。需要注意，Jira 集成是以单个项目为范围的------如果要在另一个 Katalon 项目中集成 Jira，必须为那个项目重复这些步骤。

第 4 步：启用集成并配置认证信息

在 JIRA 设置面板中：

勾选顶部的 Enable integration 复选框。

在 Authentication 区域填写以下内容：

Server URL ：格式取决于 Jira 的类型

* Jira Cloud：https://<站点名称>.atlassian.net

* Jira Data Center：https://域名（不要添加诸如 /secure 的后缀；服务器 URL 必须使用有效的 SSL 证书）

Username ：关联 Jira 账户的电子邮箱地址
Password / API Token ：不要在此处填写 Jira 密码 （Jira Cloud 要求使用令牌，详见第 5 步）

勾选 Encrypt authentication data（推荐），尤其是当项目文件保存在版本控制系统时，这项设置非常重要。

第 5 步：为 Katalon 生成 Jira API 令牌

这是多数教程一笔带过的环节，也是设置中最容易出问题的地方。理解 Katalon 对 Jira API 令牌的要求非常关键：Jira Cloud 已经停止支持基于密码的 API 认证，必须生成一个令牌。

具体操作如下：

登录 Atlassian 账户后，访问：https://id.atlassian.com/manage/api-tokens
点击 Create API Token。

在弹出的对话框中：

Name ：填写一个容易记住的名字，比如 "Jira Katalon Token"，这样将来查看令牌时能立刻明白用途。
Expires on ：设置一个一年以内的过期日（Atlassian 规定最长有效期一年）。

点击 Create 。
在关闭对话框之前，一定要把令牌复制下来。Atlassian 只会显示这一次。最好立刻将令牌保存在密码管理器或安全笔记中。如果弄丢了，就只能重新生成，并更新 Katalon 中的设置。

第 6 步：将 Katalon 连接到 Jira

回到 Katalon Studio 的 JIRA Project Settings：

将生成的 API 令牌粘贴到 Password / API Token 字段。
点击 Connect。

连接成功后，下方的 Submit Options 下拉菜单会自动填充 Jira 的项目和问题类型。如果下拉菜单仍是空的，说明认证信息未通过------请重新检查令牌和 Server URL。

第 7 步：配置提交选项并保存

建立连接后，就可以配置默认的提交行为：

设置项	推荐值
Default JIRA Project	团队的质量保证或迭代项目（例如 Locator Phase2）
Default JIRA Issue Type	Bug
Use Test Case name as Summary	✓ 勾选
Attach Screenshot to JIRA ticket	✓ 勾选
Attach Log to JIRA ticket	✓ 勾选
Automatically submit test result	✓ 勾选（可实现无人工干预的缺陷跟踪）

点击 Apply and Close。至此，Katalon 与 Jira 的集成已完全可用。

如何自动将 Bug 从 Katalon 提交到 Jira

接下来的内容是整个集成中最有价值的部分，即测试运行结束后，如何在 Katalon Studio 中提交缺陷的完整流程。

照常运行测试套件
在 Katalon Studio 中执行任意测试套件或测试用例。运行完成后，打开 Results 面板。
定位失败用例，点击缺陷图标
每个失败的测试用例右侧，都会出现一个小的 Jira 缺陷图标。这就是从 Katalon 自动向 Jira 提交 Bug 的一键入口。

_点击该图标，会弹出 Linked JIRA Issues 对话框。

选择记录缺陷的方式

对话框中提供了三种选项：

Create as New ：创建一个全新的 Jira 问题，并自动填入测试名称、日志和截图。适用于新发现的缺陷。
Create as Sub Issue ：将失败记录为现有父工单下的子任务。适合与已知功能工单关联的回归失败。
Link to Existing Issue ：将测试结果链接到已在待办列表中的 Jira 工单。当缺陷已经通过其他渠道报告时，这种选择最为合适。

在 Jira 界面中复核并提交

Katalon 会打开 Jira 的创建问题表单，并且已经预填好以下内容：

测试人员可以补充复现步骤、测试环境、严重程度等额外信息，然后点击 Create。工单会即刻在 Jira 中建立，同时 Katalon 的结果面板中会出现指向该工单的链接，从而完整闭环自动化测试缺陷跟踪和 Jira 测试管理工作流。

复制代码

- Project：默认的项目
- Issue Type：Bug
- Summary：测试用例名称（例如 CURAHealthLogin）
- Attachments：截图和日志文件已排队等待上传

从测试用例链接和管理 Jira 问题

除了从测试结果提交缺陷，集成还支持在 Katalon Studio 的 Test Explorer 中直接将 Jira 问题链接到单个测试用例。当需要将特定测试用例与某个已有的 Jira 工单关联时（无论是为了可追溯性、BDD 需求关联还是审计目的），这个功能非常实用。

编辑并链接已有的 Jira 测试用例：

在 Katalon Studio 中，进入 Test Explorer，找到并打开需要操作的测试用例。
点击测试用例中的 JIRA integration 标签页。
要添加并链接一个 Jira 问题，点击 Edit JIRA issue。
弹出的 Link to JIRA Issue 对话框中，输入目标 Jira 问题的键值。
（可选）勾选 Override test case description，以使用 Jira 问题中的描述替换现有测试用例描述。
在 Property 标签页中，新的描述会替换原有描述。
点击 OK 应用更改。

故障排查：

如果出现 "Jira issue cannot be found" 提示

可能的原因及解决方法：输入了错误的 issue key，或者该 Jira 问题在当前获取的账户中已不存在。请确保 issue key 正确无误。

移除已链接的 Jira 问题：

在 Katalon Studio 中，通过 Test Explorer 找到需要更新的测试用例。
点击 Integration 标签页。
选择 Remove Linked Issue。
在弹出的确认对话框中，点击 Remove 确认。

从 Jira 通过 JQL 导入测试用例（BDD 云端集成）

如果团队在 Jira 中编写 BDD 场景，那么可以使用 Jira Query Language（JQL）将测试用例直接拉取到 Katalon Studio。这是整个集成中功能强大却又经常被低估的一部分。

在 Katalon 工具栏中，选择 Jira > Import Test Case from JIRA JQL 。会打开 Import Test Case from JIRA JQL 对话框。
在 Jira JQL 框中填写 JQL 查询语句。例如，要导入 TDAP 项目中状态为 Completed 的 Bug 类型测试用例，可以写：
project = TDAP AND issuetype = Bug AND status = Completed ORDER BY created DESC
有关 JQL 语法，请参考 Atlassian JQL 文档。
默认情况下，Import BDD feature files 复选框处于选中状态------这允许导入 BDD 特征文件以执行 BDD 测试。如果不需要 BDD 测试执行，可取消勾选。
点击 OK。
在 Test Case Folder Selection 对话框中选择存放导入问题的目标文件夹，然后点击 OK。
随后会弹出 Jira Issues 对话框，点击 OK 即可从 Jira 导入测试用例。

导入后，测试用例的名称会反映 Jira 工单的 Summary，描述内容则为 Jira 工单的内容。如果导入了 BDD 特征文件，Katalon Studio 会在 Include/Feature 文件夹中创建相应的特征文件。需留意，一个 Jira 工单只能导入一次测试用例，无法重复执行此操作。

如果进行 BDD 测试，还可以直接在 Katalon True Platform 中查看结果。

充分利用此集成的专业建议

利用 JQL 实现双向追溯
集成是双向的。通过 Jira > Import Test Case from JIRA JQL，可以直接将 Jira 问题导入 Katalon 作为测试用例，这对基于需求的测试极为有用。
结合 CI 管道实现完全自动化
如果启用了夜间运行的 CI 管道，请务必勾选 "Automatically submit test result"。与 Katalon 的 CI/CD 管道集成相配合，每次失败都会自动创建 Jira 工单，实现真正无人值守的自动化测试缺陷跟踪。
借助 True Platform 的双向 Jira 同步获得全生命周期可见性
除了 Studio 插件之外，Katalon True Platform 的 Test Management 组件还可以直接从 Jira 同步项目、版本、需求和缺陷。这意味着需求可追溯性和版本就绪程度始终是最新的，无需在缺陷跟踪器和测试管理层之间手动对齐。
牢记项目范围
Jira 集成是按 Katalon 项目配置的。如果工作涉及多个项目，每个项目都需要单独进行集成设置------只需快速重复上述步骤即可，无需再次安装插件。
设置 API 令牌轮换提醒
Katalon 的 Jira API 令牌一旦过期，会在迭代中期无声无息地让集成失效，而且不会报出明显错误。建议在令牌到期前两周添加日历提醒，主动进行轮换。
加密凭据
当 .prj 文件提交到共享的 Git 仓库时，"Encrypt authentication data" 复选框的重要性不言而喻，一定不要跳过。
每次升级 Studio 前验证插件版本
这是集成中断最常见的原因。Katalon Studio 8.x 与 9.x 对插件版本的要求不同------升级前务必检查 Katalon Store 插件页面上的 Requirements 标签页。

常见问题排查

问题	可能原因	解决方法
Connect 按钮无响应	API 令牌错误或 Server URL 有误	重新生成令牌；移除 URL 末尾的斜杠
结果中看不到缺陷图标	插件未加载	通过用户图标执行 Reload Plugins，确认状态为 Success
Default JIRA Project 下拉框为空	未通过认证连接	先点击 Connect，只有认证成功后下拉框才会填充
令牌过期错误	Jira API 令牌已超过有效期	在 id.atlassian.com 生成新令牌，并更新项目设置
链接时提示 "Jira issue cannot be found"	输入的 issue key 错误，或该 Jira 问题在账户中已不存在	核实 issue key 正确性，并确认所用 Jira 账户有权访问该项目
插件已在商店安装，但 Studio 中不显示	Studio 与插件版本不匹配	根据 Studio 版本（8.x 或 9.x）检查并安装正确版本的插件

总结

让 Katalon Jira 集成运转起来，是一次性、不到十分钟的设置，却能在每个迭代中持续获得回报。了解如何将 Katalon Studio 与 Jira Cloud 集成后，测试团队便拆除了自动化测试结果与缺陷待办列表之间的手动桥梁，让开发人员、产品经理等每一个利益相关者都能清楚地看到，某个失败测试与正在处理的工单之间那条可追溯的线索。

完整的设置流程概览如下：

从 Katalon Store 安装 Jira Integration 插件，并从 Atlassian Marketplace 安装 Katalon Test Automation for Jira 插件。
在 Katalon Studio 中 Reload Plugins，并确认 Status: Success。
进入 Projects > Settings > Plugins > JIRA。
启用集成，填写认证信息。
在 id.atlassian.com 为 Katalon 生成 Jira API 令牌。
粘贴令牌，点击 Connect，设置默认项目与问题类型。
运行测试，只需一次点击，便能自动将 Bug 从 Katalon 提交到 Jira。

如果 Katalon Studio 缺陷报告和自动化测试缺陷跟踪是团队的重中之重------事实上也理应如此------那么这套集成就是达成目标最直接的路径。而对于使用 Katalon True Platform 的团队，测试管理层的双向 Jira 同步还会将这种可追溯性扩展到整个质量生命周期，而非仅仅局限于单次测试运行。

常见问答

问：是否支持 Jira Server（本地部署版），而不仅是 Jira Cloud？

答：支持。配置方式与 Jira Data Center 相同，Server URL 填写 https://域名，不需要末尾路径，并且服务器需要有效的 SSL 证书。

问：Jira Integration 插件是免费的吗？

答：插件本身是免费的，但需要 Katalon Studio 拥有有效的许可证才能使用。

问：能否将一个测试失败关联到多个 Jira 工单？

答：一次提交只能创建一个新工单，但可以多次使用 "Link to Existing Issue" 功能，将同一个测试结果链接到多个已有的 Jira 问题。

问：是否与 Katalon True Platform 集成以实现集中报告？

答：是的。Katalon True Platform 提供双向 Jira 同步，可以将项目、版本、需求和缺陷从 Jira 同步过来，并在平台内实现全生命周期的质量可见性。

问：连接成功后，为什么我的 Jira Project 没有出现在下拉框中？

答：通常是因为没有点击 Connect 按钮，或者认证未能成功。只有成功建立连接后，下拉框才会自动填充可用的 Jira 项目和问题类型。请检查 API 令牌和 Server URL 是否正确。