Add more examples to UI Testing docs

doc/development/testing_guide/best_practices.md

@@ -362,20 +362,16 @@ The benefits of testing in this way are that:
 - It is less brittle, as it avoids querying by IDs, classes, and attributes, which are not visible to the user.
 
 We strongly recommend that you query by the element's text label instead of by ID, class name, or `data-testid`.
+
 If needed, you can scope interactions within a specific area of the page by using `within`.
+As you will likely be scoping to an element such as a `div`, which typically does not have a label,
+you may use a `data-testid` selector in this case.
 
 ##### Actions
 
 Where possible, use more specific [actions](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Actions), such as the ones below.
 
 ```ruby
-# bad
-find(".group-name", text: group.name).click
-find('.js-show-diff-settings').click
-find('[data-testid="submit-review"]').click
-find('input[type="checkbox"]').click
-find('.search').native.send_keys('gitlab')
-
 # good
 click_button 'Submit review'
 
@@ -391,6 +387,14 @@ uncheck 'Checkbox label'
 choose 'Radio input label'
 
 attach_file('Attach a file', '/path/to/file.png')
+
+# bad - interactive elements must have accessible names, so
+# we should be able to use one of the specific actions above
+find('.group-name', text: group.name).click
+find('.js-show-diff-settings').click
+find('[data-testid="submit-review"]').click
+find('input[type="checkbox"]').click
+find('.search').native.send_keys('gitlab')
 ```
 
 ##### Finders
@@ -398,9 +402,6 @@ attach_file('Attach a file', '/path/to/file.png')
 Where possible, use more specific [finders](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Finders), such as the ones below.
 
 ```ruby
-# bad
-find('[data-testid="submit-review"]')
-
 # good
 find_button 'Submit review'
 find_button 'Submit review', disabled: true
@@ -413,24 +414,26 @@ find_field 'Search projects', with: 'gitlab' # find the input field with text
 find_field 'Search projects', disabled: true
 find_field 'Checkbox label', checked: true
 find_field 'Checkbox label', unchecked: true
+
+# acceptable when finding a element that is not a button, link, or field
+find('[data-testid="element"]')
 ```
 
 ##### Matchers
 
-Where possible, use more specific [matchers](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Matchers), such as the ones below.
+Where possible, use more specific [matchers](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/RSpecMatchers), such as the ones below.
 
 ```ruby
-# bad
-expect(find('[data-testid="submit-review"]')).to have_content(content)
-expect(page).to have_selector('[data-testid="submit-review"]')
-
 # good
 expect(page).to have_button 'Submit review'
+expect(page).to have_button 'Submit review', disabled: true
+expect(page).to have_button 'Notifications', class: 'is-checked' # assert the "Notifications" GlToggle is checked
 
 expect(page).to have_link 'UI testing docs'
 expect(page).to have_link 'UI testing docs', href: docs_url # assert the link has an href
 
 expect(page).to have_field 'Search projects'
+expect(page).to have_field 'Search projects', disabled: true
 expect(page).to have_field 'Search projects', with: 'gitlab' # assert the input field has text
 
 expect(page).to have_checked_field 'Checkbox label'
@@ -443,8 +446,40 @@ expect(page).to have_select 'Sort by', with_options: ['Created date', 'Due date'
 
 expect(page).to have_text 'Some paragraph text.'
 expect(page).to have_text 'Some paragraph text.', exact: true # assert exact match
+
+expect(page).to have_current_path 'gitlab/gitlab-test/-/issues'
+
+expect(page).to have_title 'Not Found'
+
+# acceptable when a more specific matcher above is not possible 
+expect(page).to have_css 'h2', text: 'Issue title'
+expect(page).to have_css 'p', text: 'Issue description', exact: true
+expect(page).to have_css '[data-testid="weight"]', text: 2
+expect(page).to have_css '.atwho-view ul', visible: true
+```
+
+##### Other useful methods
+
+After you retrieve an element using a [finder method](#finders), you can invoke a number of
+[element methods](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Element)
+on it, such as `hover`.
+
+Capybara tests also have a number of [session methods](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Session) available, such as `accept_confirm`.
+
+Some other useful methods are shown below:
+
+```ruby
+refresh # refresh the page
+
+send_keys([:shift, 'i']) # press Shift+I keys to go to the Issues dashboard page
+
+current_window.resize_to(1000, 1000) # resize the window
+
+scroll_to(find_field('Comment')) # scroll to an element
 ```
 
+You can also find a number of GitLab custom helpers in the `spec/support/helpers/` directory.
+
 #### Live debug
 
 Sometimes you may need to debug Capybara tests by observing browser behavior.