E2E 测试规范和最佳实践

维护者:

@TomHeng

概述
对 Upstream 类做重载
极狐添加新的组件
常量不存在和方法不存在问题处理
硬编码问题处理
- 类/模块中里的硬编码
- 测试用例里的硬编码

概述

本文主要介绍了在编写 E2E 测试代码时，需要遵循的规范和最佳实践。

如果你对 E2E 测试还一无所知，可以先来读一下 Gitlab E2E 测试的一些常识。

对 Upstream 类做重载

Upstream 的代码大部分类已经实现了版本重载功能，可以实现 CE -> EE -> JH 版本重载的功能。

重载步骤

重载总共有两步：

在 Upstream 需要重载的组件下面添加 prepend_mod_with 功能：

 # gdk/gitlab/qa/qa/runtime/env.rb
 module QA
   module Runtime
     module Env
       # ...
     end
   end
 end
   
 QA::Runtime::Env.prepend_mod_with('Runtime::Env', namespace: QA)

在极狐里添加模块来重载 Upstream 的组件

 # gdk/gitlab/jh/qa/qa/jh/runtime/env.rb
 module QA
   module JH
     module Runtime
       module Env
         extend ActiveSupport::Concern
   
         class_methods do
           def class_method
             # ...
           end
         end
   
         def instance_method
           # ...
         end
       end
     end
   end
 end

重载方法

细心会发现重载方法其实总共有三个：

prepend_mod_with: 重载组件的实例方法（Class.new.xxx），方法优先级比 Upstream 更高。该方法也可以通过钩子重载类方法，因此我们统一只使用这个方法。
extend_mod_with: 重载组件的类方法（静态方法）（Class.xxx），方法优先级比 Upstream 更高
include_mod_with: 重载组件的实例方法（Class.new.xxx），方法优先级比 Upstream 更低，因此用这个方法的场景只有极狐新增方法，且希望将来 Upstream 出现同名方法时优先 Upstream 的方法

重载注意点

所有需要重载的代码需要放在这个 qa/qa/jh/ 目录下（参照的是 GitLab 主项目的重载方案）
极狐的重载都是模块 Module 而非 Class

极狐的模块命名约定是 Upstream 组件里的 QA 后面多加一个 JH：

 QA::Page::Group::Menu -> QA::JH::Page::Group::Menu
 QA::Runtime::Env      -> QA::JH::Runtime::Env

prepend_mod_with 是用的最多的重载方法，因为他支持覆写 Upstream 已有的方法和给 Upstream 组件添加新的方法。这里为了后期好维护，对于覆写需要添加特殊注释：

 # gdk/gitlab/jh/qa/qa/jh/runtime/env.rb
 module QA
   module JH
     module Runtime
       module Env
         # @override :upstream_method
         def upstream_method
           # ...
         end

         def jihu_new_method
           # ...
         end
       end
     end
   end
 end

极狐添加新的组件

极狐专属功能也需要添加 E2E 测试，需要写自己的 QA 组件，写这些组件主要注意下面几点：

所有极狐组件的代码需要放在这个 qa/qa/ 目录下（参照的是 GitLab 主项目的重载方案）
极狐组件大部分是 Class，也可能会有 Module
极狐组件的命名应该跟 Upstream 组件保持一致，如果出现命名冲突，请更换极狐组件名称

常量不存在和方法不存在问题处理

这两个错误很常见，但是调试具体原因也是有方法的，首先可以给 gdk/gitlab/qa/qa.rb 最底部加个断点（因为此处是刚加载完所有组件的地方，刚好用于排查常量和方法问题）：

# gdk/gitlab/qa/qa.rb
require 'pry'

module QA
  # ...
  binding.pry
end

然后运行一个测试，到达断点处，尝试运行出错常量和方法复现错误，然后可以按下面方案处理：

常量不存在先检查新加常量名称和文件规范是否符合 Zeitwerk 库要求（可以参考已有常量），然后尝试将相对常量换成绝对常量（因为复杂嵌套下，可能找错）：
```
  Menu -> ::QA::Page::Group::Menu
  Env  -> ::QA::Runtime::Env
```
方法不存在大部分发生在给 Upstream 组件添加的方法里，请检查是否重载正确，例如一个功能给 QA::Runtime::Env 用重载方式添加的 jh_env 方法没找到：
1. 先判断极狐重载模块代码正确：QA::JH::Runtime::Env.instance_methods.include?('jh_env') 语句需要没有报错且返回 true。
2. 然后判断 Upstream 组件是否存在新方法：QA::Runtime::Env.instance_methods.include?('jh_env') 语句需要没有报错且返回 true。如果重载的是类方法，需要换成 QA::JH::Runtime::Env.methods.include?('jh_env')
3. 如果极狐重载模块有方法，Upstream 没有，请检查 Upstream 组件底部的重载代码正确，例如是否名称写错或者 prepend_mod_with 和 extend_mod_with 用错

硬编码问题处理

类/模块中里的硬编码

这类硬编码实际上只需要将硬编码部分拆取一个新的私有方法，然后极狐对这个私有方法进行覆盖即可，以下是一个例子：

Upstream 的待处理硬编码模块：

module QA
  module M1
    def execute
      doing_thing_before
      doing_thing_with_hardcode('upstream_hardcode')
      doing_thing_after
    end
  end
end

处理后的示例：

# Upstream
module QA
  module M1
    def execute
      doing_thing_before
      doing_thing_with_hardcode(some_data)
      doing_thing_after
    end
    
    private
    
    def some_data
      'upstream_hardcode'
    end
  end
end

# JH
module QA
  module JH
    module M1
      private

      # @override :some_data
      def some_data
        'jh_hardcode'
      end
    end
  end
end

测试用例里的硬编码

比如一个硬编码问题：

RSpec.describe 'Fulfillment' do
  let(:user) { 'GitLab QA' }
  let(:company) { 'QA User' }
  let(:user_count) { 10_000 }
end

对于这个问题，因为测试用例都是 Block 环境，没有实体类/模块，因此无法直接抽取方法来覆盖。当前需要抽取一个 Data 模块出来实现，具体抽取逻辑请参考这个 Upstream MR: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103608

抽取 Data 模块完成之后，然后就只要在极狐这边重载这个 Data 模块即可解决硬编码码问题。

对于抽取 Data 模块规范，请遵守：

Data 模块命名：qa/qa/support/data/#{测试用例文件名}.rb
对于抽取的方法命名：def #{文件名}_#{当前环境}_实体名：
- 当前环境：describe, context, it 每个块的嵌套都会起一个新的环境，每个环境的实体可能相同，需要添加环境前缀以将他们区分开
- 实体名：就是当前硬编码的合适名称，请使用名词