Page objects in GitLab QA

原文：https://docs.gitlab.com/ee/development/testing_guide/end_to_end/page_objects.html

Page objects in GitLab QA

在 GitLab 质量检查中，我们使用一种称为Page Objects的已知模式.

这意味着我们已经为用于驱动 GitLab 质量检查方案的 GitLab 中的所有页面建立了抽象. 每当我们在页面上执行某项操作（例如填写表单或单击按钮）时，我们仅通过与该 GitLab 区域相关联的页面对象来执行此操作.

例如，当 GitLab QA 测试工具登录到 GitLab 时，它需要填写用户登录名和用户密码. 为此，我们有一个名为Page::Main::Login和sign_in_using_credentials方法的类，这是代码中仅有的一部分，它具有有关user_login和user_password字段的知识.

Why do we need that?

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

想象一下，我们在 GitLab 质量检查中有 100 个规格，并且在每次声明之前我们都需要登录 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只能放在一个位置.

What problems did we have in the past?

由于性能原因以及构建软件包和测试所有内容所花费的时间，我们不会针对每次提交都运行 QA 测试.

这就是为什么当有人在新的会话视图中将t.text_field :login更改为t.text_field :username ，直到我们的 GitLab QA 夜间管道失败或有人触发了他们的package-and-qa操作，我们才知道这一更改.合并请求.

显然，这样的更改将破坏所有测试. 我们称这个问题为脆弱的测试问题 .

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

How did we solve fragile tests problem?

当前，当您添加新的Page::Base派生类时，还需要定义页面对象所依赖的所有选择器.

Whenever you push your code to CE / EE repository, qa:selectors sanity test job is going to be run as a part of a CI pipeline.

此测试将验证我们在qa/page目录中实现的所有页面对象. 失败时，将通知您有关丢失的或无效的视图/选择器定义的信息.

How to properly implement a page object?

我们建立了一个 DSL 来定义页面对象和它实际实现的 GitLab 视图之间的耦合. 请参阅下面的示例.

  1. module Page
  2.   module Main
  3.     class Login < Page::Base
  4.       view 'app/views/devise/passwords/edit.html.haml' do
  5.         element :password_field
  6.         element :password_confirmation
  7.         element :change_password_button
  8.       end
  10.       view 'app/views/devise/sessions/_new_base.html.haml' do
  11.         element :login_field
  12.         element :password_field
  13.         element :sign_in_button
  14.       end
  16.       # ...
  17.     end
  18.   end
  19. end

Defining Elements

view DSL 方法将对应于渲染元素的 rails View，partial 或 Vue 组件.

element DSL 方法依次声明一个元素，需要将其相应的data-qa-selector=element_name_snaked数据属性添加到视图文件中.

您还可以定义一个值（字符串或正则表达式）以匹配实际的视图代码，但是出于两个原因， 不建议使用上述方法，建议使用该值：

  • 一致性：只有一种定义元素的方法
  • 关注点分离：QA 使用专用的data-qa-*属性，而不是重用其他组件使用的代码或类（例如js-*类等）
  1. view 'app/views/my/view.html.haml' do
  3.   ### Good ###
  5.   # Implicitly require the CSS selector `[data-qa-selector="logout_button"]` to be present in the view
  6.   element :logout_button
  8.   ### Bad ###
  10.   ## This is deprecated and forbidden by the `QA/ElementWithPattern` RuboCop cop.
  11.   # Require `f.submit "Sign in"` to be present in `my/view.html.haml
  12.   element :my_button, 'f.submit "Sign in"' # rubocop:disable QA/ElementWithPattern
  14.   ## This is deprecated and forbidden by the `QA/ElementWithPattern` RuboCop cop.
  15.   # Match every line in `my/view.html.haml` against
  16.   # `/link_to .* "My Profile"/` regexp.
  17.   element :profile_link, /link_to .* "My Profile"/ # rubocop:disable QA/ElementWithPattern
  18. end

Adding Elements to a View

鉴于以下要素…

  1. view 'app/views/my/view.html.haml' do
  2.   element :login_field
  3.   element :password_field
  4.   element :sign_in_button
  5. end

要将这些元素添加到视图，必须通过为定义的每个元素添加data-qa-selector属性来更改 rails View，Partial 或 Vue 组件.

在我们的示例中， data-qa-selector="login_field" ， data-qa-selector="password_field"和data-qa-selector="sign_in_button"

app/views/my/view.html.haml

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

注意事项：

  • 元素的名称和qa_selector必须匹配并使用 snake_cased
  • 如果该元素无条件显示在页面上，请向该元素添加required: true . 请参阅动态元素验证
  • 您可能会在现有的页面对象中看到.qa-selector类. 我们应该使用data-qa-selector定义方法，而不是.qa-selector CSS 类.

data-qa-selector vs .qa-selector

在 GitLab 12.1 中引入

在视图中定义元素有两种支持的方法.

  1. data-qa-selector attribute
  2. .qa-selector class

任何现有的.qa-selector类都应视为已弃用，我们应该更喜欢data-qa-selector定义方法.

Dynamic element selection

在 GitLab 12.5 中引入

自动化测试中常见的一种情况是选择一个”多对多”元素. 在几个项目的列表中，如何区分选择的内容？ 最常见的解决方法是通过文本匹配. 相反，更好的做法是通过唯一标识符而不是文本来匹配该特定元素.

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

Examples

例子 1

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

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

我们可以通过在 Rails 模型上进行匹配来选择特定的问题.

  1. class Page::Project::Issues::Index < Page::Base
  2.   def has_issue?(issue)
  3.     has_element? :issue, issue_title: issue
  4.   end
  5. end

在我们的测试中，我们可以验证此特定问题的存在.

  1. describe 'Issue' do
  2.   it 'has an issue titled "hello"' do
  3.     Page::Project::Issues::Index.perform do |index|
  4.       expect(index).to have_issue('hello')
  5.     end
  6.   end
  7. end

例子 2

通过索引…

  1. %ol
  2.   - @some_model.each_with_index do |model, idx|
  3.     %li.model{ data: { qa_selector: 'model', qa_index: idx } }
  1. expect(the_page).to have_element(:model, index: 1) #=> select on the first model that appears in the list

Exceptions

在某些情况下，可能无法或不值得添加选择器.

一些 UI 组件使用外部库，包括一些第三方维护的库. 即使 GitLab 维护了一个库，选择器的健全性测试也只能在 GitLab 项目中的代码上运行，因此无法为库中的代码指定视图的路径.

在这种罕见的情况下，在页面对象方法中使用 CSS 选择器是合理的，并带有注释说明为什么不能添加element原因.

Define Page concerns

某些页面具有共同的行为，并且/或者在特定于 EE 的模块之前添加了特定于 EE 的方法.

These modules must:

  1. 从QA::Page::PageConcern模块extend QA::Page::PageConcern ，并extend QA::Page::PageConcern .
  2. 重写self.prepended方法，如果他们需要include / prepend其他模块本身，和/或定义view或elements .
  3. 将super称为self.prepended的第一件事.
  4. 包含/添加其他模块，并在base.class_eval块中定义其view / elements ，以确保在添加模块的类中定义了它们.

这些步骤确保健全性选择器检查将正确检测到问题.

例如， qa/qa/ee/page/merge_request/show.rb将 EE 特定方法添加到qa/qa/page/merge_request/show.rb （带有QA::Page::MergeRequest::Show.prepend_if_ee('QA::EE::Page::MergeRequest::Show') ），其实现方式如下（仅显示相关部分，并使用内嵌注释引用上述 4 个步骤）：

  1. module QA
  2.   module EE
  3.     module Page
  4.       module MergeRequest
  5.         module Show
  6.           extend QA::Page::PageConcern # 1.
  8.           def self.prepended(base) # 2.
  9.             super # 3.
  11.             base.class_eval do # 4.
  12.               prepend Page::Component::LicenseManagement
  14.               view 'app/assets/javascripts/vue_merge_request_widget/components/states/sha_mismatch.vue' do
  15.                 element :head_mismatch, "The source branch HEAD has recently changed."
  16.               end
  18.               [...]
  19.             end
  20.           end
  21.         end
  22.       end
  23.     end
  24.   end
  25. end

Running the test locally

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

  1. bin/qa Test::Sanity::Selectors

从qa目录中.

Where to ask for help?

如果您需要更多信息，请在 Slack 上的#quality频道（仅限内部，GitLab 团队）上寻求帮助.

如果你不是一个团队成员，你仍然需要帮助的贡献，请打开 GitLab CE 问题追踪的一个问题~QA标签.