Add documentation for element naming conventions

Refactor all capital files to lowercase

Signed-off-by: ddavison <ddavison@gitlab.com>

5 files changed, 104 insertions, 52 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..433e66ec181
--- /dev/null
+++ b/qa/docs/guidelines.md
@@ -0,0 +1,98 @@
+# 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
+
+  # `clone_options` is too vague. If it's a dropdown menu, it should be `clone_dropdown`. 
+  # If it's a checkbox, it should be `clone_checkbox`
+  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 309fcc4064c..65e7a78a8b5 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:
 
@@ -367,7 +367,7 @@ With that in mind, resources can be a project, an epic, an issue, a label, a com
 
 As you saw in the tests' pre-conditions and the optimization sections, we're already creating some of these resources, and we are doing that by calling the `fabricate_via_api!` method.
 
-> We could be using the `fabricate!` method instead, which would use the `fabricate_via_api!` method if it exists, and fallback to GUI fabrication otherwise, but we recommend being explicit to make it clear what the test does. Also, we recommend fabricating resources via API since this makes tests faster and more reliable, unless the test is focusing on the GUI itself, or there's no GUI coverage for that specific part in any other test.
+> We could be using the `fabricate!` method instead, which would use the `fabricate_via_api!` method if it exists, and fallback to GUI fabrication otherwise, but we recommend being explicit to make it clear what the test does. Also, we always recommend fabricating resources via API since this makes tests faster and more reliable.
 
 For our test suite example, the [project resource](https://gitlab.com/gitlab-org/gitlab-ee/blob/d3584e80b4236acdf393d815d604801573af72cc/qa/qa/resource/project.rb#L55) already had a `fabricate_via_api!` method available, while other resources don't have it, so we will have to create them, like for the issue and label resources. Also, we will have to make a small change in the project resource to expose its `id` attribute so that we can refer to it when fabricating the issue.