跳至主要内容

贡献

你喜欢 WebdriverIO 并想帮助使其变得更好？太棒了！我们正在努力使这个过程尽可能简单和透明。我们可能还没有完全做到，但本指南将帮助你成为一名贡献者，并提供你做出第一次贡献所需的一切。如果缺少任何阻止你发送拉取请求的信息，请告诉我们。我们将这类问题视为真正的错误。

行为准则​

每个参与此项目的人，无论是作为用户还是贡献者，都必须遵守项目的行为准则。任何违反行为准则的行为都将被审查和调查，并将得到根据具体情况认为必要和适当的回应。项目团队有义务对事件报告人保密。有关具体执行政策的更多详细信息可能会单独发布。

寻找贡献方式​

该项目提供了多种贡献方式。如果你难以找到适合你的方式，请加入 WebdriverIO 在 Matrix 上的支持频道 并与维护者联系。不要害羞，他们随时准备提供帮助！

你可以通过以下方式参与

  • 贡献代码
  • 改进文档
  • 帮助我们翻译该项目到更多语言
  • 在Discord支持频道中回答问题并提供帮助
  • 创建教育内容（博客文章、教程、视频等）
  • 宣传该项目（例如，通过 Twitter）
  • 在使用 WebdriverIO 时发现错误时创建错误报告
  • 如果你在项目中缺少某些内容，请提出功能请求
  • 如果你想在经济上支持我们，请考虑向该项目捐款

该项目的维护人员尝试以一种可以让任何人都能够获得足够上下文开始工作的方式来组织所有问题。如果不是这种情况，请在问题线程中提及，以便问题创建者或维护者提供更多信息。

如果你想贡献代码，一个通用的良好第一步是查看所有带有标签需要帮助和/或适合新手的工单。如果这些工单没有分配给用户，则可以随意领取。如果你发现了一些你感兴趣的东西，请确保在问题线程中告知我们你打算处理它。

通常，问题需要一些关于问题的上下文，这使得很难了解需要做什么。根据你使用/参与该项目的经验，此上下文可能会丢失。通常，从围绕缺少文档的任务开始或仅仅增加代码某些部分的测试覆盖率会有所帮助。一段时间后，你将更加熟悉代码库，这将使你能够承担更困难的任务。

如果你找不到适合你的东西，请查看项目路线图，看看是否有你感兴趣的东西。最后，你还可以始终在Discord支持频道中联系维护者。他们负责为你找到任务。

报告新问题​

当打开一个新问题时，请务必填写问题模板。此步骤非常重要！如果不这样做，可能会导致你的问题无法及时得到处理。如果发生这种情况，请不要为此感到难过，并在收集完模板所需的所有信息后随时打开一个新问题。

  • 一个问题，一个错误：请每个问题报告一个错误。
  • 提供复现步骤：列出复现该问题所需的所有步骤。阅读你的错误报告的人应该能够按照这些步骤轻松复现你的问题。

提供可复现的示例​

可复现的示例是一个简单、独立的脚本或程序，用于演示你遇到的问题或错误。目的是让其他人能够轻松有效地重现问题。

创建可复现示例的步骤

  1. 隔离问题
  • 将你的代码缩减到仍然可以复现问题的最小数量。
  • 删除任何与问题无关的非必要代码或依赖项。
  1. 确保其他人可以运行你的示例并复现问题
  • 它不应该需要任何非标准设置，除非绝对必要，例如，删除对 CI 供应商等特殊软件或服务的任何需求。
  • 记录执行可复现示例所需的步骤
  1. 共享项目
  • 创建一个新的公共 GitHub 存储库并将你的可复现示例推送到其中。
  • 在问题中共享存储库的链接。
  • 记录你观察到的行为和你期望的行为

注意：如果你无法提供可复现的示例，我们很遗憾不得不关闭该问题。

安全漏洞​

请参阅SECURITY.md。

流程图​

流程图提供了 WebdriverIO 生态系统的高级概述以及不同软件包如何相互交互。

WDIO 命令 - 解释了 wdio 配置、安装和 repl 命令的工作流程。

创建本地工作进程 - 解释了 @wdio/cli、@wdio/local-runner 和 @wdio/runner 软件包之间的交互以及如何创建工作进程。

测试执行 - 本地运行器工作进程中测试运行方式的概述。

高级概述 - 流程图提供了 WebdriverIO 生态系统如何与核心软件包交互的高级概述。

提出更改​

我们很乐意接受你提出的任何改进框架可用性的想法。如果你对新功能有任何想法，请先提出功能请求，以便从维护者团队那里获得反馈。这让我们在你在上面投入大量精力之前就能就你的提议达成一致。

如果你只是修复了一个错误，可以直接提交拉取请求，但我们仍然建议你提交一个问题来详细说明你修复的内容。这在以下情况下很有帮助：我们不接受该特定修复，但希望跟踪该问题。

使用代码​

如果你对代码进行了任何更改，你希望快速测试它以查看它们是否符合预期。在 WebdriverIO 中有几种方法可以做到这一点。首先，你可以将单个子包链接到自己的项目中，以查看你所做的更改是否产生了预期的效果。

测试 WebdriverIO 中的更改的另一种方法是使用其示例目录或运行其冒烟测试套件。示例目录是一组使用 WebdriverIO 的各种方式的示例脚本。在这里，您需要运行一个浏览器驱动程序才能运行这些脚本。使用冒烟测试套件，您可以在预定义的执行场景中运行 WebdriverIO 的各种版本。所有这些场景都在我们的WebDriver Mock Service中定义，该服务通过使用预定义的响应存根端点来模拟浏览器驱动程序。这是一种在无需进行任何设置的情况下快速运行 WebdriverIO 套件的好方法。

发起 Pull Request​

一旦您实施了修复或完成了功能实现，您就可以发起一个 pull request。您的更改需要推送到您的 WebdriverIO fork 中。在 GitHub UI 中，您应该会看到一个弹出按钮，允许您向主存储库发起 PR。

我们已经为您提供了要填写的模板。这里没有多少规则需要遵循。只需尝试尽可能详细地解释您的更改即可。确保您为您的更改编写了足够的单元测试，否则代码覆盖率检查将导致构建失败。

与许多开源项目一样，我们要求您签署一份**CLA**，即贡献者许可协议，该协议确保对项目的所有贡献均根据项目的相应开源许可证（即 MIT）获得许可。它规范了您向我们（作为 OpenJS 基金会）提供代码更改的法律影响。

WebdriverIO 维护者将尽快审查您的 pull request。然后，他们将批准并合并您的更改、请求修改或关闭并提供说明。

项目设置​

您可以立即使用预先设置的 Gitpod 环境开始处理代码（在此处阅读更多信息此处）。如果您想在本地开发项目，请按照此分步指南进行操作

  • Fork 项目。

  • 将项目克隆到您计算机上的某个位置

    $ git clone [email protected]:<your-username>/webdriverio.git

  • 在 Windows 上，您需要将 git config core.symlinks 设置为 true，因为我们目前已将一些符号链接提交到我们的存储库中以进行类型定义。

    • 要全局设置 git config：git config --global --add core.symlinks true
    • 在克隆存储库时本地设置 git config：git -c core.symlinks=true clone [email protected]:<your-username>/webdriverio.git。

    有关更多信息，请参阅https://github.com/git-for-windows/git/wiki/Symbolic-Links

  • 如果您需要更新您的 fork，可以按照此处的步骤进行操作

  • 切换到最新的 Node LTS（您应该能够使用旧版/新版 Node，但我们建议使用 v20 LTS，以便所有开发人员都在同一页面上）或 .nvmrc 中指示的版本。我们建议使用nvm在 Node.js 版本之间切换。

  • 设置项目：首先确保您已安装正确的 Node.js 版本。您可以在项目根目录中的 .nvmrc 中找到当前定义的开发版本。处理多个 Node.js 版本的最简单方法是使用NVM。设置 NVM 后，使用它来安装所需的 Node.js 版本

    $ nvm install

    接下来，全局安装pnpm

    $ npm install -g pnpm

    最后，通过以下方式设置项目

    $ pnpm install
    $ pnpm run setup

    第二个命令执行两件事

    • 通过 pnpm run clean 清理（可能的）现有构建工件

      如果您已编译代码，则此命令也将删除它们以及所有子包的依赖项。

    • 编译项目 pnpm run compile:all

      作为最后一步，您需要构建所有子包以解决内部依赖项。WebdriverIO 使用@wdio/compiler，这是一个使用 Esbuild 编译项目的内部包。

  • 运行测试以确保一切设置正确

    # run the complete unit test suite
    $ pnpm test

    # run test for a specific sub project (e.g. webdriver)
    $ npx vitest ./packages/webdriver/tests

    它应该会给您一个通过的结果。现在您可以继续设置您的开发环境并开始编写一些代码。如果测试未通过，请创建一个问题并提供错误日志。

处理包​

如果您开始对特定包进行更改，请确保监听文件更改并在每次保存时都转换代码。要对所有包执行此操作，请运行

pnpm run dev

如果您只处理一个包，您可以只监视该包，方法是调用

# e.g. `$ pnpm run dev wdio-runner`
$ pnpm run dev <package-name>

在开发单个包时，最好以监视模式运行 vitest，以查看更改是否会影响任何测试

npx vitest ./packages/<package-name>/tests

TypeScript 定义​

WebdriverIO 使用 TypeScript 来确保代码是静态类型的，并避免常见的误用错误。如果您不熟悉 TypeScript，请查看这些很棒的基本资源以开始使用它。

WebdriverIO 为使用 TypeScript 的项目提供了自己的类型定义。鉴于大量命令，使生成这些类型的过程**不**自动化将使其难以维护。但是，在某些特殊情况下需要手动操作。

所有类型定义都是由 TypeScript 编译器生成的。有一些必要的包

  • @wdio/types 包提供所有基于代码使用的通用类型，例如 Capabilities、Options 等。如果您需要跨多个包的类型定义，最好在此处定义它们
  • @wdio/protocol 包定义所有协议命令、其函数参数和返回类型
  • 所有其他类型都应在使用它们的包中定义，在这里我们倾向于在 types.ts 文件中定义通用类型

协议类型是在 @wdio/compiler 构建命令的一部分中生成的，并且是generate-types插件的一部分。

测试更改​

对于 WebdriverIO 代码库的开发，您可以使用维护者在示例目录中创建的示例文件。它们涵盖了各种用例，并且已设置好以便它们可以使用存储库中的代码运行。假设您对 WDIO 测试运行器进行了更改，并且想查看它们是否已正确应用，您只需通过调用以下命令运行测试运行器示例：

cd ./examples/wdio
$ pnpm run test:mocha

这将使用 Mochajs 运行一个简单的测试套件。其他框架、自定义服务和报告程序以及使用 devtools 协议作为自动化引擎也有类似的示例。如果您添加的示例有助于测试您正在处理的功能，请随时添加。

测试管道​

当提交 PR 时，WebdriverIO 会运行以下检查

  • 依赖项检查我们自动检查每个子包是否已安装其 package.json 中的所有依赖项。您可以通过调用以下命令手动触发此检查： 
    $ pnpm run test:depcheck
  • ESLint一个通用的 ESLint 测试，用于对齐代码样式并在早期检测语法错误。您可以通过调用以下命令手动触发此检查： 
    $ pnpm run test:eslint
  • TypeScript 定义测试由于我们生成了类型定义，因此我们希望谨慎地确保生成的定义确实按预期定义了接口。有关详细信息，请参阅测试类型定义。您可以通过调用以下命令手动触发此检查： 
    $ pnpm run test:typings
  • 单元测试与每个项目一样，我们对代码进行单元测试，并确保新补丁已得到正确测试。覆盖率阈值非常高，因此请确保您的更改涵盖了所有必要的代码路径。我们在这里使用Vitest作为单元测试框架。您可以通过调用以下命令手动触发此检查： 
    $ pnpm run test:unit
  • 冒烟测试虽然单元测试已经涵盖了许多情况，但我们除了运行单元测试之外，还运行冒烟测试来模拟难以在单元级别进行测试的测试场景，因为它们包含在单元测试中被存根的依赖项的功能。例如，此类场景是正确的测试重试或故障处理。冒烟测试运行实际的 e2e 测试，其中驱动程序被存根（通过@wdio/smoke-test-service）以返回伪造的结果。您可以通过调用以下命令手动触发此检查： 
    $ pnpm run test:smoke
  • e2e 测试最后但并非最不重要的是，我们使用真实的无头浏览器运行实际的 e2e 测试，以确保我们可以在所有支持的变体中启动测试，并且端到端的某些服务可以正常工作。您可以通过调用以下命令手动触发此检查： 
    $ pnpm run test:e2e

单元测试​

该项目试图保持较高的测试覆盖率，以确保对代码的更改是有意且经过深思熟虑的。因此，“通常”每个代码文件都有一个单元测试文件，位于测试目录中。例如，以下内容的单元测试：

packages/webdriverio/src/commands/element/getCSSProperty.ts

位于

packages/webdriverio/tests/commands/element/getCSSProperty.test.ts

如果不是这种情况，则该文件的功能可能会通过其他文件进行测试。我们建议为代码库中编写的每个新函数编写单元测试。我们建议使用Vitests 模拟功能模拟对其他包或模块的每个依赖项。

在开发过程中，专注于运行单个文件的单元测试而不是整个代码库是有意义的。例如，如果您正在处理 getCSSProperty 命令，那么只运行该特定命令的单元测试是有意义的，方法是调用：

npx vitest packages/webdriverio/tests/commands/element/getCSSProperty.test.ts

使用 --watch 标志，只要您更改文件中的任何内容，单元测试就会重新运行。

使用冒烟测试运行 e2e 体验​

WebdriverIO 维护着一组冒烟测试套件，允许表示用户运行 wdio 测试运行器的完整 e2e 体验。它的设置方式使其不需要实际的浏览器驱动程序，因为所有请求都使用@wdio/webdriver-mock-service进行模拟。这为您提供了一个机会，可以在不设置浏览器驱动程序和测试页面的情况下运行 wdio 测试套件。您可以通过以下方式运行所有冒烟测试：

pnpm run test:smoke

有一个 smoke.runner.js 文件触发所有测试。它包含多个在不同环境（例如 Mocha、Jasmine 和 Cucumber）中运行的 测试套件 定义。您可以通过调用以下命令运行特定的测试套件，例如：

pnpm run test:smoke mochaTestrunner

每个测试套件都是一个函数，使用 launch 辅助方法以编程方式触发 wdio 测试运行器。您只需要传入配置文件的路径以及您想覆盖配置的内容。大多数冒烟测试使用 通用配置文件 并覆盖特定于其用例的属性。

如果您测试自定义 WebDriver 命令，则可以在 @wdio/webdriver-mock-service 中定义您自己的模拟响应场景。

测试类型定义​

为了确保我们不会意外更改类型并导致用户的测试中断，我们运行一些简单的 TypeScript 检查。您可以通过运行以下命令运行所有类型定义测试：

pnpm run test:typings

这将运行 WebdriverIO 提供的所有类型定义的所有测试。这些测试只是检查 TypeScript 是否可以根据生成的类型定义编译它们。所有类型检查都位于 /webdriverio/tests/typings 中。如果您扩展 WebdriverIO 命令或其他类型定义的接口，请确保已在这些文件中使用它。该目录包含 WebdriverIO 异步用法的测试。

例如，要测试 touchActions 属性，我们在 /tests/typings/webdriverio/async.ts 中对其进行了测试

// touchAction
const ele = await $('')
const touchAction: WebdriverIO.TouchAction = {
    action: "longPress",
    element: await $(''),
    ms: 0,
    x: 0,
    y: 0
}
await ele.touchAction(touchAction)
await browser.touchAction(touchAction)

以及在 /tests/typings/sync/sync.ts 中

const ele = $('')
const touchAction: WebdriverIO.TouchAction = {
    action: "longPress",
    element: $(''),
    ms: 0,
    x: 0,
    y: 0
}
ele.touchAction(touchAction)
browser.touchAction(touchAction)

文档​

此存储库包含设置、构建和部署 WebdriverIO 文档页面所需的一切。我们使用 Docusaurus (v2) 生成页面。内容基于以下内容生成

  • 来自 docs 目录 的 markdown 文件中的指南页面
  • 来自此存储库中这些包的 readme 文件的服务和报告程序文档
  • 来自第三方插件（在 这些 JSON 文件 中定义）的服务和报告程序文档，这些插件从 GitHub 下载并解析
  • 来自 @wdio/protocols 包的协议 API
  • 从单个命令的 JSDoc 注释中解析出的 WebdriverIO API（例如，execute 命令）

文档更改需要在以下位置之一进行。请注意，例如配置文件的更改必须在多个地方更新，因为配置文件在此存储库中广泛存在（作为示例或测试文件）。解决此问题的一种好方法是查找特定配置文件字符串的所有出现情况，并在所有查找结果中更新更改。

在本地部署文档​

在您 设置项目 后，您可以进入 website 目录设置文档页面并在本地机器上运行它。为此，请运行

cd website
$ pnpm install
$ pnpm start

这将设置在 localhost:3000 上运行页面所需的一切。如果您需要在不同的主机或端口上运行，请将它们作为附加参数传递给 pnpm start，例如 -- --host 0.0.0.0。

您现在可以修改 /website/docs 文件的内容，以及更改样式和模板。页面将自动更新。如果您在其他地方添加文档，则必须重新运行 pnpm start 脚本以重新生成文档。

在生产环境中部署文档​

每次将新版本推送到 GitHub 时，都需要构建 WebdriverIO 文档并重新部署到项目的 S3 存储桶。该过程在 GitHub Actions 管道 中定义。您（作为维护者）需要做的就是触发管道。其余部分由工作流处理。

创建新包​

所有 WebdriverIO 子包都需要一定的结构才能在 wdio 生态系统中工作。为了简化创建新子包的过程，我们构建了一个 NPM 脚本，它为您完成所有样板工作。只需运行

pnpm run create

它会询问您新包的类型和名称，并为您创建所有文件。

向后移植错误修复​

从 v6 开始，WebdriverIO 团队尝试向后移植所有与旧版本仍向后兼容的功能。该团队尝试每年发布一个新的主要版本（通常在 12 月/1 月左右）。使用新的主要版本更新（例如 v7），我们继续维护最后一个版本（例如 v6）并弃用以前维护的版本（例如 v5、v4 及更低版本）。因此，该团队承诺始终支持 2 个主要版本。

作为分类者​

如果更改可以应用于维护的（以前的）版本，则每个对 PR 进行分类或审查的人员都应将其标记为 backport-requested。通常，每个不会对先前版本造成重大更改的 PR 都应被视为移植回。如果更改依赖于当前版本中才有的功能或代码片段，那么如果您觉得可以进行必要的调整，则仍然可以考虑进行向后移植。也就是说，如果您觉得时间投入和复杂度过高，请不要强迫自己进行代码向后移植。向后移植功能是任何贡献者都可以做出的合理的贡献。

作为合并者​

一旦带有 backport-requested 标签的 PR 合并，您将负责将补丁向后移植到旧版本。为此，请从 GitHub 拉取最新代码

git pull
$ git fetch --all
$ git checkout v6

在您开始之前，请将 GITHUB_AUTH 令牌导出到您的环境中，以允许执行脚本获取有关拉取请求的数据并设置正确的标签。转到您的 个人访问令牌 设置页面并生成这样的令牌，其中仅启用了 public_repo 字段。然后将其导出到您的环境中并运行向后移植脚本。它获取与标记为 backport-requested 的 PR 相关的全部提交，并将它们 cherry-pick 到维护分支中。通过交互式控制台，您可以有机会再次审查 PR 以及您是否要向后移植它。要启动该过程，只需执行

pnpm run backport

如果在此过程中 cherry-pick 失败，您可以随时中止并手动进行故障排除。如果您无法解决问题，请在存储库中创建一个问题，并包含该 PR 的作者。成功向后移植两个 PR 将如下所示

$ pnpm run backport

> webdriverio-monorepo@ backport /path/to/webdriverio/webdriverio
> node ./scripts/backport.js

? You want to backport "Backporting Test PR" by christian-bromann?
(See PR https://github.com/webdriverio/webdriverio/pull/4890) Yes
Backporting sha 264b7bc49dfc3fe8f1ed8b58d681ce562aaf1544 from v6 to v5
[cb-backport-process e47c5527] Backporting Test PR (#4890)
 Author: Christian Bromann <[email protected]>
 Date: Mon Dec 16 14:54:02 2019 +0100
 1 file changed, 2 insertions(+)
? You want to backport "Second backport test" by christian-bromann?
(See PR https://github.com/webdriverio/webdriverio/pull/4891) Yes
Backporting sha 77dc52fdb86c51242b92f299998d2904004cb347 from v6 to v5
[cb-backport-process 35a3ad41] Second backport test (#4891)
 Author: Christian Bromann <[email protected]>
 Date: Mon Dec 16 16:01:46 2019 +0100
 1 file changed, 2 deletions(-)

Successfully backported 2 PRs 👏!
Please now push them to `v6` and make a new v6.x release!

对于任何问题，您始终可以联系 Matrix 上的 webdriverio/ProjectCommitters 频道。

发布新版本​

软件包发布使用 Lerna 的发布功能作为 GitHub 工作流，并且仅由 技术指导委员会 执行。您需要做的就是转到 Manual NPM Publish 工作流并触发新的运行。根据 语义版本控制 选择适当的版本升级。为了帮助您选择正确的发布类型，以下是一些一般准则

  • **重大更改**：切勿自行进行此操作！主要版本始终是所有 TSC 成员之间的协作工作。它需要他们所有人的共识。
  • **次要版本**：如果向其中一个包添加了新的面向用户的功能，则始终需要次要版本。例如，如果向 WebdriverIO 添加了一个命令，或者如果某个服务提供了一种新的集成形式，则进行次要版本升级将是合适的。但是，如果像 @wdio/local-runner 这样的内部包公开了仅在内部使用的新的接口，我们可以将其视为补丁版本。
  • **修补程序版本**：每次修复错误、更新文档（包括 TypeScript 定义）或改进现有功能时，我们都应该进行修补程序版本发布。

如果您不确定要选择哪种发布类型，请在 webdriverio/TSC Matrix 频道中联系我们。通过设置 NPM 标签，您还可以发布当前版本（例如，使用 next 标签）以在将其推广到所有用户之前测试更改。

研讨会​

作为 OpenJS World 2020 协作者峰会 的一部分，WebdriverIO 团队举办了关于“为 WebdriverIO 做贡献”的研讨会，可以帮助您熟悉代码库和项目。观看

此存储库 包含 WebdriverIO 项目的所有必要包（不包括第三方开发人员贡献的插件）。这些包在其 README 文件（/packages/<package>/README.md）中具有单独的描述，提供有关其范围和职责的信息。即使构建命令可能因包而异，使用它们的方式也是相同的。此项目使用 Lerna 在此单体存储库中管理其所有子项目。

欢迎！我怎样才能帮助您？

WebdriverIO AI Copilot