Bruno API测试工具实战：Git原生、本地优先的10个高效技巧

1. 项目概述：为什么Bruno值得你投入时间？

如果你是一名开发者、测试工程师或者DevOps，每天和API打交道，那么Bruno这个名字最近可能已经不止一次出现在你的视野里了。它被很多人称为“Postman的本地化、开源替代品”，但这个标签其实远远不够。Bruno的核心魅力在于它的“Git-Native”理念——你的API集合不再是锁在某个云端平台里的黑盒，而是一个个可以像代码一样被版本控制、被评审、被协作的纯文本文件。这意味着，你的API测试脚本可以和你的后端代码库放在同一个Git仓库里，每一次接口变更的测试用例更新，都能像提交代码一样，有迹可循、有史可查。

我最初接触Bruno，是因为厌倦了传统API工具繁琐的账号体系、强制性的云端同步，以及团队协作时令人头疼的权限管理。当Postman宣布逐步淘汰本地草稿功能时，我意识到，是时候寻找一个真正尊重开发者数据主权和工作流的工具了。Bruno的出现，恰好击中了这个痛点。它不是一个试图构建生态闭环的“平台”，而是一个纯粹的、高效的、能与开发者现有工具链无缝集成的“客户端”。这篇文章，我将结合自己从零上手到深度使用的经验，分享10个实战技巧，帮你快速跨越新手期，成为能高效利用Bruno的专家。无论你是想摆脱云服务的束缚，还是希望将API测试真正融入CI/CD流程，这些技巧都能让你事半功倍。

2. 核心设计理念与快速上手配置

2.1 理解“Git-Native”与“Local-First”的真正含义

在深入技巧之前，我们必须先吃透Bruno的两个核心设计哲学：“Git-Native”和“Local-First”。这不仅仅是口号，而是决定了你如何使用它的根本。

Git-Native：这意味着Bruno的“集合”和“环境”等所有资产，都以纯文本文件（.bru文件）的形式存储在本地文件夹中。一个集合就是一个文件夹，里面包含多个.bru文件，每个文件对应一个API请求及其配置。这种设计带来了几个革命性的优势：

1. 版本控制友好：你可以直接用git add,git commit,git push来管理你的API测试套件。接口文档更新了？修改对应的.bru文件并提交，团队其他成员git pull就能同步。回滚到某个历史版本进行测试？一个git checkout命令就能搞定。
2. 与代码共置：你可以把API测试集合直接放在后端项目的根目录或/api-tests目录下。这样，开发新功能时，编写接口代码和编写对应的测试用例可以同步进行，极大提升了开发测试的一体化和可发现性。
3. 无供应商锁定：你的数据完全掌握在自己手中，格式是开放的。即使未来Bruno不维护了，你的测试用例依然是可读的文本文件，迁移成本极低。

Local-First：Bruno默认不进行任何云端同步。没有账号，没有登录，没有强制性的“工作区”。所有操作都在本地完成。协作通过你已有的Git工作流（如GitHub, GitLab, Gitee）来实现。这彻底解决了数据隐私和安全的担忧，也避免了因网络问题或服务宕机导致工具不可用的尴尬。

注意：很多从Postman转过来的朋友会下意识地寻找“同步”或“分享集合”的按钮。在Bruno里，这个动作被“Git提交与推送”替代了。你需要转变思维，将API测试资产视为项目源码的一部分。

2.2 五分钟完成Bruno的安装与初体验

Bruno的安装过程极其简单，它提供了多种平台的安装包。

1. 下载与安装：

   • 官方网站：访问 Bruno 的官方网站，下载对应你操作系统（Windows, macOS, Linux）的安装包。通常是一个.dmg（Mac）、.exe（Windows）或.AppImage（Linux）文件。
   • 包管理器安装（推荐给开发者）：
     • macOS (Homebrew):brew install bruno
     • Linux (Snap):snap install bruno
     • Windows (Winget):winget install Bruno.Bruno

   安装后打开，你会看到一个非常简洁的界面，没有注册弹窗，直接进入工作区。

2. 创建你的第一个集合： 在Bruno中，核心单位是“集合”。点击界面上的“Create Collection”按钮。

   • 命名：给你的集合起个名字，例如My-Project-APIs。
   • 选择存储位置：这是最关键的一步。不要随意放在桌面或下载文件夹。我强烈建议你将其创建在你的项目代码仓库目录内。例如，如果你的项目路径是~/projects/my-backend，那么就在这个目录下创建一个子文件夹，比如api-tests，然后将Bruno集合创建在这里。这样，它天生就和你的代码在一起了。
   • 观察文件结构：创建完成后，去你选择的目录看看。你会发现一个以集合名命名的文件夹（如My-Project-APIs），里面有一个bru.json的元数据文件。后续你在这个集合里创建的每一个请求，都会是一个独立的.bru文件。

3. 发送第一个请求： 在新建的集合上右键，选择“Add Request”。

   • 命名请求：例如Get User List。
   • 填写URL：输入一个公开的测试API，比如https://jsonplaceholder.typicode.com/users。
   • 选择方法：默认是GET，保持即可。
   • 点击“Send”：右侧会立刻显示响应的状态码、时间和响应体。

至此，你已经完成了Bruno最基础的搭建。但这只是开始，下面的技巧将带你解锁它的真正威力。

3. 从新手到精通的10个核心实战技巧

3.1 技巧一：像管理代码一样管理你的集合结构

新手常犯的错误是把所有请求都堆在一个集合里。在Bruno中，你应该利用其文件系统的特性，构建清晰的目录结构。

• 按功能模块划分文件夹：在集合根目录下，创建子文件夹来对应不同的业务模块。例如：

  My-Project-APIs/ ├── bru.json ├── Auth/ │ ├── Login.bru │ ├── Logout.bru │ └── RefreshToken.bru ├── UserManagement/ │ ├── GetUsers.bru │ ├── CreateUser.bru │ └── UpdateUser.bru └── Order/ ├── CreateOrder.bru └── GetOrderHistory.bru

  这样，当你的后端代码按模块组织时，测试用例能完美映射，查找和维护都非常直观。

• 使用.bru文件命名规范：文件名就是请求名。建议使用动词+资源的格式，如CreateProduct.bru,GetUserById.bru。保持一致性，团队协作时一目了然。

实操心得：我习惯在集合根目录的bru.json里，添加一个简单的README.bru文件（虽然Bruno不识别.md，但你可以创建一个内容为Markdown格式文本的请求，不实际发送，仅作说明）。在里面写明这个集合测试的API版本、基础URL、以及重要的环境变量说明，这对新加入项目的同事非常友好。

3.2 技巧二：深度玩转环境变量与脚本，实现动态化

环境变量是API测试自动化的基石。Bruno的环境变量管理非常灵活，支持多个环境（如local,dev,staging,prod），并且可以在脚本中动态赋值。

1. 创建与管理环境：

   • 点击左侧边栏的“Environments”图标（地球形状）。

   • 点击“Create Environment”，命名为Development。

   • 在Key-Value表格中，添加你的变量。例如：

     Key	Value
     base_url	https://api-dev.example.com
     api_version	v1
     admin_token	your_test_token_here

   • 你可以创建多个环境，并通过顶部的下拉菜单快速切换。切换环境时，所有使用这些变量的请求都会自动更新URL和参数。

2. 在请求中使用变量：在任何可以输入文本的地方（URL, Headers, Body），使用双花括号{{}}来引用变量。

   • URL:{{base_url}}/{{api_version}}/users
   • Header:Authorization: Bearer {{admin_token}}
   • Body (JSON):{"email": "{{test_user_email}}"}

3. 使用脚本动态设置变量：这是Bruno的高级功能，能让你在请求前后执行JavaScript代码。

   • 前置脚本 (Pre-request Script)：在请求发送前运行。常用于生成签名、计算时间戳、或从其他来源获取token。
   • 后置脚本 (Assertion Script)：在收到响应后运行。用于提取响应数据并存入变量，或进行复杂的断言。

   实战示例：自动处理登录Token假设你需要先登录获取token，然后用于后续所有请求。

   • 在Login.bru的断言脚本里，写入：

     // 假设登录响应是 {“token”: “xyz123”, “user”: {…}} const responseData = JSON.parse(bruno.response.body); // 将token设置到环境变量中 bruno.setEnvVar(‘auth_token’, responseData.token); // 你也可以断言状态码 bruno.test(“Status code is 200”, () => { bruno.expect(bruno.response.status).to.equal(200); });

   • 在后续需要认证的请求的Header中，使用Authorization: Bearer {{auth_token}}即可。

3.3 技巧三：高效处理认证与Cookie管理

API认证是测试中的高频需求。Bruno支持多种认证方式，并且对Cookie的管理非常直观。

• 内置认证类型：在请求的“Auth”标签页下，你可以选择None,Bearer Token,Basic Auth,OAuth 2.0等。对于最常见的Bearer Token，直接粘贴token或使用{{auth_token}}这样的变量即可。

• 手动管理Cookie（应对热词“bruno设置cookie”）：有些API的认证依赖于Cookie，特别是Session认证或某些SSO场景。Bruno没有像浏览器那样显式的Cookie管理器，但它会自动处理响应头中的Set-Cookie，并在后续发往同一域名的请求中自动携带。

  • 查看Cookie：发送一个登录请求后，你可以在响应结果的“Cookies”标签页中看到服务器设置的Cookie详情。
  • 手动设置Cookie：如果某些场景需要你手动初始化Cookie，可以在请求的“Headers”标签页中，直接添加一个Cookie头。其值格式与浏览器相同，例如：sessionId=abc123; userId=456。
  • 使用脚本处理Cookie：对于更复杂的场景，你可以在前置脚本中通过bruno.setCookie(‘domain.com’, ‘cookieName’, ‘cookieValue’)来动态设置。

注意事项：Bruno的Cookie是跟随“集合”存储的，并且是明文保存在本地文件中的。切勿将包含敏感信息（如生产环境Session）的Cookie集合提交到公开的Git仓库。务必使用.gitignore忽略这些包含敏感信息的集合，或使用环境变量来管理敏感值。

3.4 技巧四：编写健壮且可读的断言脚本

断言是自动化测试的灵魂。Bruno的断言脚本基于一个轻量级的断言库，语法直观。

• 基础断言示例：

  // 断言状态码为200 bruno.test(“Status is 200”, () => { bruno.expect(bruno.response.status).to.equal(200); }); // 断言响应体包含某个字段 bruno.test(“Response has user id”, () => { const body = JSON.parse(bruno.response.body); bruno.expect(body).to.have.property(‘id’); bruno.expect(body.id).to.be.a(‘number’); }); // 断言响应时间在合理范围内 bruno.test(“Response time is acceptable”, () => { bruno.expect(bruno.response.time).to.be.lessThan(500); // 小于500毫秒 });

• 提取数据供后续请求使用：

  // 提取新建用户的ID，存入变量 const body = JSON.parse(bruno.response.body); if (body && body.id) { bruno.setEnvVar(‘new_user_id’, body.id.toString()); // 注意转为字符串 }

  然后，在下一个删除或查询用户的请求URL中，就可以使用/users/{{new_user_id}}。

• 组织断言：一个请求的断言脚本里可以包含多个bruno.test块。Bruno会依次执行并报告每个测试的通过与否。清晰的测试描述能让你在测试失败时快速定位问题。

3.5 技巧五：利用Collection Runner实现接口流程自动化

单个请求的测试是点，Collection Runner能将点连成线，实现完整的业务流程测试。

1. 创建测试流程：在集合文件夹中，你可以创建一个特殊的bru.json文件来定义运行顺序，但更直观的方法是使用Bruno GUI界面中的“Collection Runner”。
2. 配置Runner：
   • 在左侧边栏点击“Runner”图标（播放键形状）。
   • 将你的集合或文件夹拖入运行区域。
   • 调整顺序：拖拽请求来调整执行顺序。例如：1.登录 -> 2.创建资源 -> 3.查询资源 -> 4.更新资源 -> 5.删除资源 -> 6.登出。
   • 选择环境：为这次运行选择一个预设的环境（如Development）。
   • 设置迭代与延迟：可以设置整个流程运行多次，或请求之间添加延迟，用于压力测试或模拟用户操作间隔。
3. 运行与查看报告：点击“Run”按钮，Bruno会依次执行所有请求。你可以实时看到每个请求的状态（通过/失败）、耗时。运行结束后，会有一个简单的摘要报告，列出所有断言的结果。

实战场景：每晚定时跑一遍核心业务流程的回归测试，确保主功能正常。你可以将Bruno集合与GitHub Actions或Jenkins等CI工具结合，实现自动化（详见技巧十）。

3.6 技巧六：处理GraphQL和gRPC等现代API

Bruno并非只支持REST API，它对现代API协议的支持是其一大亮点。

• GraphQL测试：

  1. 创建新请求，将方法从GET/POST切换到GRAPHQL。
  2. 在“Query”标签页中，直接编写你的GraphQL查询（Query）或变更（Mutation）语句。
  3. 在“Variables”标签页中，以JSON格式提供查询变量。
  4. 在“Headers”中，通常需要设置Content-Type: application/json。 它的体验非常原生，比在Postman中把GraphQL查询塞进Body里要清晰得多。

• gRPC测试（需要服务反射）：

  1. 创建新请求，将方法切换到GRPC。
  2. 输入你的gRPC服务器地址（如localhost:50051）。
  3. Bruno会尝试连接服务器并获取服务定义（如果服务器启用了反射）。成功后，你可以从下拉列表中选择服务、方法。
  4. 在“Message”标签页中，以JSON格式填写请求的protobuf消息内容。 这对于测试微服务接口极其方便，无需手动编译proto文件生成客户端。

3.7 技巧七：团队协作与Git工作流集成

这是Bruno“Git-Native”理念的核心价值体现。团队如何高效地共用一套API测试集合？

1. 共享集合仓库：为API测试单独创建一个Git仓库，或者将其作为子目录放在后端项目仓库中。这是唯一的“真相之源”。
2. 定义协作规范：
   • 分支策略：可以模仿代码开发流程。main分支存放稳定的测试用例。开发新功能时，创建feature/login-test分支来添加或修改测试用例。
   • 代码评审：对.bru文件的修改（新增接口测试、更新断言、修改环境变量）发起Pull Request。团队成员可以像评审代码一样评审测试逻辑，确保测试的准确性和覆盖率。
   • 解决冲突：因为文件是纯文本，合并冲突时可以使用标准的Git工具或IDE来解决，非常清晰。
3. 环境变量分离：个人本地环境变量（如本地数据库连接串、个人测试账号）绝对不能提交到共享仓库。Bruno的环境变量可以导出为文件。团队应该共享一个environments文件夹，里面存放dev.bruenv,staging.bruenv等不包含敏感值的环境定义文件（例如只定义base_url,api_version）。每个成员在本地克隆仓库后，导入这些环境文件，再在本地添加自己的敏感变量（如个人token）。这些本地添加的变量不会污染共享文件。

3.8 技巧八：使用快捷键与高级功能提升效率

任何工具，熟练使用快捷键都能极大提升效率。

• 常用快捷键：

  • Cmd/Ctrl + N: 新建请求
  • Cmd/Ctrl + S: 保存当前请求（Bruno是自动保存，但这是个好习惯快捷键）
  • Cmd/Ctrl + Enter: 发送当前请求
  • Cmd/Ctrl + Shift + R: 运行Collection Runner
  • Cmd/Ctrl + B: 切换侧边栏显示
  • 在URL/Header输入框，按Tab键可以快速补全已输入过的历史值或变量名。

• 高级功能：

  • 导入导出：Bruno支持从Postman、Insomnia等工具导入集合（Collection v2.1格式），迁移成本很低。你也可以将Bruno集合导出为OpenAPI (Swagger) 规范，用于生成文档。
  • 代码生成：在请求发送后，点击响应区域下方的“Code”按钮，Bruno可以为你生成当前请求的cURL命令，以及多种编程语言（如JavaScript Fetch, Python requests, Go）的代码片段，方便你将其集成到自己的自动化脚本中。

3.9 技巧九：调试与问题排查实战指南

即使是最简单的请求，也可能遇到问题。以下是快速排查的步骤：

1. 检查网络与代理：首先确认你的网络连接正常。如果公司有代理，需要在Bruno的设置（Settings -> Network）中配置。Bruno默认使用系统代理设置。
2. 仔细查看请求详情：发送请求前，点击URL输入框旁边的“Preview”按钮，可以预览最终将要发送的完整请求URL（变量已被替换）。在“Headers”标签页，确认所有必要的请求头都已正确添加且值无误（特别是Content-Type和Authorization）。
3. 查看原始请求与响应：发送请求后，在结果面板的“Timeline”或“Raw”标签页，你可以看到原始的HTTP请求和响应文本。这是排查问题的金矿。对比你预期的请求和实际发出的请求，差异往往就在这里。
4. 活用控制台日志：在你的前置脚本和断言脚本中，可以使用console.log()输出调试信息。这些日志会在请求结果下方的“Console”标签页中显示。例如：console.log(‘Extracted token:’, bruno.getEnvVar(‘auth_token’));。
5. 环境变量未定义：如果遇到{{variable}}没有被替换的情况，请检查：1）当前选择的环境是否正确；2）变量名是否拼写错误；3）变量是否确实在当前环境中定义。
6. SSL证书问题：在测试本地开发环境（https://localhost）时，可能会遇到SSL证书错误。你可以在Bruno的设置中临时关闭SSL验证（Settings -> General -> SSL Verification），但仅限本地开发，切勿用于测试远程服务器。

3.10 技巧十：将Bruno集成到CI/CD流水线

这是实现API测试自动化的最后一步，也是价值最大的一步。Bruno本身是图形化工具，但可以通过其命令行工具bru实现无头运行。

1. 安装CLI工具bru：
   • 这是一个独立的Node.js包。通过npm或yarn全局安装：npm install -g @usebruno/cli
2. 编写运行脚本： 在你的项目根目录创建一个脚本文件，例如run-api-tests.sh：

   #!/bin/bash echo “Running Bruno API tests…” # 切换到测试集合目录 cd ./api-tests/My-Project-APIs # 使用bru run命令运行整个集合，指定环境文件 bru run --env ../../environments/staging.bruenv # 检查退出码，非0表示测试失败 if [ $? -ne 0 ]; then echo “API Tests Failed!” exit 1 else echo “All API Tests Passed!” fi

3. 在CI中配置（以GitHub Actions为例）： 在项目.github/workflows目录下创建api-test.yml：

   name: API Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup Node.js uses: actions/setup-node@v3 with: { node-version: ‘18’ } - name: Install Bruno CLI run: npm install -g @usebruno/cli - name: Run API Tests run: bash ./run-api-tests.sh env: # 将敏感的环境变量（如token）通过GitHub Secrets注入 PROD_API_TOKEN: ${{ secrets.PROD_API_TOKEN }}

   这样，每次代码推送或发起PR时，都会自动运行API测试套件，确保接口变更不会破坏现有功能。

4. 常见问题与进阶排查技巧

即使掌握了上述技巧，在实际使用中仍会遇到一些特有的问题。这里记录了几个我踩过的坑和解决方案。

问题1：团队共用集合时，环境变量如何管理才不会混乱？这是Bruno协作中最常见的问题。我们的解决方案是“三层环境变量管理法”：

1. 项目级默认环境(default.bruenv)：存放在集合仓库的environments目录下，包含所有非敏感的、项目通用的变量，如base_url,api_version。每个成员克隆后导入。
2. 个人本地覆盖：每个成员在Bruno App中，在导入的项目环境基础上，添加自己本地的敏感变量（如个人账号密码、本地开发数据库配置）。这些设置保存在本地，不提交。
3. CI/CD环境变量：在GitHub Actions/GitLab CI等平台上，通过bru run --env指定环境文件，同时利用CI平台的Secrets功能注入敏感变量（如PROD_API_TOKEN）。环境文件里可以引用这些注入的变量（格式可能需调整，如使用$VAR）。

问题2：.bru文件冲突了怎么办？因为.bru文件是JSON格式的纯文本，合并冲突和解决代码冲突一模一样。打开冲突文件，你会看到标准的Git冲突标记（<<<<<<<,=======,>>>>>>>）。你需要：

• 理解冲突部分：通常是请求的URL、Header、Body或脚本被不同的人修改了。
• 与发生冲突的同事沟通，确定最终的正确内容。
• 手动编辑文件，删除冲突标记，保留正确的内容。
• 保存文件，然后执行git add和git commit完成冲突解决。

问题3：断言脚本中bruno.response.body有时不是对象？这是一个容易出错的地方。bruno.response.body永远是字符串类型。即使响应头是application/json，你也需要先解析它。

// 正确做法 let responseData; try { responseData = JSON.parse(bruno.response.body); } catch (e) { bruno.test(“Response is valid JSON”, () => { bruno.expect.fail(“Response body is not valid JSON: “ + e.message); }); return; // 如果不是JSON，提前结束 } // 现在可以使用responseData.user.id了

对于非JSON响应（如XML、纯文本），你需要使用其他方式解析或直接进行字符串匹配。

问题4：Collection Runner中，如何让一个请求的变量传递给下一个请求？这依赖于环境变量。在第一个请求的断言脚本中，使用bruno.setEnvVar(‘key’, ‘value’)设置变量。这个变量会进入当前Runner会话的环境上下文。在后续的请求中，直接使用{{key}}引用即可。Runner会按顺序执行，并保持这个环境上下文。

问题5：Bruno的性能或功能不如Postman强大？这需要客观看待。Bruno的优势在于轻量、快速、本地优先和与Git的无缝集成。它的核心定位是一个高效的开发者客户端，而不是一个全功能的API监控、Mock和文档平台。对于复杂的API监控、自动化工作流编排，你可能需要结合其他工具（如专门的API监控服务、Mock服务器等）。但对于日常开发、调试、回归测试和团队协作，Bruno提供的功能已经绰绰有余，且其简洁的设计避免了不必要的认知负担。选择工具，关键是看它是否契合你的核心工作流。