Bruno 编码规范实践:从 ESLint 风格规则到 Electron E2E 测试的完整约定

原创2026-09-07 17:47:301,721 阅读
文章标签:开发工具接口测试测试桌面应用API设计CLI

Bruno 编码规范实践:从 ESLint 风格规则到 Electron E2E 测试的完整约定

本文以 Bruno 仓库根目录的 CODING_STANDARDS.md 为主体,完整梳理 Bruno(开源的 API 探索与测试 IDE)的编码约定:最小 diff 原则、通用风格规则、标点与空格细则、测试编写准则(含 Electron Playwright E2E 测试的六条硬规则)、React UI 特定约束,以及可读性与抽象的取舍标准。同时结合 eslint.config.js、playwright.config.ts、playwright/index.ts 与 tests/utils/page/ 等仓库文件,说明每条约定在工程中的落地与强制执行机制,帮助你在向 Bruno 提交 PR 前对齐其代码风格与测试文化。

最小 diff 原则:Bruno 对代码变更的第一要求

Bruno Coding Standards 开篇就立下一条总则:没有实际变更就不产生 diff,代码改动尽可能小,避免无意义的空白符 diff。虽然 ESLint 已经处理了大部分自动格式问题,但开发者在提交和发起 PR 前仍须自行检查改动。

这条原则在仓库的工程链路上有直接支撑:

  • 根 package.json 配置了 husky + nano-staged,其中 nano-staged 对 *.{js,ts,jsx} 文件自动执行 npm run lint:fix(即 npx eslint --fix)。也就是说,在 Bruno 的提交流程中,风格类问题会在 pre-commit 阶段被自动修复,人工只需聚焦逻辑变更本身。
  • eslint.config.js 额外挂载了 eslint-plugin-diff 插件(diff plugin),用于在代码评审中约束 diff 质量。
  • 仓库还区分了修复模式:isFixMode(--fix / --fix-dry-run)下会临时关闭 eqeqeq 与 prefer-const 等规则(见 eslint.config.js 第 13 行与第 90-91 行),避免 --fix 时产生大量与本次任务无关的连带改动——这正是“diff 最小化”原则在工具链上的体现。

通用风格规则(General Style Rules)

原文档给出的四条基础风格约定,全部可以在 eslint.config.js 中找到对应的机器可执行规则:

风格约定 原文要求 对应 ESLint 配置
缩进 使用 2 个空格缩进,禁止 Tab stylistic.configs.customize({ indent: 2 })(eslint.config.js)
引号 字符串统一单引号;JSX/TSX 属性使用双引号以遵循 React 惯例(如 <svg xmlns="..." viewBox="...">) quotes: 'single'(@stylistic 规则默认豁免 JSX 属性)
分号 语句结尾必须加分号 semi: true
JSX 已启用 JSX,合理场景直接使用 jsx: true

其中 customize({ indent: 2, quotes: 'single', semi: true, jsx: true }) 是 @stylistic/eslint-plugin 的批量定制入口,一条配置同时收敛了缩进、引号、分号和 JSX 开关四类风格,保证所有受 lint 的文件(mainLintFiles 列表覆盖了 tests/**、playwright/** 以及 packages/bruno-app、bruno-cli、bruno-common、bruno-requests、bruno-sqlite 等十余个 workspace 包)风格一致。

标点与空格细则:逐条对照 @stylistic 规则

原文档 “Punctuation and Spacing” 一节共 10 条细则,几乎每条都精确映射到 eslint.config.js 中显式配置的 @stylistic/* 规则。下表逐条对照,方便你在本地复现或校验:

原文规则 对应配置 说明
不写尾随逗号(no trailing commas) '@stylistic/comma-dangle': ['error', 'never'] 数组、对象、参数列表末尾都不留悬挂逗号
箭头函数参数永远加括号,即使单参数 '@stylistic/arrow-parens': ['error', 'always'] (x) => x 而非 x => x
多行构造开括号同行;多行结构至少 2 个元素才换行 '@stylistic/brace-style': ['error', '1tbs', { allowSingleLine: true }] + '@stylistic/curly-newline': ['error', { multiline: true, minElements: 2, consistent: true }] 1tbs 风格 + 最小 2 元素阈值
函数参数括号内不换行 '@stylistic/function-paren-newline': ['off'] 保持参数列表紧凑
箭头两侧留空格:() => {} '@stylistic/arrow-spacing': ['error', { before: true, after: true }] 箭头前后各一个空格
函数名与调用括号之间不留空格:func() 而非 func () '@stylistic/function-call-spacing': ['error', 'never'] 调用点紧贴括号
分号写在行尾而不是新起一行 '@stylistic/semi-style': ['error', 'last'] 禁止“分号独占一行”写法
不强制最大行宽,写可读代码而非挤压缩排 '@stylistic/max-len': ['off'] 关闭行宽限制
JSX 一行多个表达式允许 '@stylistic/jsx-one-expression-per-line': ['off'] + '@stylistic/max-statements-per-line': ['off'] 为 JSX 布局留出灵活性

此外还有几处显式关闭以放宽限制的配置:array-bracket-spacing: never(数组内不留空格)、multiline-ternary: off、padding-line-between-statements: off、no-mixed-operators: off(见 eslint.config.js)。

除风格规则外,eslint.config.js 还保留一组质量类规则作为底线:no-unused-vars(warn)、no-debugger(warn)、eqeqeq(warn,always)、prefer-const(warn)、no-var(warn)、no-unreachable(warn)、no-duplicate-imports(warn)等;对 TypeScript 包(bruno-common、bruno-filestore、bruno-requests 等)还绑定了各自 workspace 的 tsconfig.json 作为 type-aware 解析项目(如 eslint.config.js 中 project: './packages/bruno-common/tsconfig.json')。

按原文档结语:这些规则的目的是让代码库保持和谐(harmonious),遇到不适配的规则应讨论而不是绕开。

测试准则:行为优先、高价值优先

CODING_STANDARDS.md 的 “Tests” 一节给出了 Bruno 对单元测试/集成测试的完整立场,核心可以归纳为以下十条准则(原文逐条要求,此处按原文语义整理):

  1. 新功能或重要变更必须补测试:代码被新增、删除或大幅修改时,对应测试必须更新或新建。
  2. 高价值测试优先于覆盖率数字:聚焦关键、复杂、易坏的行为,不为覆盖率本身而写测试。
  3. 行为驱动而非实现驱动:测试验证真实期望输出与可观察行为,不测内部细节;除非绝对必要,不 mock 内部逻辑。
  4. 最小化 mock:仅 mock 外部服务、慢系统或非确定性行为;可行时优先走真实流程。
  5. 可读、可维护:命名描述化、setup 最小化、避免不必要抽象,清晰优于 clever。
  6. 让测试“有用地失败”:失败信息应清楚指出哪个行为坏了、为什么坏。
  7. 覆盖 happy path 与真实异常路径:错误处理、边界条件、降级模式行为都要验证。
  8. 确定性可复现:无随机性、无时序依赖、无未显式控制的环境假设。
  9. 避免测试过拟合当前实现:只断言必须成立的点,不断言偶然细节,为未来灵活性留空间。
  10. 共享测试工具但克制:优先复用公共测试工具而非复制粘贴 setup,但仅在其真正降低复杂度时。

另外两条工程性要求:测试要足够快以便持续运行(避免长耗时操作,优先轻量 fixture 与隔离单元);以及 E2E 测试的专项要求,见下一节。

这些准则在仓库测试布局上得到印证:packages/bruno-js/tests/、packages/bruno-lang/v2/tests/(22 个 JS 测试 + 28 个 JSON 期望文件)、packages/bruno-converters/tests/ 等目录大量使用 fixture 目录 + 期望快照文件的方式做行为级断言,与“验证真实期望输出”的准则一致。

E2E 测试:Electron Playwright 的六条规则

原文档对 E2E 的规范相当具体。Bruno 的 E2E 规格(spec)规范位置是 <project-root>/tests/**,典型匹配 tests/**/*.spec.{ts,js};更完整的 Playwright 工作流指引见 docs/playwright-testing-guide.md。目标是让测试真正行为化、可维护、可安全并行。原文的六条规则:

  1. 验证用户可见行为,而非实现细节
    • 优先断言 UI 状态、持久化数据、窗口、对话框、文件系统副作用与应用级结果;
    • 避免硬编码等待、脆弱选择器、伪造内部状态检查,以及“点击然后断言 mock 被调用”式的测试(除非用户行为本身才是重点)。
  2. 测试必须 Electron-aware
    • 正确 Electron 应用启动模式;
    • 主窗口、辅助窗口、对话框、菜单、原生 prompt、剪贴板、文件选择器、IPC 驱动的 UI 行为,都通过可观察结果处理;
    • 除非 setup 或受控 fixture 绝对需要,否则不要深入应用内部。
  3. 并行安全(parallel-safe)
    • 不共享 user data 目录、端口、文件、数据库、缓存、剪贴板假设或全局应用状态;
    • 每个测试有隔离的临时路径、唯一的 workspace/collection 名称、确定性清理;
    • 避免测试顺序假设。
  4. 拒绝硬编码混乱(No hardcoded mess)
    • 魔法超时 → 事件驱动等待;
    • 脆弱的文本/索引选择器 → role、label、test id 或稳定的面向用户的选择器;
    • 重复 setup → fixture;
    • 硬编码绝对路径 → 临时目录;
    • 随机 sleep → 等待真实应用信号。
  5. 每个测试遵循 Arrange-Act-Assert-Cleanup 结构:创建隔离 fixture 状态 → 执行真实用户动作 → 验证可观察行为结果 → 清理隔离资源。
  6. 定位器与动作集中管理:所有 locator 和 action 放在 tests/utils/page/* 的 page module 中,spec 里永远不内联原始选择器;page-module 模式与 buildCommonLocators 的用法见 docs/playwright-testing-guide.md 的 Best Practices 一节。

对于每个待评审的测试文件,原文还给出了一份“改写检查清单”:识别行为性 vs 非行为性测试;标记脆弱选择器、硬编码等待、共享状态、串行依赖与伪断言;按 Playwright Electron 最佳实践重写;使其具备并行能力;并简要说明每处改写为何更好。

规则落地的源码证据:fixture、并行与 page module

上述 E2E 规则不是纸面约定,playwright/index.ts 的自定义 fixture 体系是其直接实现:

  • 隔离临时目录:createTmpDir fixture 基于 fs.mkdtemp(os.tmpdir() + 'pw-<tag>-') 创建 worker 级临时目录,tag 会先剥离 Windows 非法字符(<>:"/\|?* 与空白)避免路径非法;teardown 时批量 rm -rf 并带重试(playwright/index.ts)。这就是规则 3“隔离 temp 路径 + 确定性清理”的落地。
  • 隔离 user data 与并行安全:launchElectronApp 为每个 worker 启动独立的 Electron 实例,通过 ELECTRON_USER_DATA_PATH 注入独立 user data 目录,并显式设置 DISABLE_SINGLE_INSTANCE: 'true' 与 PLAYWRIGHT: 'true' 环境变量(playwright/index.ts);installFakeClipboard fixture 用 Object.defineProperty 替换页面内的 navigator.clipboard,避免各并行 worker 争抢真实系统剪贴板,teardown 时精确还原——这正是规则 3“不共享剪贴板假设”的解法。
  • 应用就绪信号替代 sleep:waitForReadyPage 等待 [data-app-state="loaded"] 选择器出现后再进入测试(playwright/index.ts),对应规则 4“等待真实应用信号”;docs/playwright-testing-guide.md 的 Troubleshooting 一节也明确写道:超时是症状不是问题,应等待 app-ready 信号而非调大 timeout。
  • 优雅关闭:closeElectronApp 先在主进程内逐个 win.close(),再 app.close(),每步都有超时上限(3s/5s),仅当进程真实存活超时时才 SIGKILL(playwright/index.ts),保证 teardown 不会拖垮 worker 预算。
  • 偏好默认值同步:defaultPreferences(跳过 onboarding 的 onboarding.hasLaunchedBefore 等)在 launchElectronApp 中被 merge 进每个测试的 preferences.json;测试指南特别要求:应用偏好 schema 每新增一个键,就要同步更新这里,否则测试跑在未设置偏好上、与真实行为分叉。
  • fixture 与 fixture 目录约定:collectionFixturePath 自动把 spec 同目录的 fixtures/collections 或 fixtures/collection 复制到临时目录供测试变更;pageWithUserData 则要求 spec 目录存在 init-user-data/,缺失时直接抛出指向性错误提示改用 page fixture。仓库中大量 tests/**/init-user-data/ 与 tests/**/fixtures/ 目录正是这套约定的产物。

并行配置:playwright.config.ts 中 fullyParallel: true、CI 下 forbidOnly 与 retries: 2,并按资源隔离拆分 projects——default(排除 ssl/**、auth/**、benchmarks/**、proxy/system-pac/**、mock-server/**)、auth、ssl(自定义 CA 证书需独立服务与证书生成)、system-pac(与 proxy/pac 共享 PAC/proxy/target 端口,须在 default 之后独立运行)、mock-server(workerIndex 端口 + per-worker Electron 状态)。webServer 段会自动启动 npm run dev:web(等待 stdout 匹配 ready built in)与 npm start --workspace=packages/bruno-tests(等待 http://localhost:8081/ping 就绪)两个前置服务。这解释了为什么根 package.json 的测试脚本按 project 拆分:test:e2e(default + system-pac)、test:e2e:ssl、test:e2e:auth、test:e2e:mock-server、test:e2e:sanity。

page module 模式:tests/utils/page/locators.ts 中的 buildCommonLocators(page) 统一汇聚 sidebar、runner、tabs、environment、preferences 等各区块的 locator builder,各区块(如 tests/utils/page/mounting.ts 的 buildCollectionTreeLocators 与其同文件的 waitForCollectionMount、openCollectionFromPath 等 action)一文件一区、locator 与动作同置。tests/utils/page/index.ts 再以 export * 聚合导出。spec 的标准写法是构建一次 locators 后按需解构,例如:

import { test, expect } from '../../playwright';
import { buildCommonLocators, createCollection, createRequest, closeAllCollections } from '../utils/page';

test('should rename a request via the sidebar', async ({ page, createTmpDir }) => {
  const { sidebar, actions, dropdown } = buildCommonLocators(page);
  const testDir = await createTmpDir('rename-test');

  await createCollection(page, 'My Collection', testDir);
  await createRequest(page, 'Test Request', 'My Collection');

  await sidebar.request('Test Request').hover();
  await actions.collectionItemActions('Test Request').click();
  await dropdown.item('Rename').click();

  await closeAllCollections(page);
});

测试指南(docs/playwright-testing-guide.md)还补充了两条与 E2E 规则 5、6 相呼应的细则:action helper 内部用 waitFor 做同步、不承载断言,expect 只留在 spec 中;新 UI 区块 → 新建 page module 文件 → 挂进 buildCommonLocators,对新增 spec 严格执行、对既有 spec 宽容(但大改时应顺带提取 selector)。语义化选择器优先级为 getByTestId / getByRole / getByLabel,避免 .btn-primary、#id 这类脆弱选择器。这也解释了 UI 代码中“给可测元素加 data-testid”这条 React 规则存在的意义。

UI 特定指令:React 部分的硬约束

原文档 “UI Specific instructions / React” 一节共 9 条,逐条如下:

  1. 颜色用 styled-components 的 theme prop,不用 CSS 变量(在 styled component 或任何使用 styled component 的 React 组件上下文中);
  2. Styled Components 作为包装器定义自身与子组件样式,Tailwind class 专用于布局类样式;Styled Component 的 CSS 可以影响布局,但 Tailwind class 不应定义颜色;
  3. MUST:业务逻辑、数据获取、副作用优先封装为自定义 hooks;
  4. MUST:除非绝对必要避免 useEffect,优先派生状态(derived state)与事件处理器;
  5. SHOULD:只在必要时 memoize(useMemo/useCallback),且优先考虑先把逻辑移进 hook;
  6. MUST:app 代码中禁止命名空间访问 hooks(如 React.useCallback、React.useMemo、React.useState),必须直接导入:
    • 正确:import { useCallback, useMemo, useState } from "react";
    • 避免:import * as React from "react"; 之后 React.useCallback(...)
  7. 为可测元素添加 data-testid(供 Playwright 使用)——与上文 E2E page module 模式直接呼应;
  8. 工具函数就近放置:真正组件专属的 utility 与组件同目录,共享项放公共目录;
  9. 避免受控/非受控状态混用:组件要么受控要么非受控,状态需要有单一事实来源,而不是“由 props 算一遍再内部重算一遍”;SHOULD 用派生状态变量替代多余的 useState。

配套的工具链约束在 eslint.config.js:bruno-app 的源码统一启用 eslint-plugin-react-hooks 的 rules-of-hooks 与 exhaustive-deps(均为 warn);app 代码的 languageOptions.globals 明确将 Buffer、process、require、ipcRenderer 设为 false 并开 no-undef: error(eslint.config.js),从编译器层面阻止渲染进程代码误用 Node 全局——这与“避免混合受控状态、保持单一事实来源”一样,都是防止渲染层与主进程层职责混淆的防线。

可读性与抽象:克制地抽象

原文档最后一节 “Readability and Abstractions” 给出了 Bruno 的抽象哲学,7 条规则:

  1. 提取能提升可读性或服务于明确预期复用的抽象;
  2. 避免“增加复杂度却没换来清晰度或复用”的抽象;
  3. 函数命名要简洁且有描述性;
  4. 需要时用 JSDoc 注释补充抽象的细节;
  5. 适度函数式:不必走到 ADT 与 Monad 那么深,目标是让数据管道一目了然、人人可读可贡献;
  6. 避免“单行抽象”——那种只是让调用栈多一层的函数;
  7. 在复杂代码流处加有意义的注释,而不是解释显而易见的内容。

还有一条独立的 TypeScript 专项规则:避免滥用可选链(?.)——它会掩盖“值是否真正可能为 null”,与 TypeScript 的类型保证背道而驰。只在该处就地处理了 null 情形(fallback、提前返回、guard)时才使用;否则应修类型或先做收窄(narrowing)。

小结:如何在 Bruno 中落地这套规范

  • 风格层:2 空格缩进、单引号(JSX 属性双引号)、强制分号、无尾逗号、箭头参数加括号、func() 紧贴括号、行宽不强制——由 eslint.config.js 中 @stylistic 规则全量机器化,npm run lint / npm run lint:fix 执行,nano-staged 在提交时自动 lint:fix;
  • 测试层:行为驱动、高价值优先、最小 mock、确定性、快速可连跑;E2E 额外要求用户可见行为断言、Electron-aware、并行安全、事件驱动等待、Arrange-Act-Assert-Cleanup 结构、selector 集中到 tests/utils/page/* page module;
  • UI 层:theme prop 管颜色、Tailwind 只管布局、hooks 封装业务逻辑、慎用 useEffect 与 memoize、直接导入 hooks、受控/非受控单一事实来源、data-testid 为 Playwright 服务;
  • 抽象层:克制抽象、描述性命名、JSDoc 补充、有意义的注释、慎用 ?.。

对照仓库实际代码(tests/ 下数十个功能目录、packages/*/tests/ 的 fixture 式单测、playwright/index.ts 的 worker 级隔离 fixture),这套规范在 Bruno 中是“文档 + 工具链 + fixture 基础设施”三位一体的约束,而不仅仅是一篇风格指南。

登录后查看全文
bruno