Resource class in GitLab QA

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

Resource class in GitLab QA

资源主要是使用浏览器 UI 步骤创建的，但也可以通过 API 或 CLI 创建的.

How to properly implement a resource class?

所有资源类都应继承自Resource::Base .

只有一种强制性方法可以实现以定义资源类. 这是#fabricate! 方法，用于通过浏览器 UI 构建资源. 请注意，在此方法中，您仅应使用Page 对象与网页进行交互.

这是一个假想的例子：

  1. module QA
  2.   module Resource
  3.     class Shirt < Base
  4.       attr_accessor :name
  6.       def fabricate!
  7.         Page::Dashboard::Index.perform do |dashboard_index|
  8.           dashboard_index.go_to_new_shirt
  9.         end
  11.         Page::Shirt::New.perform do |shirt_new|
  12.           shirt_new.set_name(name)
  13.           shirt_new.create_shirt!
  14.         end
  15.       end
  16.     end
  17.   end
  18. end

Define API implementation

资源类还可以实现以下三种方法，以便能够通过公共 GitLab API 创建资源：

  • #api_get_path ：获取现有资源的GET路径.
  • #api_post_path ：用于创建新资源的POST路径.
  • #api_post_body ：用于创建新资源的POST正文（作为 Ruby 哈希）.

请注意，许多 API 资源都是分页的 . 如果找不到期望的结果，请检查是否有超过一页的结果.

让我们使用Shirt资源类，并添加以下三个 API 方法：

  1. module QA
  2.   module Resource
  3.     class Shirt < Base
  4.       attr_accessor :name
  6.       def fabricate!
  7.         # ... same as before
  8.       end
  10.       def api_get_path
  11.         "/shirt/#{name}"
  12.       end
  14.       def api_post_path
  15.         "/shirts"
  16.       end
  18.       def api_post_body
  19.         {
  20.           name: name
  21.         }
  22.       end
  23.     end
  24.   end
  25. end

Project资源是浏览器 UI 和 API 实现的一个很好的真实示例.

Resource attributes

一个资源可能首先需要另一个资源. 例如，一个项目需要在其中创建一个组.

要定义资源属性，可以将attribute方法与使用其他资源类的块一起使用以构造资源.

这将允许从资源对象的方法访问其他资源. 您通常会在#fabricate!使用它#fabricate! ， #api_get_path ， #api_post_path ， #api_post_body .

让我们使用Shirt资源类，并向其添加一个project属性：

  1. module QA
  2.   module Resource
  3.     class Shirt < Base
  4.       attr_accessor :name
  6.       attribute :project do
  7.         Project.fabricate! do |resource|
  8.           resource.name = 'project-to-create-a-shirt'
  9.         end
  10.       end
  12.       def fabricate!
  13.         project.visit!
  15.         Page::Project::Show.perform do |project_show|
  16.           project_show.go_to_new_shirt
  17.         end
  19.         Page::Shirt::New.perform do |shirt_new|
  20.           shirt_new.set_name(name)
  21.           shirt_new.create_shirt!
  22.         end
  23.       end
  25.       def api_get_path
  26.         "/project/#{project.path}/shirt/#{name}"
  27.       end
  29.       def api_post_path
  30.         "/project/#{project.path}/shirts"
  31.       end
  33.       def api_post_body
  34.         {
  35.           name: name
  36.         }
  37.       end
  38.     end
  39.   end
  40. end

请注意，所有属性都是延迟构造的. 这意味着，如果您要首先构造特定的属性，则即使不使用它，也需要首先调用 attribute 方法.

Product data attributes

创建后，您可能希望使用可在网页或 API 响应中找到的属性填充资源. 例如，创建项目后，您可能希望将其存储库 SSH URL 存储为属性.

同样，我们可以将attribute方法与块一起使用，使用页面对象来检索页面上的数据.

让我们以Shirt资源类Shirt ，并定义一个:brand属性：

  1. module QA
  2.   module Resource
  3.     class Shirt < Base
  4.       attr_accessor :name
  6.       attribute :project do
  7.         Project.fabricate! do |resource|
  8.           resource.name = 'project-to-create-a-shirt'
  9.         end
  10.       end
  12.       # Attribute populated from the Browser UI (using the block)
  13.       attribute :brand do
  14.         Page::Shirt::Show.perform do |shirt_show|
  15.           shirt_show.fetch_brand_from_page
  16.         end
  17.       end
  19.       # ... same as before
  20.     end
  21.   end
  22. end

再次注意，所有属性都是延迟构造的. 这意味着，如果您shirt.brand另一页面后再调用shirt.brand ，则由于我们不在预期的页面上，因此将无法正确检索数据.

考虑一下：

  1. shirt =
  2.   QA::Resource::Shirt.fabricate! do |resource|
  3.     resource.name = "GitLab QA"
  4.   end
  6. shirt.project.visit!
  8. shirt.brand # => FAIL!

上面的示例将失败，因为现在我们在项目页面上，试图从衬衫页面构造品牌数据，但是我们已经移至项目页面. 有两种解决方法，一种是我们可以在再次访问该项目之前尝试检索该品牌：

  1. shirt =
  2.   QA::Resource::Shirt.fabricate! do |resource|
  3.     resource.name = "GitLab QA"
  4.   end
  6. shirt.brand # => OK!
  8. shirt.project.visit!
  10. shirt.brand # => OK!

The attribute will be stored in the instance therefore all the following calls will be fine, using the data previously constructed. If we think that this might be too brittle, we could eagerly construct the data right before ending fabrication:

  1. module QA
  2.   module Resource
  3.     class Shirt < Base
  4.       # ... same as before
  6.       def fabricate!
  7.         project.visit!
  9.         Page::Project::Show.perform do |project_show|
  10.           project_show.go_to_new_shirt
  11.         end
  13.         Page::Shirt::New.perform do |shirt_new|
  14.           shirt_new.set_name(name)
  15.           shirt_new.create_shirt!
  16.         end
  18.         populate(:brand) # Eagerly construct the data
  19.       end
  20.     end
  21.   end
  22. end

populate方法将遍历其参数并分别调用每个属性. 这里populate(:brand)有像刚才一样的效果brand . 使用填充方法使意图更清晰.

这样，将确保我们在创建衬衫后立即构造数据. 缺点是，即使我们不需要使用数据，也总是在构造资源时构造数据.

另外，我们可以在构建品牌数据之前确保在正确的页面上：

  1. module QA
  2.   module Resource
  3.     class Shirt < Base
  4.       attr_accessor :name
  6.       attribute :project do
  7.         Project.fabricate! do |resource|
  8.           resource.name = 'project-to-create-a-shirt'
  9.         end
  10.       end
  12.       # Attribute populated from the Browser UI (using the block)
  13.       attribute :brand do
  14.         back_url = current_url
  15.         visit!
  17.         Page::Shirt::Show.perform do |shirt_show|
  18.           shirt_show.fetch_brand_from_page
  19.         end
  21.         visit(back_url)
  22.       end
  24.       # ... same as before
  25.     end
  26.   end
  27. end

这将确保在构建品牌之前，它在衬衫页面上，并返回到上一页以避免破坏状态.

Define an attribute based on an API response

有时，您想基于来自其GET或POST请求的 API 响应来定义资源属性. 例如，如果通过 API 创建衬衫的返回

  1. {
  2.   brand: 'a-brand-new-brand',
  3.   style: 't-shirt',
  4.   materials: [[:cotton, 80], [:polyamide, 20]]
  5. }

您可能希望将style main_fabric在资源中，并在main_fabric属性中获取第一个materials项的第一个值.

让我们以Shirt资源类:main_fabric ，并定义一个:style和:main_fabric属性：

  1. module QA
  2.   module Resource
  3.     class Shirt < Base
  4.       # ... same as before
  6.       # @style from the instance if present,
  7.       # or fetched from the API response if present,
  8.       # or a QA::Resource::Base::NoValueError is raised otherwise
  9.       attribute :style
  11.       # If @main_fabric is not present,
  12.       # and if the API does not contain this field, this block will be
  13.       # used to construct the value based on the API response, and
  14.       # store the result in @main_fabric
  15.       attribute :main_fabric do
  16.         api_response.&dig(:materials, 0, 0)
  17.       end
  19.       # ... same as before
  20.     end
  21.   end
  22. end

有关属性优先级的说明：

  • 资源实例变量具有最高优先级
  • API 响应中的属性优先于块中的属性（通常是来自浏览器用户界面）
  • 没有值的属性将引发QA::Resource::Base::NoValueError错误

Creating resources in your tests

要在测试中创建资源，可以调用.fabricate! 资源类上的方法. 请注意，如果资源类支持 API 构造，则默认情况下将使用该构造.

这是一个示例，由于Shirt资源类支持该方法，因此将在后台使用 API​​构造方法：

  1. my_shirt = Resource::Shirt.fabricate! do |shirt|
  2.   shirt.name = 'my-shirt'
  3. end
  5. expect(page).to have_text(my_shirt.name) # => "my-shirt" from the resource's instance variable
  6. expect(page).to have_text(my_shirt.brand) # => "a-brand-new-brand" from the API response
  7. expect(page).to have_text(my_shirt.style) # => "t-shirt" from the API response
  8. expect(page).to have_text(my_shirt.main_fabric) # => "cotton" from the API response via the block

如果您明确希望使用浏览器 UI 的制作方法，则可以调用.fabricate_via_browser_ui! 方法：

  1. my_shirt = Resource::Shirt.fabricate_via_browser_ui! do |shirt|
  2.   shirt.name = 'my-shirt'
  3. end
  5. expect(page).to have_text(my_shirt.name) # => "my-shirt" from the resource's instance variable
  6. expect(page).to have_text(my_shirt.brand) # => the brand name fetched from the `Page::Shirt::Show` page via the block
  7. expect(page).to have_text(my_shirt.style) # => QA::Resource::Base::NoValueError will be raised because no API response nor a block is provided
  8. expect(page).to have_text(my_shirt.main_fabric) # => QA::Resource::Base::NoValueError will be raised because no API response and the block didn't provide a value (because it's also based on the API response)

您还可以通过调用.fabricate_via_api!来显式使用 API .fabricate_via_api! 方法：

  1. my_shirt = Resource::Shirt.fabricate_via_api! do |shirt|
  2.   shirt.name = 'my-shirt'
  3. end

在这种情况下，结果将类似于调用Resource::Shirt.fabricate! .

Where to ask for help?

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

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