Add documentation for element naming conventionsdoc-qa-doc-element-guidelines

Refactor all capital files to lowercase

5 files changed, 103 insertions, 53 deletions

diff --git a/qa/README.md b/qa/README.md
index 002ad4c65f5..f75205133e6 100644
--- a/qa/README.md
+++ b/qa/README.md
@@ -49,10 +49,10 @@ will need to [modify your GDK setup](https://gitlab.com/gitlab-org/gitlab-qa/blo
 
 ### Writing tests
 
-- [Writing tests from scratch tutorial](docs/WRITING_TESTS_FROM_SCRATCH.md)
-    - [Best practices](docs/BEST_PRACTICES.md)
+- [Writing tests from scratch tutorial](docs/writing_tests_from_scratch.md)
+    - [Best practices](docs/best_practices.md)
     - [Using page objects](qa/page/README.md)
-    - [Guidelines](docs/GUIDELINES.md)
+    - [Guidelines](docs/guidelines.md)
 
 ### Running specific tests
 
diff --git a/qa/docs/GUIDELINES.md b/qa/docs/GUIDELINES.md
deleted file mode 100644
index 9db52cd07e6..00000000000
--- a/qa/docs/GUIDELINES.md
+++ /dev/null
@@ -1,46 +0,0 @@
-# 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 abstract multi-step navigation.
diff --git a/qa/docs/BEST_PRACTICES.md b/qa/docs/best_practices.md
index 3a2640607e4..d6e5350b0c8 100644
--- a/qa/docs/BEST_PRACTICES.md
+++ b/qa/docs/best_practices.md
@@ -35,4 +35,4 @@ Finally, interacting with the application only by its GUI generates a higher rat
 - Building state through the GUI is time consuming and it's not sustainable as the test suite grows.
 - When depending only on the GUI to create the application's state and tests fail due to front-end issues, we can't rely on the test failures rate, and we generates a higher rate of test flakiness.
 
-Now that we are aware of all of it, [let's go create some tests](./WRITING_TESTS_FROM_SCRATCH.md).
+Now that we are aware of all of it, [let's go create some tests](writing_tests_from_scratch.md).
diff --git a/qa/docs/guidelines.md b/qa/docs/guidelines.md
new file mode 100644
index 00000000000..3271e96f372
--- /dev/null
+++ b/qa/docs/guidelines.md
@@ -0,0 +1,96 @@
+# Style guide for writing E2E tests
+
+This document describes the conventions used at GitLab for writing E2E 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 abstract multi-step navigation.
+
+### Element Naming Convention
+
+When adding new elements to a page, it's important that we have a uniform element naming convention.
+
+We follow a simple formula roughly based on hungarian notation.
+
+*Formula*: `element :<descriptor>_<type>`
+
+- `descriptor`: The natural-language description of what the element is. On the login page, this could be `username`, or `password`.
+- `type`: A physical control on the page that can be seen by a user.
+  - `_button`
+  - `_link`
+  - `_tab`
+  - `_dropdown`
+  - `_text`
+  - `_checkbox`
+  - `_radio`
+  
+*Note: This list is a work in progress. This list will eventually be the end-all enumeration of all available types.
+        I.e., any element that does not end with something in this list is bad form.*
+  
+#### Examples
+
+**Good**  
+```ruby
+view '...' do
+  element :edit_button 
+  element :notes_tab
+  element :squash_checkbox
+end
+```
+
+**Bad**  
+```ruby
+view '...' do
+  # `_field` should be `_text`.  
+  # Per the W3C Spec, field is too vague. `type='password'`, `type='hidden'` etc.
+  element :login_field  
+  
+  # `_confirmation` should be `_text`. what sort of confirmation? a checkbox confirmation? no real way to disambiguate.
+  # an appropriate replacement would be `element :password_confirmation_text`
+  element :password_confirmation
+  
+  element :clone_options
+  
+  # how is this url being displayed? is it a textbox? a simple span?
+  element :ssh_clone_url
+end
+```
diff --git a/qa/docs/WRITING_TESTS_FROM_SCRATCH.md b/qa/docs/writing_tests_from_scratch.md
index a6daffc964e..68463c5bdd3 100644
--- a/qa/docs/WRITING_TESTS_FROM_SCRATCH.md
+++ b/qa/docs/writing_tests_from_scratch.md
@@ -8,7 +8,7 @@ In this tutorial, you will find different examples, and the steps involved, in t
 
 It's important to understand that end-to-end tests of isolated features, such as the ones described in the above note, doesn't mean that everything needs to happen through the GUI.
 
-If you don't exactly understand what we mean by **not everything needs to happen through the GUI,** please make sure you've read the [best practices](./BEST_PRACTICES.md) before moving on.
+If you don't exactly understand what we mean by **not everything needs to happen through the GUI,** please make sure you've read the [best practices](best_practices.md) before moving on.
 
 ## This document covers the following items:
 
@@ -279,7 +279,7 @@ In the `before :all` block we create all the application state needed for the te
 
 ### 6. Optimization
 
-As already mentioned in the [best practices](./BEST_PRACTICES.md) document, end-to-end tests are very costly in terms of execution time, and it's our responsibility as software engineers to ensure that we optimize them as max as possible.
+As already mentioned in the [best practices](best_practices.md) document, end-to-end tests are very costly in terms of execution time, and it's our responsibility as software engineers to ensure that we optimize them as max as possible.
 
 > Differently than unit tests, that exercise every little piece of the application in isolation, usually having only one assertion per test, and being very fast to run, end-to-end tests can have more actions and assertions in a single test to help on speeding up the test's feedback since they are much slower when comparing to unit tests.
 
@@ -377,4 +377,4 @@ Now, let's go back to our examples.
 
 #### Adding testability
 
-TBD.
\ No newline at end of file
+TBD.