Merge branch 'doc-qa-doc-element-guidelines' into 'master'

Add documentation for element naming conventions

See merge request gitlab-org/gitlab-ce!28563

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
 

qa/docs/BEST_PRACTICES.md → 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).

qa/docs/GUIDELINES.md → qa/docs/guidelines.md

-# Style guide for writing GUI tests
+# Style guide for writing E2E tests
 
-This document describes the conventions used at GitLab for writing GUI tests using the GitLab QA project.
+This document describes the conventions used at GitLab for writing E2E tests using the GitLab QA project.
 
 ## `click_` versus `go_to_`
 
@@ -44,3 +44,54 @@ end
 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`
+  - `_field`
+  - `_checkbox`
+  - `_radio`
+  - `_content`
+  
+*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
+  element :username_field
+  element :issue_title_content
+end
+```
+
+**Bad**  
+```ruby
+view '...' do  
+  # `_confirmation` should be `_field`. what sort of confirmation? a checkbox confirmation? no real way to disambiguate.
+  # an appropriate replacement would be `element :password_confirmation_field`
+  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
+```

qa/docs/WRITING_TESTS_FROM_SCRATCH.md → 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.