1 files changed, 10 insertions, 0 deletions
diff --git a/doc/development/testing_guide/end_to_end/best_practices.md b/doc/development/testing_guide/end_to_end/best_practices.md
index 15520d8a6b1..74c02d19d0a 100644
--- a/doc/development/testing_guide/end_to_end/best_practices.md
+++ b/doc/development/testing_guide/end_to_end/best_practices.md
@@ -338,6 +338,16 @@ Page::Project::Pipeline::Show.perform do |pipeline|
 end
 ```
 
+### Use `eventually_` matchers for expectations that require waiting
+
+When something requires waiting to be matched, use `eventually_` matchers with clear wait duration definition.
+
+`Eventually` matchers use the following naming pattern: `eventually_${rspec_matcher_name}`. They are defined in [eventually_matcher.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/spec/support/matchers/eventually_matcher.rb).
+
+```ruby
+expect { async_value }.to eventually_eq(value).within(max_duration: 120, max_attempts: 60, reload_page: page)
+```
+
 ### Create negatable matchers to speed `expect` checks
 
 However, sometimes we want to check that something is _not_ as we _don't_ want it to be. In other