自信地升级前端依赖项

2023 年 9 月 22 日 ·阅读时长 9 分钟

Docusaurus 维护者，本周 React 编辑

前端开发人员经常需要**升级 npm 依赖项**，但这些升级可能让人感到恐惧，并会导致您的常规测试套件无法捕获的**细微 UI 副作用**。

升级 Docusaurus 就是一个很好的例子：如果没有逐页查看所有页面，很难确保没有视觉回归。**Docusaurus v3 即将发布**（目前处于 beta 版），我们希望帮助您自信地进行此升级。

本文介绍了基于 GitHub Actions、Playwright 和 Argos 的**视觉回归测试**工作流程。它没有直接与 Docusaurus 或 React 耦合，可以适应其他前端应用程序和框架。

此工作流程已在将 Docusaurus v2 升级到 v3 时进行过测试，并且已经帮助在 React Native、Jest 以及 Docusaurus 网站本身等网站上发现了一些视觉回归。

Docusaurus v3 带来了基础设施变化和主要依赖项升级，例如 MDX v3 和 React 18，这些升级可能会产生意外的副作用。如果没有这样的工作流程，很难发现所有视觉回归。因此，我们鼓励站点所有者考虑采用视觉回归测试，特别是对于高度定制的站点。

工作流程概述

总体思路很简单

使用 GitHub Actions 在 CI 中构建您的站点
使用 Playwright 对所有 sitemap.xml 页面进行截图
将它们上传到 Argos
对 Git 分支 main 和 pr-branch 都执行此操作
在 Argos 中并排比较截图

然后，Argos 会将 main 和 pr-branch 之间发现的视觉差异作为 GitHub 提交状态和拉取请求评论进行报告。这可以帮助您以自动化方式提前发现视觉回归。

Argos GitHub commit status

Argos GitHub PR comment

Argos 创建了一份报告，引用了在并排比较两个 Git 分支站点时发现的所有视觉差异，并提供了一个方便的用户界面来轻松发现差异。

查看 Docusaurus Argos 页面，探索我们自己的网站报告。

以下是在升级 React-Native 网站时，Argos 报告视觉回归的更具体示例

工作流程实施

本节将介绍工作流程中每个步骤的实施细节。

您需要注册 Argos 并将 Argos 连接到您的 GitHub 存储库

依赖项

除了通常的 Docusaurus 依赖项之外，此工作流程还需要以下开发依赖项

yarn add -D @argos-ci/cli @argos-ci/playwright @playwright/test cheerio

GitHub Action

GitHub Action 负责为每个 Git 分支执行工作流程。

最小的工作流程可能如下所示

.github/workflows/argos.yml
name: Argos CI Screenshots

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  take-screenshots:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4

      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: current

      - name: Install dependencies
        run: yarn install --frozen-lockfile

      - name: Install Playwright browsers
        run: yarn playwright install --with-deps chromium

      - name: Build the website
        run: yarn docusaurus build

      - name: Take screenshots with Playwright
        run: yarn playwright test

      - name: Upload screenshots to Argos
        run: yarn argos upload ./screenshots

Playwright 配置

Playwright 负责对之前由 GitHub Action 在本地构建的网站进行截图。

最小的 Playwright 配置可能如下所示

playwright.config.ts
import {devices} from '@playwright/test';
import type {PlaywrightTestConfig} from '@playwright/test';

const config: PlaywrightTestConfig = {
  webServer: {
    port: 3000,
    command: 'yarn docusaurus serve',
  },
  projects: [
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
      },
    },
  ],
};

export default config;

Playwright 测试

Playwright 配置还不够：我们还需要编写一个 Playwright 测试文件来生成网站截图。

screenshot.spec.ts
import * as fs from 'fs';
import {test} from '@playwright/test';
import {argosScreenshot} from '@argos-ci/playwright';
import {extractSitemapPathnames, pathnameToArgosName} from './utils';

// Constants
const siteUrl = 'http://localhost:3000';
const sitemapPath = './build/sitemap.xml';
const stylesheetPath = './screenshot.css';
const stylesheet = fs.readFileSync(stylesheetPath).toString();

// Wait for hydration, requires Docusaurus v2.4.3+
// Docusaurus adds a <html data-has-hydrated="true"> once hydrated
// See https://github.com/facebook/docusaurus/pull/9256
function waitForDocusaurusHydration() {
  return document.documentElement.dataset.hasHydrated === 'true';
}

function screenshotPathname(pathname: string) {
  test(`pathname ${pathname}`, async ({page}) => {
    const url = siteUrl + pathname;
    await page.goto(url);
    await page.waitForFunction(waitForDocusaurusHydration);
    await page.addStyleTag({content: stylesheet});
    await argosScreenshot(page, pathnameToArgosName(pathname));
  });
}

test.describe('Docusaurus site screenshots', () => {
  const pathnames = extractSitemapPathnames(sitemapPath);
  console.log('Pathnames to screenshot:', pathnames);
  pathnames.forEach(screenshotPathname);
});

为什么我们要用 Argos 而不是 Playwright 进行截图？

Argos 有一个 Playwright 集成，它包装了原始的 Playwright 截图 API 并提供更好的默认值，以使截图更确定。

utils.ts 中有什么？

该模块包含我们选择隐藏的实施细节，以保持清晰。

import * as cheerio from 'cheerio';
import * as fs from 'fs';

// Extract a list of pathnames, given a fs path to a sitemap.xml file
// Docusaurus generates a build/sitemap.xml file for you!
export function extractSitemapPathnames(sitemapPath: string): string[] {
  const sitemap = fs.readFileSync(sitemapPath).toString();
  const $ = cheerio.load(sitemap, {xmlMode: true});
  const urls: string[] = [];
  $('loc').each(function handleLoc() {
    urls.push($(this).text());
  });
  return urls.map((url) => new URL(url).pathname);
}

// Converts a pathname to a decent screenshot name
export function pathnameToArgosName(pathname: string): string {
  return pathname.replace(/^\/|\/$/g, '') || 'index';
}

样式表

截图并不总是确定的，对页面进行两次截图会导致 Argos 作为误报视觉回归报告的细微变化。

因此，我们建议注入额外的样式表来隐藏有问题的元素。您可能需要根据在您自己的站点上发现的易变元素，向此基本样式表添加新的 CSS 规则。阅读 Argos - 关于易变测试的文档以了解更多信息。

screenshot.css
/* Iframes can load lazily */
iframe,
/* Avatars can be flaky due to using external sources: GitHub/Unavatar */
.avatar__photo,
/* Gifs load lazily and are animated */
img[src$='.gif'],
/* Algolia keyboard shortcuts appear with a little delay */
.DocSearch-Button-Keys > kbd,
/* The live playground preview can often display dates/counters */
[class*='playgroundPreview'] {
  visibility: hidden;
}

/* Different docs last-update dates can alter layout */
.theme-last-updated,
/* Mermaid diagrams are rendered client-side and produce layout shifts */
.docusaurus-mermaid-container {
  display: none;
}

防止布局偏移

我们建议使用 display: none; 隐藏影响布局的易变 UI 元素。

例如，文档的“上次更新时间”可能会渲染在不止一行上，最终会将您的其他内容“推”到更下方，导致 Argos 检测到许多不同的像素。

示例存储库

The slorber/docusaurus-argos-example 存储库展示了在使用 Yarn 单仓库的新初始化 Docusaurus v2 站点上实施此工作流程的完整示例。

降低成本

我们选择的工具是此视觉回归测试工作流程的实现细节。

对于 Docusaurus，我们选择 Argos：它对我们很有效，并提供免费和开源计划。但是，您可以自由采用其他工具。

如果您不介意在 Git 中存储大量截图，您也可以尝试免费的、自托管的 Playwright 视觉比较并在 npx playwright show-report 中浏览视觉差异。但是，我们发现使用专门的外部工具更方便。

外部工具可能很昂贵，但通常提供免费计划，并有充足的截图配额。您可以通过实施以下一些技巧来减少截图消耗。

限制路径名数量

基本设置涉及对 sitemap.xml 中找到的每个路径名进行截图。对于大型站点，这会导致大量截图。

您可以决定过滤路径名，只对最重要的页面进行截图。

对于 Docusaurus 网站，不要对版本化的文档页面进行截图

screenshot.spec.ts
function isVersionedDocsPathname(pathname: string): boolean {
  return pathname.match(/^\/docs\/((\d\.\d\.\d)|(next))\//);
}

test.describe('Docusaurus site screenshots', () => {
  const pathnames = extractSitemapPathnames(sitemapPath)
    .filter(isVersionedDocsPathname);

  pathnames.forEach(screenshotPathname);
});

限制工作流程并发性

实施GitHub Actions 并发组将阻止连续提交触发多个无用的工作流运行。工作流将只针对最后一次提交执行，之前提交将自动取消。

.github/workflows/argos.yml
concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

有条件地运行您的工作流

为每个提交和拉取请求运行此工作流不值得。

例如，如果有人在您的文档中更正了错别字，您可能不希望拍摄数百张屏幕截图并让 Argos 指出只有修改的页面存在视觉差异：这有点令人期待！

对于 Docusaurus 网站，我们只对具有 Argos 标签的拉取请求运行工作流。

.github/workflows/argos.yml
name: Argos CI Screenshots

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
    types:
      - opened
      - synchronize
      - reopened
      - labeled

jobs:
  take-screenshots:
    if: ${{ github.ref_name == 'main' || (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'Argos')) }}
    runs-on: ubuntu-latest
    steps:
      # Your job steps here ...

有很多选项可以探索，例如手动触发工作流或仅当匹配特定模式的文件被修改时才触发。

结论

我相信视觉回归测试在前端生态系统中被低估了。

拍摄全页面屏幕截图是一种唾手可得的成果，它易于设置，可以帮助您捕获您的常规测试套件可能会遗漏的新一类错误。这种技术不仅适用于 npm 包升级，而且适用于任何类型的重构，这些重构不应该改变用户界面。

那么为什么不试试呢？

祝您编码愉快！

另请参阅

有用的文档链接

工作流程概述​

工作流程实施​

依赖项​

GitHub Action​

Playwright 配置​

Playwright 测试​

样式表​

示例存储库​

降低成本​

限制路径名数量​

限制工作流程并发性​

有条件地运行您的工作流​

结论​

另请参阅​