WebdriverIO 交互式文档实践从代码示例抽离、CI 测试到 Runme 一键运行【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverioWebdriverIO 是一个功能丰富且生态庞大的 Node.js 浏览器与移动端自动化测试框架其官方文档本仓库 website 目录即该文档的源码承担着向开发者传递海量 API 与特性的重任。本文将剖析 WebdriverIO 团队于 2023 年提出的“交互式、可测试的文档”方案把文档中的代码示例抽离到独立仓库、通过 Docusaurus 插件按行引用回填、再用 CI/CD 与 Dependabot 保证示例始终可运行、最后借助 Runme 让读者一键在 VS Code 中执行。读完你将掌握一套可复制的“示例即代码、文档即测试”工程化方法论并能在自己的文档项目中落地。为什么代码示例会沦为文档的“短板”代码示例常被誉为“一图胜千言”WebdriverIO 框架提供大量可供把玩的功能官方文档的核心目标正是把这些特性讲清楚、并让你理解如何在项目中落地而这一目标主要靠示例代码来承载。社区里很多项目都会在文档中嵌入代码示例其中不少还做到了“可交互”例如新的 React 官方文档允许读者实时摆弄代码svelte.dev 则提供了带在线示例的 playground。但这类“写在 Markdown 里的示例”往往面临四个通病示例是编造的常常不反映真实情况人非圣贤示例里包含错误接口一变示例迅速过时难以直接迁移到读者自己的项目中。为此WebdriverIO 团队开始在文档站上推行一系列改动核心思路可以概括为把示例从文档中抽离出去当作真正的代码来维护、测试与交付。效果如下图所示文档中的示例现在带上了两个按钮一个用于直接运行Run一个用于在仓库中查看源码https://github.com/webdriverio/example-recipes/blob/main/queryElements/singleElements.js#L9-L10第一步把示例从文档抽离进独立仓库方案的第一步是把所有代码示例从文档页面中删除迁移到独立的webdriverio/example-recipes仓库。这样一来示例不再是一堆散落在 Markdown 里的孤立文本而是可以被当作普通代码来对待可以为其搭建 CI/CD、配置自动化依赖更新等基础设施从而确保质量与正确性。在该仓库中每个示例都自包含在各自的独立目录中互不依赖、结构极简同时在 package.json 的 NPM scripts 里维护了一长串脚本清单让每个示例都能用一条命令单独运行。这种“一个目录一个示例 一个脚本一条命令”的组织方式天然降低了维护与定位问题的成本。用 Docusaurus 插件把示例“引”回文档抽离之后的关键问题是如何把示例代码再嵌入到网站页面里答案是使用一个面向 Docusaurus 的插件docusaurus-theme-github-codeblock它能够根据一个简单的 GitHub 引用链接把代码下载回来。于是Markdown 文件里不再直接写代码而是只写一行引用地址例如https://github.com/webdriverio/example-recipes/blob/main/setup/testrunner.js#L5-L8useHTTPS标识该引用走 HTTPS 协议获取源码#L5-L8则限定只展示该文件的第 5 到 8 行。插件会下载对应文件仅渲染你指定的代码行区间最终呈现在页面上的效果就是上方的这段代码块。即便你使用的静态文档构建工具不是 Docusaurus大概率也能找到功能相似的插件来复刻这套引用机制。第二步用 CI/CD 让示例“跑”起来示例抽离进独立仓库后最大的红利是可以借助 CI/CD定期执行全部示例。一个简单的 GitHub Actions workflow 即可触发示例的运行并在任意示例报错时让流水线失败name: Test on: [push, pull_request] jobs: test: runs-on: ubuntu-latest strategy: matrix: exampleDir: - click # more example directories here # ... - api/webdriver steps: - name: Checkout uses: actions/checkoutv3 - uses: actions/setup-nodev3 with: node-version: 18 - name: Install run: npm install - name: Test run: npm run ${{ matrix.exampleDir }} working-directory: ${{ matrix.exampleDir }}这个 workflow 的设计要点在于matrix策略把每个示例目录作为一个矩阵维度列出流水线会对每个目录分别执行npm install与npm run exampleDir。只要示例目录持续增长矩阵项也持续追加任何回归都会被流水线当场拦下。示例本身就是要跑通的测试大多数示例其实就是普通的 WebdriverIO 测试文件和真实测试一样带有断言逻辑。比如下面这个演示“命令链式查找元素”的示例本质就是一个带expect断言的测试用例it(should get the text of a menu link, async () { const menu$ await $(#menu) // or browser.$(#menu) console.log(await menu$.$$(li)[2].$(a).getText()) // outputs: API await expect(menu$.$$(li)[2].$(a)).toHaveText(API) })由于插件支持引用指定代码行文档中可以只展示L9-L10这种“教学重心所在”的关键片段把断言、清理等测试细节在渲染时裁剪掉让读者聚焦于“怎么用”而不是“怎么测”https://github.com/webdriverio/example-recipes/blob/main/queryElements/singleElements.js#L9-L10第三步让示例永不过时CI/CD 基础设施还带来了第二个红利——保证示例持续跟上框架版本迭代。因为 WebdriverIO 的代码托管在 GitHub 上团队配置了Dependabot 每周自动更新示例仓库的全部依赖另配一个自动合并 workflowupdate workflow来把这些依赖更新直接合入主干。只有当更新引发了测试失败、造成实际问题时维护者才需要人工介入处理。这套自动化闭环意义重大它确保WebdriverIO 自身的每次改动都不会悄悄弄坏文档里引用的示例形成了一条高效的反馈回路每当发布新版本时团队也因此对“示例未受影响”充满信心。你可以在这份博客对应的 scripts/templates/template.eta 中看到 API 文档生成模板如何把exampleReferences渲染成reference useHTTPS形式的代码块从源码层面印证了这套引用机制的普遍使用。第四步让示例“一键可达”最后为了让每个示例触手可及WebdriverIO 文档站引入了 VS Code 扩展Runme读者只需点击文档示例上的Run Example运行示例按钮即可把示例仓库克隆到本地并打开。如果你还没安装 Runme可以到 VS Code Marketplace 搜索stateful.runme安装或直接在 VS Code 中搜索大量调研表明 VS Code 是当下全球开发者最主流的 IDE而Run Example按钮本质上是一个携带自定义vscode://协议的链接点击后会弹窗请求你授权在 VS Code 中打开扩展会从链接信息中解析出需要 clone 哪个仓库、打开哪个 Markdown 文件如果扩展尚未安装在获得你同意的情况下它还会自动替你完成安装。仓库克隆完成后Runme 会为该示例打开一份专属README.md以交互式 notebook 的形式逐步讲解并引导你走完整个示例你可以在 VS Code 终端里安全地逐格执行代码单元从环境搭建到运行示例全程只需点击无需再打开任何额外应用。没有安装 VS Code 的用户也完全不受影响仍可手动 clone 仓库、按 README 逐个运行示例。这套机制在 WebdriverIO 官方文档中得到了广泛应用。例如在 website/docs/ComponentTesting.md 中代码块通过runmeRepositorygitgithub.com:webdriverio/example-recipes.git与runmeFileToOpencomponent-testing%2FREADME.md指定了 Runme 要拉取的仓库与要打开的 READMEwebsite/docs/GettingStarted.md 和 website/docs/CustomMatchers.md 同样大量使用reference useHTTPS引用形式。这些行为都由文档站的 Docusaurus 配置驱动在 website/docusaurus.config.ts 中通过codeblock主题配置开启showRunmeLink并设置按钮文案runmeLinkLabel: Run Example并在 website/docusaurus.config.ts 的themes数组中注册docusaurus-theme-github-codeblock插件。参与共建为示例生态添砖加瓦WebdriverIO 拥有大量示例以及海量的命令与 API 等待被文档化——这对贡献者而言是绝佳的参与机会。你可以通过以下两种方式参与共建向webdriverio/example-recipes仓库补充更多示例在 WebdriverIO 官方文档中引用已有示例即在 Markdown 里按上文格式写入reference useHTTPS引用块。如有任何疑问或反馈也可以在 webdriverio/webdriverio 仓库中提出 issue。对于需要特定运行时环境而不仅仅是浏览器的框架——例如依赖 Node.js 的 WebdriverIO 而言这套方案提供了一种相当优雅的、交互且简单的示例交付方式。如果你也是框架作者、并且用 Docusaurus 构建文档完全可以借鉴甚至直接复制这套做法——它是开源的、免费的。【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
WebdriverIO 交互式文档实践：从代码示例抽离、CI 测试到 Runme 一键运行
WebdriverIO 交互式文档实践从代码示例抽离、CI 测试到 Runme 一键运行【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverioWebdriverIO 是一个功能丰富且生态庞大的 Node.js 浏览器与移动端自动化测试框架其官方文档本仓库 website 目录即该文档的源码承担着向开发者传递海量 API 与特性的重任。本文将剖析 WebdriverIO 团队于 2023 年提出的“交互式、可测试的文档”方案把文档中的代码示例抽离到独立仓库、通过 Docusaurus 插件按行引用回填、再用 CI/CD 与 Dependabot 保证示例始终可运行、最后借助 Runme 让读者一键在 VS Code 中执行。读完你将掌握一套可复制的“示例即代码、文档即测试”工程化方法论并能在自己的文档项目中落地。为什么代码示例会沦为文档的“短板”代码示例常被誉为“一图胜千言”WebdriverIO 框架提供大量可供把玩的功能官方文档的核心目标正是把这些特性讲清楚、并让你理解如何在项目中落地而这一目标主要靠示例代码来承载。社区里很多项目都会在文档中嵌入代码示例其中不少还做到了“可交互”例如新的 React 官方文档允许读者实时摆弄代码svelte.dev 则提供了带在线示例的 playground。但这类“写在 Markdown 里的示例”往往面临四个通病示例是编造的常常不反映真实情况人非圣贤示例里包含错误接口一变示例迅速过时难以直接迁移到读者自己的项目中。为此WebdriverIO 团队开始在文档站上推行一系列改动核心思路可以概括为把示例从文档中抽离出去当作真正的代码来维护、测试与交付。效果如下图所示文档中的示例现在带上了两个按钮一个用于直接运行Run一个用于在仓库中查看源码https://github.com/webdriverio/example-recipes/blob/main/queryElements/singleElements.js#L9-L10第一步把示例从文档抽离进独立仓库方案的第一步是把所有代码示例从文档页面中删除迁移到独立的webdriverio/example-recipes仓库。这样一来示例不再是一堆散落在 Markdown 里的孤立文本而是可以被当作普通代码来对待可以为其搭建 CI/CD、配置自动化依赖更新等基础设施从而确保质量与正确性。在该仓库中每个示例都自包含在各自的独立目录中互不依赖、结构极简同时在 package.json 的 NPM scripts 里维护了一长串脚本清单让每个示例都能用一条命令单独运行。这种“一个目录一个示例 一个脚本一条命令”的组织方式天然降低了维护与定位问题的成本。用 Docusaurus 插件把示例“引”回文档抽离之后的关键问题是如何把示例代码再嵌入到网站页面里答案是使用一个面向 Docusaurus 的插件docusaurus-theme-github-codeblock它能够根据一个简单的 GitHub 引用链接把代码下载回来。于是Markdown 文件里不再直接写代码而是只写一行引用地址例如https://github.com/webdriverio/example-recipes/blob/main/setup/testrunner.js#L5-L8useHTTPS标识该引用走 HTTPS 协议获取源码#L5-L8则限定只展示该文件的第 5 到 8 行。插件会下载对应文件仅渲染你指定的代码行区间最终呈现在页面上的效果就是上方的这段代码块。即便你使用的静态文档构建工具不是 Docusaurus大概率也能找到功能相似的插件来复刻这套引用机制。第二步用 CI/CD 让示例“跑”起来示例抽离进独立仓库后最大的红利是可以借助 CI/CD定期执行全部示例。一个简单的 GitHub Actions workflow 即可触发示例的运行并在任意示例报错时让流水线失败name: Test on: [push, pull_request] jobs: test: runs-on: ubuntu-latest strategy: matrix: exampleDir: - click # more example directories here # ... - api/webdriver steps: - name: Checkout uses: actions/checkoutv3 - uses: actions/setup-nodev3 with: node-version: 18 - name: Install run: npm install - name: Test run: npm run ${{ matrix.exampleDir }} working-directory: ${{ matrix.exampleDir }}这个 workflow 的设计要点在于matrix策略把每个示例目录作为一个矩阵维度列出流水线会对每个目录分别执行npm install与npm run exampleDir。只要示例目录持续增长矩阵项也持续追加任何回归都会被流水线当场拦下。示例本身就是要跑通的测试大多数示例其实就是普通的 WebdriverIO 测试文件和真实测试一样带有断言逻辑。比如下面这个演示“命令链式查找元素”的示例本质就是一个带expect断言的测试用例it(should get the text of a menu link, async () { const menu$ await $(#menu) // or browser.$(#menu) console.log(await menu$.$$(li)[2].$(a).getText()) // outputs: API await expect(menu$.$$(li)[2].$(a)).toHaveText(API) })由于插件支持引用指定代码行文档中可以只展示L9-L10这种“教学重心所在”的关键片段把断言、清理等测试细节在渲染时裁剪掉让读者聚焦于“怎么用”而不是“怎么测”https://github.com/webdriverio/example-recipes/blob/main/queryElements/singleElements.js#L9-L10第三步让示例永不过时CI/CD 基础设施还带来了第二个红利——保证示例持续跟上框架版本迭代。因为 WebdriverIO 的代码托管在 GitHub 上团队配置了Dependabot 每周自动更新示例仓库的全部依赖另配一个自动合并 workflowupdate workflow来把这些依赖更新直接合入主干。只有当更新引发了测试失败、造成实际问题时维护者才需要人工介入处理。这套自动化闭环意义重大它确保WebdriverIO 自身的每次改动都不会悄悄弄坏文档里引用的示例形成了一条高效的反馈回路每当发布新版本时团队也因此对“示例未受影响”充满信心。你可以在这份博客对应的 scripts/templates/template.eta 中看到 API 文档生成模板如何把exampleReferences渲染成reference useHTTPS形式的代码块从源码层面印证了这套引用机制的普遍使用。第四步让示例“一键可达”最后为了让每个示例触手可及WebdriverIO 文档站引入了 VS Code 扩展Runme读者只需点击文档示例上的Run Example运行示例按钮即可把示例仓库克隆到本地并打开。如果你还没安装 Runme可以到 VS Code Marketplace 搜索stateful.runme安装或直接在 VS Code 中搜索大量调研表明 VS Code 是当下全球开发者最主流的 IDE而Run Example按钮本质上是一个携带自定义vscode://协议的链接点击后会弹窗请求你授权在 VS Code 中打开扩展会从链接信息中解析出需要 clone 哪个仓库、打开哪个 Markdown 文件如果扩展尚未安装在获得你同意的情况下它还会自动替你完成安装。仓库克隆完成后Runme 会为该示例打开一份专属README.md以交互式 notebook 的形式逐步讲解并引导你走完整个示例你可以在 VS Code 终端里安全地逐格执行代码单元从环境搭建到运行示例全程只需点击无需再打开任何额外应用。没有安装 VS Code 的用户也完全不受影响仍可手动 clone 仓库、按 README 逐个运行示例。这套机制在 WebdriverIO 官方文档中得到了广泛应用。例如在 website/docs/ComponentTesting.md 中代码块通过runmeRepositorygitgithub.com:webdriverio/example-recipes.git与runmeFileToOpencomponent-testing%2FREADME.md指定了 Runme 要拉取的仓库与要打开的 READMEwebsite/docs/GettingStarted.md 和 website/docs/CustomMatchers.md 同样大量使用reference useHTTPS引用形式。这些行为都由文档站的 Docusaurus 配置驱动在 website/docusaurus.config.ts 中通过codeblock主题配置开启showRunmeLink并设置按钮文案runmeLinkLabel: Run Example并在 website/docusaurus.config.ts 的themes数组中注册docusaurus-theme-github-codeblock插件。参与共建为示例生态添砖加瓦WebdriverIO 拥有大量示例以及海量的命令与 API 等待被文档化——这对贡献者而言是绝佳的参与机会。你可以通过以下两种方式参与共建向webdriverio/example-recipes仓库补充更多示例在 WebdriverIO 官方文档中引用已有示例即在 Markdown 里按上文格式写入reference useHTTPS引用块。如有任何疑问或反馈也可以在 webdriverio/webdriverio 仓库中提出 issue。对于需要特定运行时环境而不仅仅是浏览器的框架——例如依赖 Node.js 的 WebdriverIO 而言这套方案提供了一种相当优雅的、交互且简单的示例交付方式。如果你也是框架作者、并且用 Docusaurus 构建文档完全可以借鉴甚至直接复制这套做法——它是开源的、免费的。【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
