Document click_ vs. go_to_ standard for e2e testsqa/document_click_vs_go_to

Closes https://gitlab.com/gitlab-org/gitlab-ce/issues/59645.

2 files changed, 47 insertions, 0 deletions

diff --git a/qa/README.md b/qa/README.md
index 7d66f7d5abc..9517d4f42b4 100644
--- a/qa/README.md
+++ b/qa/README.md
@@ -48,6 +48,7 @@ will need to [modify your GDK setup](https://gitlab.com/gitlab-org/gitlab-qa/blo
 ### Writing tests
 
 1. [Using page objects](qa/page/README.md)
+2. [Style guide](STYLE_GUIDE.md)
 
 ### Running specific tests
 
diff --git a/qa/STYLE_GUIDE.md b/qa/STYLE_GUIDE.md
new file mode 100644
index 00000000000..f85e7492409
--- /dev/null
+++ b/qa/STYLE_GUIDE.md
@@ -0,0 +1,46 @@
+# Style guide for writing GUI tests
+
+This document describes the conventions used at GitLab for writing GUI tests using the GitLab QA project.
+
+## `click_` versus `go_to_`
+
+### When to use `click_`?
+
+When clicking in a single link to navigate, use `click_`.
+
+E.g.:
+
+```ruby
+def click_ci_cd_pipelines
+  within_sidebar do
+    click_element :link_pipelines
+  end
+end
+```
+
+From a testing perspective, if we want to check that clicking a link, or a button (a single interaction) is working as intended, we would want the test to read as:
+
+- Click a certain element
+- Verify the action took place
+
+### When to use `go_to_`?
+
+When interacting with multiple elements to go to a page, use `go_to_`.
+
+E.g.:
+
+```ruby
+def go_to_operations_environments
+  hover_operations do
+    within_submenu do
+      click_element(:operations_environments_link)
+    end
+  end
+end
+```
+
+`go_to_` fits the definition of interacting with multiple elements very well given it's more of a meta-navigation action that includes multiple interactions.
+
+Notice that in the above example, before clicking the `:operations_environments_link`, another element is hovered over.
+
+> We can create these methods as helpers to abstrac multi-step navigation.
\ No newline at end of file