Help us learn about your current experience with the documentation. Take the survey.

GitLab QA 中的页面对象

在 GitLab QA 中，我们使用一种称为 Page Objects（页面对象）的已知模式。

这意味着我们为 GitLab 中的所有页面构建了一个抽象层，用于驱动 GitLab QA 场景。每当我们在页面上执行操作，比如填写表单或选择按钮时，我们只会通过与此 GitLab 区域关联的页面对象来执行。

例如，当 GitLab QA 测试框架登录 GitLab 时，它需要填写用户名和密码。为此，我们有一个名为 Page::Main::Login 的类和 sign_in_using_credentials 方法，这是唯一读取 user-login 和 user-password 字段的代码。

为什么需要这个？

我们需要页面对象，因为需要减少代码重复，并避免有人在 GitLab 源代码中更改选择器时出现问题。

想象一下，我们在 GitLab QA 中有上百个测试规范，每次进行断言前都需要登录 GitLab。如果没有页面对象，就需要依赖不稳定的辅助方法或直接调用 Capybara 方法。想象一下在每个 *_spec.rb 文件/测试示例中都调用 fill_in 'user-login'。

当有人在与此页面关联的视图中将 t.text_field 'login' 更改为 t.text_field 'username' 时，会生成不同的字段标识符，这将导致所有测试失效。

由于我们在所有地方都使用 Page::Main::Login.perform(&:sign_in_using_credentials)，当我们想要登录 GitLab 时，页面对象是唯一的事实来源，我们只需要在一个地方将 fill_in 'user-login' 更新为 fill_in 'user-username'。

我们过去遇到过什么问题？

由于性能原因以及构建包和测试所有内容所需的时间，我们不会为每次提交都运行 QA 测试。

这就是为什么当有人在 new session 视图中将 t.text_field 'login' 更改为 t.text_field 'username' 时，我们直到 GitLab QA 夜间流水线失败，或者有人在合并请求中触发 package-and-qa 操作时才知道这个变化。

这样的更改会破坏所有测试。我们将这个问题称为 脆弱测试问题。

为了使 GitLab QA 更加可靠和健壮，我们必须通过引入 GitLab CE/EE 视图与 GitLab QA 之间的耦合来解决此问题。

我们如何解决脆弱测试问题？

当前，当你添加一个新的 Page::Base 派生类时，还必须定义页面对象所依赖的所有选择器。

每当你的代码推送到 CE/EE 仓库时，qa:selectors 完整性测试作业都会作为 CI 流水线的一部分运行。

此测试验证我们在 qa/page 目录中实现的所有页面对象。当测试失败时，它会通知你缺少或无效的视图/选择器定义。

如何正确实现页面对象？

我们构建了一个 DSL（领域特定语言）来定义页面对象与实际实现它的 GitLab 视图之间的耦合。请看下面的示例。

module Page
  module Main
    class Login < Page::Base
      view 'app/views/devise/passwords/edit.html.haml' do
        element 'password-field'
        element 'password-confirmation'
        element 'change-password-button'
      end

      view 'app/views/devise/sessions/_new_base.html.haml' do
        element 'login-field'
        element 'password-field'
        element 'sign-in-button'
      end

      # ...
    end
  end
end

定义元素

view DSL 方法对应于渲染元素的 Rails 视图、局部视图或 Vue 组件。

element DSL 方法声明一个元素，必须在视图文件中为其添加相应的 testid=element-name 数据属性（如果尚未添加）。

你也可以定义一个值（字符串或正则表达式）来匹配实际的视图代码，但此方法已被弃用，原因如下：

  • 一致性：只有一种定义元素的方式
  • 关注点分离：测试使用专用的 data-testid 属性，而不是重用其他组件使用的代码或类（例如 js-* 类等）
view 'app/views/my/view.html.haml' do

  ### Good ###

  # 隐式要求视图中存在 CSS 选择器 `[data-testid="logout-button"]`
  element 'logout-button'

  ### Bad ###

  ## 这已被弃用，并且被 `QA/ElementWithPattern` RuboCop 规则禁止。
  # 要求 `my/view.html.haml` 中存在 `f.submit "Sign in"`
  element :my_button, 'f.submit "Sign in"' # rubocop:disable QA/ElementWithPattern

  ## 这已被弃用，并且被 `QA/ElementWithPattern` RuboCop 规则禁止。
  # 将 `my/view.html.haml` 中的每一行与 `/link_to .* "My Profile"/` 正则表达式匹配。
  element :profile_link, /link_to .* "My Profile"/ # rubocop:disable QA/ElementWithPattern
end

向视图中添加元素

给定以下元素…

view 'app/views/my/view.html.haml' do
  element 'login-field'
  element 'password-field'
  element 'sign-in-button'
end

要将这些元素添加到视图中，你必须通过为每个定义的元素添加 data-testid 属性来更改 Rails 视图、局部视图或 Vue 组件。

在我们的例子中，data-testid="login-field"、data-testid="password-field" 和 data-testid="sign-in-button"

app/views/my/view.html.haml

= f.text_field :login, class: "form-control top", autofocus: "autofocus", autocapitalize: "off", autocorrect: "off", required: true, title: "This field is required.", data: { testid: 'login_field' }
= f.password_field :password, class: "form-control bottom", required: true, title: "This field is required.", data: { testid: 'password_field' }
= f.submit "Sign in", class: "btn btn-confirm", data: { testid: 'sign_in_button' }

注意事项：

  • 元素名称和 data-testid 必须匹配并使用 kebab-case 格式
  • 如果元素无条件出现在页面上，请为元素添加 required: true。请参阅 动态元素验证
  • 你不应该在页面对象中看到 data-qa-selector 类。我们应该使用 data-testid 定义方法

data-testid 与 data-qa-selector 的对比

任何现有的 data-qa-selector 类都应被视为已弃用，我们应该使用 data-testid 定义方法。

动态元素选择

自动化测试中常见的情况是选择单个"多选一"的元素。在多个项目的列表中，如何区分你选择的是哪个？最常见的解决方法是文本匹配。更好的做法是通过唯一标识符匹配特定元素，而不是通过文本。

我们通过添加 data-qa-* 可扩展选择机制来解决这个问题。

示例

示例 1

给定以下 Rails 视图（以 GitLab Issues 为例）：

%ul.issues-list
 - @issues.each do |issue|
   %li.issue{data: { testid: 'issue', qa_issue_title: issue.title } }= link_to issue

我们可以通过匹配 Rails 模型来选择特定的 issue。

class Page::Project::Issues::Index < Page::Base
  def has_issue?(issue)
    has_element?(:issue, issue_title: issue)
  end
end

在我们的测试中，我们可以验证这个特定的 issue 是否存在。

describe 'Issue' do
  it 'has an issue titled "hello"' do
    Page::Project::Issues::Index.perform do |index|
      expect(index).to have_issue('hello')
    end
  end
end

示例 2

通过索引…

%ol
  - @some_model.each_with_index do |model, idx|
    %li.model{ data: { testid: 'model', qa_index: idx } }
expect(the_page).to have_element(:model, index: 1) #=> 选择列表中出现的第一个 model

异常情况

在某些情况下，添加选择器可能不可行或不值得。

一些 UI 组件使用外部库，其中一些由第三方维护。即使库由 GitLab 维护，选择器完整性测试也只在 GitLab 项目内的代码上运行，因此无法为库中的代码指定视图路径。

在少数情况下，在页面对象方法中使用 CSS 选择器是合理的，并添加注释说明为什么不能添加 element。

定义页面关注点

一些页面共享通用行为，或者被添加了 EE 特定模块（这些模块添加了 EE 特定方法）。

这些模块必须：

  1. 从 QA::Page::PageConcern 模块扩展，使用 extend QA::Page::PageConcern。
  2. 如果需要自己 include/prepend 其他模块，和/或定义 view 或 elements，则重写 self.prepended 方法。
  3. 在 self.prepended 中首先调用 super。
  4. 在 base.class_eval 块中 include/prepend 其他模块并定义它们的 view/elements，以确保它们在添加该模块的类中定义。

这些步骤确保完整性选择器检查能够正确检测问题。

例如，qa/qa/ee/page/merge_request/show.rb 向 qa/qa/page/merge_request/show.rb 添加了 EE 特定方法（使用 QA::Page::MergeRequest::Show.prepend_mod_with('Page::MergeRequest::Show', namespace: QA)），以下是它的实现方式（仅显示相关部分，并使用内联注释引用上述 4 个步骤）：

module QA
  module EE
    module Page
      module MergeRequest
        module Show
          extend QA::Page::PageConcern # 1.

          def self.prepended(base) # 2.
            super # 3.

            base.class_eval do # 4.
              prepend Page::Component::LicenseManagement

              view 'app/assets/javascripts/vue_merge_request_widget/components/states/sha_mismatch.vue' do
                element 'head-mismatch', "The source branch HEAD has recently changed."
              end

              [...]
            end
          end
        end
      end
    end
  end
end

在本地运行测试

在开发过程中，你可以通过运行以下命令来运行 qa:selectors 测试：

bin/qa Test::Sanity::Selectors

在 qa 目录中。

在哪里寻求帮助？

如果你需要更多信息，请在 Slack 的 #s_developer_experience 频道寻求帮助（内部，仅限 GitLab 团队成员）。

如果你不是团队成员，但仍需要帮助进行贡献，请在 GitLab 问题跟踪器中创建一个带有 ~QA 标签的问题。