1 files changed, 47 insertions, 0 deletions
diff --git a/doc/development/testing_guide/end_to_end/page_objects.md b/doc/development/testing_guide/end_to_end/page_objects.md
index 22e7375be1f..9d4fa5316c4 100644
--- a/doc/development/testing_guide/end_to_end/page_objects.md
+++ b/doc/development/testing_guide/end_to_end/page_objects.md
@@ -238,6 +238,53 @@ the view for code in a library.
 In such rare cases it's reasonable to use CSS selectors in page object methods,
 with a comment explaining why an `element` can't be added.
 
+### Define Page concerns
+
+Some pages share common behaviors, and/or are prepended with EE-specific modules that adds EE-specific methods.
+
+These modules must:
+
+1. Extend from the `QA::Page::PageConcern` module, with `extend QA::Page::PageConcern`.
+1. Override the `self.prepended` method if they need to `include`/`prepend` other modules themselves, and/or define
+  `view` or `elements`.
+1. Call `super` as the first thing in `self.prepended`.
+1. Include/prepend other modules and define their `view`/`elements` in a `base.class_eval` block to ensure they're
+   defined in the class that prepends the module.
+
+These steps ensure the sanity selectors check will detect problems properly.
+
+For example, `qa/qa/ee/page/merge_request/show.rb` adds EE-specific methods to `qa/qa/page/merge_request/show.rb` (with
+`QA::Page::MergeRequest::Show.prepend_if_ee('QA::EE::Page::MergeRequest::Show')`) and following is how it's implemented
+(only showing the relevant part and refering to the 4 steps described above with inline comments):
+
+```ruby
+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
+```
+
 ## Running the test locally
 
 During development, you can run the `qa:selectors` test by running