updating comments and read me

Author: nareshnavinash

Locators/amazon_home_page.py

@@ -1,7 +1,17 @@
 from selpy.locator import Locator
+# Importing the locator method from selpy
 
 
 class AmazonHomePageLocator:
+    # Use the following description for different locators
+    # CSS - 'css selector'
+    # XPATH - 'xpath'
+    # ID - 'id'
+    # NAME - 'name'
+    # LINK TEXT - 'link text'
+    # PARTIAL LINK TEXT - 'partial link text'
+    # TAG NAME - 'tag name'
+    # CLASS NAME - 'class name'
     amazon_logo = Locator("css selector", "div#nav-logo a[aria-label='Amazon']")
     amazon_search_categories = Locator("css selector", "div.nav-search-scope select.nav-search-dropdown")
     amazon_search_categories_text = Locator("css selector", "div.nav-search-facade span")
@@ -11,6 +21,7 @@ class AmazonHomePageLocator:
     def __init__(self):
         print("Locators for Amazon home page")
 
+    # Dynamic locators can be declared as a method with variables.
     @staticmethod
     def amazon_search_category_list(string):
         amazon_search_category_list = Locator("xpath", "//select[contains(@class,'nav-search-dropdown')]//option[text("

Locators/amazon_product_page.py

@@ -2,18 +2,28 @@
 
 
 class AmazonProductPageLocator:
+    # Use the following description for different locators
+    # CSS - 'css selector'
+    # XPATH - 'xpath'
+    # ID - 'id'
+    # NAME - 'name'
+    # LINK TEXT - 'link text'
+    # PARTIAL LINK TEXT - 'partial link text'
+    # TAG NAME - 'tag name'
+    # CLASS NAME - 'class name'
     amazon_deliver_to_link = Locator("css selector", "div#contextualIngressPt")
     amazon_deliver_to_pincode = Locator("css selector", "div.a-column input[aria-label='or enter a pincode']")
     amazon_deliver_to_pincode_apply = Locator("css selector", "div.a-column input.a-button-input")
     amazon_product_page_identifier = Locator("css selector", "div#dp")
     # Product details locator
     amazon_product_title = Locator("css selector", "span#productTitle")
     amazon_product_byline_info = Locator("css selector", "div#bylineInfo")
+    amazon_product_show_more_format = Locator("css selector", "span#showMoreFormatsPrompt")
     amazon_product_formats = Locator("css selector", "div#formats")
     amazon_product_detail_description_iframe = Locator("css selector", "iframe#bookDesc_iframe")
     amazon_product_detail_description = Locator("css selector", "div#iframeContent")
-    amazon_product_offers = Locator("css selector", "div#sopp_feature_div")
     amazon_product_description = Locator("css selector", "div#productDescription_feature_div.a-row")
+    amazon_product_offers = Locator("css selector", "div#sopp_feature_div")
     amazon_product_details = Locator("css selector", "div#detail_bullets_id")
 
     def __init__(self):

Locators/amazon_search_result.py

@@ -2,6 +2,15 @@
 
 
 class AmazonSearchResultLocator:
+    # Use the following description for different locators
+    # CSS - 'css selector'
+    # XPATH - 'xpath'
+    # ID - 'id'
+    # NAME - 'name'
+    # LINK TEXT - 'link text'
+    # PARTIAL LINK TEXT - 'partial link text'
+    # TAG NAME - 'tag name'
+    # CLASS NAME - 'class name'
     amazon_search_result_top_header = Locator("css selector", "div.sg-col-inner div.a-section")
     amazon_search_result_department_see_more = Locator("css selector", "div#departments span.a-expander-prompt")
     amazon_search_sort_by = Locator("css selector", "span.a-dropdown-container")

Pages/amazon_home_page.py

@@ -1,6 +1,7 @@
 from Locators.amazon_home_page import AmazonHomePageLocator
 
 
+# Inherit the locator class inside page class for easier access of locators
 class AmazonHomePage(AmazonHomePageLocator):
 
     def __init__(self):

Pages/amazon_product_page.py

@@ -1,6 +1,7 @@
 from Locators.amazon_product_page import AmazonProductPageLocator
 
 
+# Inherit the locator class inside page class for easier access of locators
 class AmazonProductPage(AmazonProductPageLocator):
 
     def __init__(self):

Pages/amazon_search_result.py

@@ -1,6 +1,7 @@
 from Locators.amazon_search_result import AmazonSearchResultLocator
 
 
+# Inherit the locator class inside page class for easier access of locators
 class AmazonSearchResultPage(AmazonSearchResultLocator):
 
     def __init__(self):

README.md

@@ -4,6 +4,8 @@ Selpy-Python is a Page Object Model (POM) framework for selenium automation with
 
 This framework also uses [selpy](https://pypi.org/project/selpy/) custom built pypi module to implement snapshot feature (which is available in jest framework). If there are any change in UI we can directly change this in the test data file during the test run with ease. Manual maintenance of test data can be reduced drastically with this feature.
 
+More details of this module can be refered in [selpy](https://pypi.org/project/selpy/) or [repo](https://github.com/nareshnavinash/selpy)
+
 
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
 [![Made with Python](https://img.shields.io/badge/Made%20with-Python-yellow.svg)](https://www.python.org/)
@@ -129,7 +131,19 @@ class AmazonHomePageLocator:
         return Locator("xpath", "//select[contains(@class,'nav-search-dropdown')]//option[text()='%s']" % string)
 ```
 
-3. Ideally each web page should have a new file inside locators folder (with the same name as the web page) and all the locators inside a web page has to be declared inside a page class(Class name also should be same as the web page name).
+4. To use the Locator method we need to pass the type of locator and the actual locator element. Type of locator has to be mentioned in the following way to allow `selpy` to process the locator.
+```
+CSS - 'css selector'
+XPATH - 'xpath'
+ID - 'id'
+NAME - 'name'
+LINK TEXT - 'link text'
+PARTIAL LINK TEXT - 'partial link text'
+TAG NAME - 'tag name'
+CLASS NAME - 'class name'
+``` 
+
+5. Ideally each web page should have a new file inside locators folder (with the same name as the web page) and all the locators inside a web page has to be declared inside a page class(Class name also should be same as the web page name).
 * If the web page name is `home page` then the locator file name should be `home_page.rb` inside `locators` folder and the class name should be `HomePageLocator` inside `Locators` module.
 
 ### Adding page methods to the project
@@ -154,7 +168,7 @@ class AmazonHomePage(AmazonHomePageLocator):
         return AmazonHomePageLocator.amazon_logo.is_displayed_with_wait()
 ```
 
-3. Ideally each web page should have a new page file inside `pages` folder with the class name same as the web page name.
+4. Ideally each web page should have a new page file inside `pages` folder with the class name same as the web page name.
 * If the web page name is `home page` then the pages file name should be `home_page.rb` inside `pages` folder and the class name should be `HomePage` inside `Pages` module.
 
 ### Creating a new test file in the project
@@ -194,7 +208,7 @@ Use `allure.step("step name")` to have a detailed reporting in allure.
 
 3. Append the method name for the test as `test_` only then it will be taken as a test case. This has been configured in ```pytest.ini``` as,
 
-```python
+```ini
 markers =
     sanity: sanity tests marker
     regression: regression tests marker
@@ -263,6 +277,14 @@ This ensures that this data has been set before pytest is being invoked only onc
 assert (AmazonHomePage.is_home_page_displayed() is True), "Amazon home page is not displayed"
 ```
 
+### Data sets:
+
+In order to have distinguished set of data I have used three types of data.
+
+**Global** - Global configuration for the whole project. Here mode of run, browsers to use, browser configurations etc., are specified.
+**Test Data** - This is to store the module level data. Ideally for each test file we need to have a test data file, but that depends on the requirement.
+**Dynamic Data** - This is to store the dynamic data. Files in this folder are supposed to change when we run with `snap=1 pytest`. This is separated from the other data files so that other static files are not disturbed during the run.
+
 ## Detailing snap Mode:
 
 Snap mode is created to reduce the burden in maintaining the test data. While we test an application with data heavy validations, there is a high chance that the data in the application may change over the course of time.

Tests/amazon.py

@@ -8,28 +8,30 @@
 from selpy.variable import Var
 
 
+# Feature name and severity to have better reporting in the allure.
 @allure.feature("Amazon - Book search with text 'AI', department as 'Arts, Film & Photography', sub-department as "
                 "'Cinema & Broadcast', maximum 'Avg Customer Review', sort result by 'Publication Date'"
                 "filter as 1000 to 1500 rupees, the book available in paperback, Kindle ebooks, and Hardcover"
                 "select the first result and verify")
 @allure.severity('Critical')
-@pytest.mark.regression
-@pytest.mark.ui
+@pytest.mark.regression  # Custom pytest marker to run the test cases with ease on demand
+@pytest.mark.ui  # Custom pytest marker to run the test cases with ease on demand
 def test_amazon_book_search_001():
     with allure.step("Initialize the UI dynamic data"):
         ui_dynamic_data = {}
     with allure.step("Set the test data file needed for this test run"):
-        static_variable = Var("amazon.yml", "static")
+        static_variable = Var("amazon.yml", "static")  # static variables will change for each test case/ test module
+        # Dynamic variable is to verify the dynamic data in UI, if needed we can store the UI values to this file
         dynamic_variable = Var("amazon_book_search_result_dynamic.yml", "dynamic")
 
     with allure.step("Initialize the driver and navigate to the url"):
-        driver = Driver()
+        driver = Driver() # Initialize the driver. Driver configurations will be taken from the global_data.yml file
         driver.get(static_variable.static_value_for("url"))
         assert (AmazonHomePage.is_home_page_displayed() is True), "Amazon home page is not displayed"
 
     with allure.step("Select the categories as books in the search dropdown"):
         AmazonHomePage.select_category_drop_down(static_variable.static_value_for("category"))
-        assert (AmazonHomePage.get_selected_category() == static_variable.static_value_for("category")),\
+        assert (AmazonHomePage.get_selected_category() == static_variable.static_value_for("category")), \
             "Category is not selected properly"
 
     with allure.step("Search for the text which is needed in this"):
@@ -40,6 +42,7 @@ def test_amazon_book_search_001():
                                                                                           "displayed in the result page"
 
     with allure.step("Apply the filter categories in the search results page"):
+        # applying and verifying the filters applied
         AmazonSearchResultPage.select_department(static_variable.static_value_for("search_department"))
         AmazonSearchResultPage.select_sub_department(static_variable.static_value_for("search_sub_department"))
         list_of_checkbox = static_variable.static_value_for("book_format")
@@ -76,6 +79,7 @@ def test_amazon_book_search_001():
 
     with allure.step("Set the delivery pincode in the product page"):
         AmazonProductPage.set_delivery_pincode(static_variable.static_value_for("delivery_pincode"))
+        # To handle the delay in the UI.
         for i in range(0, 10):
             time.sleep(1)
             res = AmazonProductPage.get_delivery_pincode().find(
@@ -86,22 +90,28 @@ def test_amazon_book_search_001():
         assert (res != -1), "Delivery Pin code is not set properly"
 
     with allure.step("Store the UI details in the dynamic dictionary"):
+        # Now fetch the data which you want to store in the snap way and save it in the ui_dynamic_data dictionary
+        # with the name to it. After saving this to the dictionary/hash, you can compare with the stored data.
         AmazonProductPage.amazon_product_title.scroll_to_locator()
         ui_dynamic_data["amazon_product_title"] = AmazonProductPage.amazon_product_title.texts_as_string()
         AmazonProductPage.amazon_product_byline_info.scroll_to_locator()
         ui_dynamic_data["amazon_product_byline_info"] = AmazonProductPage.amazon_product_byline_info.texts_as_string()
+        AmazonProductPage.amazon_product_show_more_format.click()
         AmazonProductPage.amazon_product_formats.scroll_to_locator()
         ui_dynamic_data["amazon_product_formats"] = AmazonProductPage.amazon_product_formats.texts_as_string()
         driver.switch_to_frame(AmazonProductPage.amazon_product_detail_description_iframe.get_element())
-        ui_dynamic_data["amazon_product_detail_description"] = AmazonProductPage.\
+        ui_dynamic_data["amazon_product_detail_description"] = AmazonProductPage. \
             amazon_product_detail_description.texts_as_string()
         driver.switch_to_default_content()
-        AmazonProductPage.amazon_product_offers.scroll_to_locator()
-        ui_dynamic_data["amazon_product_offers"] = AmazonProductPage.amazon_product_offers.texts_as_string()
         AmazonProductPage.amazon_product_description.scroll_to_locator()
         ui_dynamic_data["amazon_product_description"] = AmazonProductPage.amazon_product_description.texts_as_string()
+        # Intentionally adding following two details which are vulnerable to change dynamically.
+        # While running `snap=1 pytest` first time it will fail and next time it should pass
+        AmazonProductPage.amazon_product_offers.scroll_to_locator()
+        ui_dynamic_data["amazon_product_offers"] = AmazonProductPage.amazon_product_offers.texts_as_string()
         AmazonProductPage.amazon_product_details.scroll_to_locator()
         ui_dynamic_data["amazon_product_details"] = AmazonProductPage.amazon_product_details.texts_as_string()
 
     with allure.step("Compare the dynamic value from UI with the stored file"):
+        # Now compare the UI value with the stored value. This comparison is taken care in `selpy` module.
         dynamic_variable.compare(ui_dynamic_data)

Tests/conftest.py

@@ -11,6 +11,7 @@ def before_each():
     print('*-* Before each INITIALIZATION')
     try:
         yield
+        # After each test case taking screen shots form the available drivers
         for driver in Store.drivers:
             root_dir = os.path.dirname(os.path.abspath(__file__)).replace("/Tests", "")
             name = 'img%s.png' % datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
@@ -26,6 +27,7 @@ def before_each():
 def before_module():
     print('*-* Before module INITIALIZATION')
     yield
+    # after each module ensuring the browsers are closed
     for driver in Store.drivers:
         driver.quit()
     print('*-* After module END')
@@ -38,11 +40,13 @@ def pytest_configure(config):
     file after command line options have been parsed.
     """
     print("*-* pytest_configure")
+    # Configuring the selpy with data path location
     Store.global_data_path = os.path.dirname(
         os.path.abspath(__file__)).replace("/Tests", "") + '/Data/GlobalData/global_data.yml'
     Store.static_data_path = os.path.dirname(os.path.abspath(__file__)).replace("/Tests", "") + '/Data/TestData/'
     Store.dynamic_data_path = os.path.dirname(os.path.abspath(__file__)).replace("/Tests", "") + '/Data/DynamicData/'
     root_dir = os.path.dirname(os.path.abspath(__file__)).replace("/Tests", "")
+    # Clearing the old screenshots from the location.
     config_path = root_dir + '/reports/screenshots/*.png'
     for CleanUp in glob.glob(config_path):
         print(CleanUp)