Lovefield 开发者环境搭建与测试全指南：依赖安装、Closure 构建、Selenium 测试与贡献流程

• 关系型数据库
• 数据库
• 前端

Lovefield 是 Google 出品的纯 JavaScript 关系型数据库，面向 Web 应用提供 SQL 风格 API，跨浏览器（Chrome 37+、Firefox 31+、IE 11+、Edge、Safari 10+）运行。本文以仓库中的 docs/dev_setup.md 为主线，结合 package.json、gulpfile.js、tools/builder.js、tools/run_test.js 等源码，完整讲解从零搭建 Lovefield 开发环境、用 Closure 编译器构建产物、用 Selenium WebDriver 跑单元测试（本地与 Sauce Labs 云端两种模式），以及向项目提交贡献前必须通过的完整校验流程。读完本文，你将能独立完成 Lovefield 仓库的安装、构建、测试与贡献准备。

前置条件：Java、Git 与 Node.js

Lovefield 的开发工具链由三部分基础环境支撑，文档明确要求它们处于"可用状态"，且必须能被 PATH 搜索到：

• Java：Closure JavaScript Compiler 以 JAR 形式运行，需要 Java 运行时。
• Git：版本管理与贡献流程（Pull Request）的基础。
• Node.js：Lovefield 的各种开发工具（gulp、Closure 编译器 npm 包、selenium-webdriver 等）都运行在 Node.js 之上。Node.js 版本建议以 package.json 中的声明为准——当前仓库声明"engines": { "node": ">=12.16.3" }，而 .travis.yml 中 CI 使用node_js: "12.16.3"，两者相互印证，本地开发建议使用不低于 12.16.3 的 Node.js 版本。

值得注意的细节：gulp 任务本身也依赖 Node.js 生态。仓库在devDependencies中固定了gulp: "4.0.2"、gulp-closure-compiler、gulp-gjslint、jasmine、selenium-webdriver: "^3.6.0"、google-closure-compiler-java与google-closure-library: "20190618.0.0"等关键开发依赖，安装时请保持这些版本约束，避免工具链行为漂移。

Windows 用户的特殊注意事项

Windows 命令提示符（Command Prompt）存在命令行长度限制，而 Closure 编译器需要一条远超该限制的命令行才能运行，这会导致编译失败。文档给出的解决方案是安装一个能突破此限制的命令行工具，例如TCC/LE（Take Command Console / Light Edition）。在 Windows 下开发时，请改用这类工具执行 gulp/Closure 编译命令，而不是直接使用原生 Command Prompt。

设置开发环境：依赖安装

Lovefield 使用npm作为依赖管理器。克隆仓库后，在仓库根目录（即 package.json 所在目录）执行：

npm update

该命令会拉取 Lovefield 所需的全部依赖，其中最重要的两个：

• google-closure-compiler-java：Closure 编译器本体（JAR），由 npm 自动下载，无需手动安装编译器。它的路径在 tools/config.js 中被解析为node_modules/google-closure-compiler-java/compiler.jar。
• google-closure-library：Closure 库源码，用于测试环境的依赖解析，路径为node_modules/google-closure-library。

构建 Lovefield：Closure 编译器 + gulp

Lovefield 使用gulp作为构建管理器，使用Closure JavaScript Compiler对代码进行校验、压缩（minify）与混淆（uglify）。Closure 编译器由 npm 自动带入（见上文）。

在仓库根目录直接运行gulp（不带任何参数），即可看到全部支持的构建命令。从 gulpfile.js 的 default 任务源码中可以提取出完整的命令清单：

从源码看，gulp test --target=tests目前支持的浏览器目标是chrome|firefox|ie|safari，且--browser与--filter两个标志都可以重复传入多次，以同时跑多个浏览器或按多个模式过滤测试。

构建库产物：gulp build --target=lib

这是贡献者最常用、也最重要的构建命令。核心逻辑位于 tools/builder.js 的buildLib：

1. 通过depsHelper.scanDeps()扫描源码依赖；
2. 将依赖文件与lib/**/*.js（全部库源码）一起交给 Closure 编译器；
3. 注入builddef/firebase_externs.js作为 externs 声明；
4. 输出文件名为lf.js，写入dist/目录，期间还会剥离许可证头（StripLicense）。

编译模式由--mode决定，两种模式的差异定义在 tools/config.js：

• --mode=opt（发布模式）：compilation_level: 'ADVANCED'（高级优化），同时生成dist/lf.js.map源映射，并通过define: 'goog.DEBUG=false'关闭 Closure 的调试代码。这是贡献流程要求使用的模式。
• --mode=debug（调试模式）：启用debug并设置formatting: 'PRETTY_PRINT'，便于阅读与断点调试。

无论哪种模式，都叠加了一组公共编译标志：warning_level: 'VERBOSE'、language_out: 'ECMASCRIPT5_STRICT'，并开启了一长串jscomp_error严格检查（包括checkTypes、missingProperties、undefinedNames、visibility等），这意味着构建过程本身同时就是一次严格的类型与代码质量校验——任何类型错误都会导致构建失败。

构建测试：gulp build --target=tests

该命令编译tests/**/*_test.js下的全部测试文件，也可用--filter=<pattern>只编译匹配的测试。buildAllTests（tools/builder.js）的实现细节值得了解：

• 通过 glob 收集所有*_test.js文件，按 filter 过滤；
• 每个测试文件单独交给 Closure 编译器编译（debug 模式）；
• 编译前会先用SPAC（Schema Parser And Code generator）为测试所需的 schema 生成代码——生成对象由 tools/config.js 中的TEST_SCHEMAS定义，包括testing/hr_schema/hr_schema.yaml、testing/hr_schema/hr_schema_bundled.yaml、testing/order_schema.yaml与testing/perf/hr_schema_no_fk.yaml；
• 并行度受环境变量CONCURRENT_BUILDER控制，默认 8，可调高以加速构建。

测试 Lovefield：Selenium WebDriver

Lovefield 使用Selenium WebDriver驱动真实浏览器运行自动化测试。运行单元测试有两条路径：本地测试（调试与快速反馈）与Sauce Labs 云端测试（跨浏览器矩阵验证）。此外，仓库中实际存在三类测试（见 docs/running_tests.md）：

• 单元测试：验证库的正确性，即gulp test --target=tests对应的主体；
• SPAC 测试：验证 SPAC 代码生成器的正确性，绝大多数使用者用不到；
• 性能测试：用于监控 Lovefield 性能，主要由测试机器人运行。

方式一：本地测试（Local）

1. 从 Selenium 官方渠道手动下载并安装目标浏览器的WebDriver（ChromeDriver、geckodriver、IEDriverServer、SafariDriver 等），并确保其可被 Selenium 发现。
2. 在仓库根目录执行：

gulp test --target=tests --browser=<browser>

其中<browser>取值为chrome、firefox、ie或safari。文档特别说明：本地测试适用于调试与快速迭代（quick turn around）。

如果不指定--browser，gulpfile.js 会回退读取环境变量SELENIUM_BROWSER，再回退到默认值chrome。

本地测试的底层机制（结合源码）：

• gulpfile.js 的 test 任务会先通过 tools/run_test_server.js 启动一个基于 gulp-connect 的静态服务器（默认端口 8000，开启 livereload）；
• tools/setup_tests.js 会创建临时测试目录，建立lib、perf、testing、tests、dist等目录的符号链接，为没有自带 HTML 的*_test.js生成 HTML 测试页面，生成deps.js与测试索引index.html，并调用 SPAC 生成测试 schema 代码；
• tools/run_test.js 的runJsUnitTests通过 selenium-webdriver 启动浏览器，逐个访问http://localhost:8000/html/...下的测试 URL，由 tools/jsunit_test_runner.js 汇总结果；
• 最终控制台会输出形如N tests, M failure(s).的汇总，以及[ chrome ] JSUnit tests: PASSED/FAILED的着色结果。

方式二：Sauce Labs 云端测试

Sauce Labs 提供云端浏览器矩阵，适合在多种浏览器上做回归验证。步骤如下：

1. 在 Sauce Labs 注册账号；
2. 在本机运行Sauce Connect，打通本机与 Sauce 云之间的安全隧道；
3. 配置环境变量并逐个浏览器执行（文档给出的脚本，假设 Linux/Mac 与 bash，Windows 用户请按自身环境调整）：

export SAUCE_USERNAME=<your username> export SAUCE_ACCESS_KEY=<your sauce token> export SELENIUM_BROWSER=chrome gulp test --target=tests export SELENIUM_BROWSER=firefox gulp test --target=tests export SELENIUM_BROWSER=ie gulp test --target=tests export SELENIUM_BROWSER=safari gulp test --target=tests

用户名与 Sauce token 可在 Sauce Labs 账户设置中获取。从 tools/run_test.js 的实现可以看到选择逻辑：一旦检测到环境变量SAUCE_USERNAME已设置，WebDriver 构建就会自动切换为远端模式（getRemoteWebDriver），连接到http://<username>:<access_key>@ondemand.saucelabs.com:80/wd/hub；否则使用本地驱动。因此上述脚本只需要设置环境变量即可完成模式切换，无需修改任何命令。

Sauce 模式下的浏览器能力矩阵（来自getRemoteWebDriver的 switch 分支）也值得了解：chrome 对应 Linux 平台、firefox 对应 Linux、safari 对应 OS X 10.11 的 Safari 10.0、ie 对应 Windows 7 的 IE 11.0——这正是 Lovefield 声明的跨浏览器支持范围。

手动调试测试：gulp debug

在跑自动化之前，也可以手动在浏览器中观察测试行为。执行：

gulp debug

默认启动单元测试服务器并监听localhost:8000（可用--target=perf切换为性能测试服务器，用--port=<number>改端口）。然后用浏览器访问http://localhost:8000，页面会列出全部测试的索引。文档强烈建议为浏览器创建独立的测试 profile再访问，避免污染日常浏览数据。从 gulpfile.js 源码看，debug任务不会自动退出，需用Ctrl-C终止服务器。

提交贡献前的完整校验流程

先阅读贡献规则

动手之前，请先确认认可 CONTRIBUTING.md 中的规则（文档在 docs/dev_setup.md 中明确要求阅读，若不认可可止步于此）。结合 CONTRIBUTING.md 的内容，贡献流程还包括：签署 Google 个人贡献者许可协议（CLA）、通过 GitHub Pull Request 提交代码、所有提交（包括项目成员）均需代码评审。如果你的修改未通过下述全部校验，将被直接拒绝。

贡献前必须通过的命令序列

文档给出的完整校验脚本（假设 Linux/Mac，Windows 请自行调整）：

gulp build --target=lib --mode=opt gulp build --target=tests gulp lint gulp test --target=spac export SAUCE_USERNAME=<your username> export SAUCE_ACCESS_KEY=<your sauce token> export SELENIUM_BROWSER=chrome gulp test --target=tests export SELENIUM_BROWSER=firefox gulp test --target=tests export SELENIUM_BROWSER=ie gulp test --target=tests export SELENIUM_BROWSER=safari gulp test --target=tests

每一步的含义与背后的校验逻辑：

1. gulp build --target=lib --mode=opt：以高级优化模式构建库产物，验证源码能通过 Closure 编译器的全部严格检查（VERBOSE 警告级别 + 完整 jscomp_error 列表）；
2. gulp build --target=tests：编译全部测试文件，验证测试代码同样满足编译要求；
3. gulp lint：对perf/**/*.js、spac/**/*.js、src/**/*.js、tests/**/*.js、testing/**/*.js运行 gjslint（见 gulpfile.js）。文档特别提醒：Google JavaScript 风格被"无情地"严格执行，但 linter 无法覆盖所有检查项，因此在代码评审中你可能还会遇到额外的 lint 意见；
4. gulp test --target=spac：运行 SPAC 测试，验证代码生成器未被破坏。该任务通过 child_process 派生 spac/run_test.js，使用 Jasmine 执行spac/下所有*_test.js，并加载spac/testdata/中的 YAML 测试数据与spac/template/中的模板；
5. gulp test --target=tests（× 4 个浏览器）：在 Chrome、Firefox、IE、Safari 上跑完整单元测试矩阵。注意前四条export SELENIUM_BROWSER=...设定了每个浏览器目标，且测试命令本身不再带--browser参数——这是环境变量驱动的典型用法。

关于 Travis CI 的重要说明

仓库本身配置了 Travis CI（见 .travis.yml）：CI 使用 Node.js 12.16.3，通过SELENIUM_BROWSER环境变量矩阵（builder1-3、chrome、ie、safari、firefox）配合 Sauce Connect 在云端跑测试。但文档明确说明：出于安全考虑，外部贡献者的 Pull Request 不会触发 Travis CI 构建。因此你必须在本机完整运行上述脚本，否则 PR 将直接被拒。也就是说，本地跑通完整校验是贡献被接受的前提，不能指望 CI 替你兜底。

Markdown 文档规范

仓库内所有 Lovefield 文档均使用GitHub 风格 Markdown编写。开发者可使用任意顺手的 Markdown 编辑器或预览器（包括带预览的 IDE、命令行预览工具等）来撰写与校对文档。仓库中的文档入口（如 README.md、docs/spec_index.md、docs/dd_index.md）都通过相对路径互相链接，修改文档时请保持链接的相对路径有效。

常见问题与排查要点

结合源码，补充几个文档未展开、但实践中极易遇到的坑：

• Closure 编译失败且报错信息极长：在 Windows 原生 Command Prompt 下运行时几乎可以肯定是命令行长度限制所致，换用 TCC/LE 之类的命令行工具即可（这正是文档提示的初衷）。
• 本地测试找不到浏览器驱动：gulp test --target=tests报 WebDriver 相关错误时，优先检查对应浏览器驱动是否已下载并加入 PATH，或检查驱动版本与浏览器版本是否匹配。
• 意外连上了 Sauce Labs：一旦 shell 环境中残留SAUCE_USERNAME/SAUCE_ACCESS_KEY，gulp test会静默切换到云端模式（见 tools/run_test.js 的判断逻辑）。只想本地跑时，请先unset SAUCE_USERNAME。
• 构建太慢：gulp build --target=tests默认并行度 8，可设置CONCURRENT_BUILDER=16之类环境变量加速（见 tools/builder.js）。
• Firebase 相关测试：tests/backstore/下的 Firebase 测试需要额外的FIREBASE_URL与FIREBASE_TOKEN环境变量才可运行（见 tools/setup_tests.js 的注入逻辑），普通贡献者不必纠结于这部分。

小结

Lovefield 的开发环境搭建可以归纳为一条清晰的链路：装好 Java/Git/Node.js（Windows 换 TCC/LE）→npm update拉取依赖 →gulp build --target=lib --mode=opt用 Closure 严格校验并产出dist/lf.js→gulp test --target=tests --browser=<browser>本地快速验证，或通过SAUCE_USERNAME/SAUCE_ACCESS_KEY/SELENIUM_BROWSER三件套切换到 Sauce Labs 云端跑跨浏览器矩阵 → 贡献前按顺序跑完build(opt) → build(tests) → lint → test(spac) → test(tests)×4全套校验。由于外部 PR 不触发 Travis CI，本地跑通全套校验是贡献被接受的硬性前提；而 tools/builder.js、tools/run_test.js、tools/config.js 等源码则为你理解每一步"内部到底发生了什么"提供了完整的实现级参考。

• 关系型数据库
• 数据库
• 前端