跳过主内容

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 插件都自动包含针对 Grafana 版本矩阵的端到端测试，作为其 ci.yml 工作流程的一部分。如果您的插件是使用更早的版本创建的，可以使用以下示例工作流程在单独的 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 和更新拉取请求评论。
permissions:
  contents: write
  id-token: write
  pull-requests: write
  1. 如果您的仓库尚未启用 GitHub Pages，请配置部署的源分支。请遵循此处的详细说明进行设置。

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

重要注意事项​

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

报告摘要​

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