跳到主要内容

CI 工作流

本文介绍了针对 Grafana 版本矩阵运行端到端测试的过程。

为什么针对 Grafana 版本矩阵运行端到端测试​

由于 Grafana 的依赖共享机制，许多与插件相关的问题仅在运行时才会出现。例如，如果插件调用 Grafana 运行时环境中不可用的函数、组件或类，则加载插件该部分的任何页面都将崩溃。这些运行时特定的问题超出了单元测试的范围，但可以通过端到端测试有效地识别出来。

为了保持可靠性和兼容性，插件开发者必须定期对所有受支持的 Grafana 版本执行端到端测试。`e2e-versions` GitHub Action 通过根据插件的 grafanaDependency 自动解析受支持的 Grafana 版本，同时包含 Grafana 的主开发分支，从而简化了此过程。将此 Action 集成到您的 CI 工作流中，可确保您的插件在旧版本和新版本 Grafana 中保持稳定和兼容，让您对插件在各个版本中的功能充满信心。"

e2e-versions Action​

e2e-versions GitHub Action 生成 Grafana 镜像名称和版本的矩阵，用于在 GitHub 工作流中对 Grafana 插件进行端到端测试。该 Action 支持两种模式

  • plugin-grafana-dependency: 此模式解析最新的 grafana-dev 镜像，并返回自 plugin.json 文件中指定的 grafanaDependency 版本以来的所有最新的 Grafana Enterprise 补丁版本。为了防止启动过多的作业，输出上限为 6 个版本。这是默认模式。
  • version-support-policy: 在此模式下，action 根据 Grafana 的插件兼容性支持策略解析版本。它检索当前主要 Grafana 版本中每个次要版本的最新补丁版本。此外，它还包括上一个主要 Grafana 版本的最新次要版本的最新版本。

有关配置 inputs 的详细信息，请访问 e2e-versions GitHub 页面。

示例工作流​

所有使用 grafana/create-plugin 4.7.0 或更高版本创建的 Grafana 插件都会自动在其 ci.yml 工作流中包含针对 Grafana 版本矩阵的端到端测试。如果您的插件是使用早期版本创建的，则可以使用以下示例工作流在单独的 GitHub 工作流中设置和运行带有 Grafana 版本矩阵的端到端测试

注意

以下示例是通用的，基于前端和后端插件。根据您插件的具体情况，您可能需要在将它们集成到插件的工作流之前，修改或删除 playwright-tests 作业中的某些步骤。

后端插件工作流

.github/workflows/e2e.yml
name: E2E tests
on:
  pull_request:
  schedule:
    - cron: '0 11 * * *' #Run e2e tests once a day at 11 UTC

permissions:
  contents: read
  id-token: write

jobs:
  resolve-versions:
    name: Resolve Grafana images
    runs-on: ubuntu-latest
    timeout-minutes: 3
    outputs:
      matrix: ${{ steps.resolve-versions.outputs.matrix }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Resolve Grafana E2E versions
        id: resolve-versions
        uses: grafana/plugin-actions/e2e-version@main

  playwright-tests:
    needs: resolve-versions
    timeout-minutes: 60
    strategy:
      fail-fast: false
      matrix:
        GRAFANA_IMAGE: ${{fromJson(needs.resolve-versions.outputs.matrix)}}
    name: e2e ${{ matrix.GRAFANA_IMAGE.name }}@${{ matrix.GRAFANA_IMAGE.VERSION }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js environment
        uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc

      - name: Install npm dependencies
        run: npm ci

      - name: Install Mage
        uses: magefile/mage-action@v3
        with:
          install-only: true

      - name: Build binaries
        run: mage -v build:linux

      - name: Build frontend
        run: npm run build

      - name: Install Playwright Browsers
        run: npx playwright install --with-deps

      - name: Start Grafana
        run: |
          docker compose pull
          GRAFANA_VERSION=${{ matrix.GRAFANA_IMAGE.VERSION }} GRAFANA_IMAGE=${{ matrix.GRAFANA_IMAGE.NAME }} docker compose up -d

      - name: Wait for grafana server
        uses: grafana/plugin-actions/wait-for-grafana@main

      - name: Run Playwright tests
        id: run-tests
        run: npx playwright test

前端插件工作流

.github/workflows/e2e.yml
name: E2E tests
on:
  pull_request:
  schedule:
    - cron: '0 11 * * *' #Run e2e tests once a day at 11 UTC

permissions:
  contents: read
  id-token: write

jobs:
  resolve-versions:
    name: Resolve Grafana images
    runs-on: ubuntu-latest
    timeout-minutes: 3
    outputs:
      matrix: ${{ steps.resolve-versions.outputs.matrix }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Resolve Grafana E2E versions
        id: resolve-versions
        uses: grafana/plugin-actions/e2e-version@main

  playwright-tests:
    needs: resolve-versions
    timeout-minutes: 60
    strategy:
      fail-fast: false
      matrix:
        GRAFANA_IMAGE: ${{fromJson(needs.resolve-versions.outputs.matrix)}}
    name: e2e ${{ matrix.GRAFANA_IMAGE.name }}@${{ matrix.GRAFANA_IMAGE.VERSION }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js environment
        uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc

      - name: Install npm dependencies
        run: npm ci

      - name: Build frontend
        run: npm run build

      - name: Install Playwright Browsers
        run: npx playwright install --with-deps

      - name: Start Grafana
        run: |
          docker compose pull
          GRAFANA_VERSION=${{ matrix.GRAFANA_IMAGE.VERSION }} GRAFANA_IMAGE=${{ matrix.GRAFANA_IMAGE.NAME }} docker compose up -d

      - name: Wait for grafana server
        uses: grafana/plugin-actions/wait-for-grafana@main

      - name: Run Playwright tests
        id: run-tests
        run: npx playwright test

将 Playwright 报告发布到 GitHub Pages​

Playwright HTML 报告以及 Trace Viewer 提供了强大的工具，用于解决端到端测试执行期间发现的问题。本节介绍了如何将这些报告部署到 GitHub 的静态站点托管服务 GitHub Pages，以便在测试完成后立即访问它们进行审查。

本指南基于本文档前面提供的示例工作流。

启用报告发布的步骤​

  1. 在执行测试的步骤之后，立即添加一个步骤，该步骤使用 upload-report-artifacts Action 将报告和测试摘要作为 GitHub artifacts 上传。
- name: Run Playwright tests
  id: run-tests
  run: npx playwright test

- name: Upload e2e test summary
  uses: grafana/plugin-actions/playwright-gh-pages/upload-report-artifacts@main
  if: ${{ (always() && !cancelled()) }}
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    test-outcome: ${{ steps.run-tests.outcome }}
  1. 在 playwright-tests 作业之后，添加一个新的作业来下载报告 artifacts，将它们部署到 GitHub Pages，并发布 PR 注释，总结测试结果，包括指向报告的链接。
publish-report:
  if: ${{ (always() && !cancelled()) }}
  needs: [playwright-tests]
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Publish report
      uses: grafana/plugin-actions/playwright-gh-pages/deploy-report-pages@main
      with:
        github-token: ${{ secrets.GITHUB_TOKEN }}
  1. 修改工作流权限以允许其推送更改、查询 GitHub API 和更新 PR 注释。
permissions:
  contents: write
  id-token: write
  pull-requests: write
  1. 如果您的存储库尚未启用 GitHub Pages，请配置用于部署的源分支。按照此处的详细说明进行设置。

有关其他配置选项和示例，请参阅 playwright-gh-pages 文档。

重要注意事项​

  • 公开可见性：默认情况下，GitHub Pages 站点在 Internet 上公开访问。如果您的端到端测试包含敏感数据或机密信息，请注意潜在的暴露风险。
  • 企业访问控制：如果您有 GitHub Enterprise 帐户，则可以配置访问控制以限制可见性。有关详细信息，请参阅 GitHub 文档。

报告摘要​

publish-report 作业添加一个 PR 注释，总结作为矩阵一部分执行的所有测试。对于失败的测试，注释包含指向 GitHub Pages 网站的链接，可以在该网站上浏览详细报告。