Merge pull request #48 from kaiserk/a-little-more-description

Added pydocs and comments to clarify the intent of the code

source/page-objects.rst

@@ -31,18 +31,29 @@ and ensure some results are found.
   import page
 
   class PythonOrgSearch(unittest.TestCase):
+      """A sample test class to show how page object works"""
 
       def setUp(self):
           self.driver = webdriver.Firefox()
           self.driver.get("http://www.python.org")
 
       def test_search_in_python_org(self):
+          """
+          Tests python.org search feature. Searches for the word "pycon" then verified that some results show up.
+          Note that it does not look for any particular text in search results page. This test verifies that
+          the results were not empty.
+          """
+
+          #Load the main page. In this case the home page of Python.og.
           main_page = page.MainPage(self.driver)
+          #Checks if the word "Python" is in title
           assert main_page.is_title_matches(), "python.org title doesn't match."
-	  main_page.search_text_element = "pycon"
-	  main_page.click_go_button()
+          #Sets the text of search textbox to "pycon"
+          main_page.search_text_element = "pycon"
+          main_page.click_go_button()
           search_results_page = page.SearchResultsPage(self.driver)
-	  assert search_results_page.is_results_found(), "No results found."
+          #Verifies that the results page is not empty
+	      assert search_results_page.is_results_found(), "No results found."
 
       def tearDown(self):
           self.driver.close()
@@ -59,29 +70,37 @@ The ``page.py`` will look like this::
   from locators import MainPageLocators
 
   class SearchTextElement(BasePageElement):
+      """This class gets the search text from the specified locator"""
 
+      #The locator for search box where search string is entered
       locator = 'q'
 
 
   class BasePage(object):
+      """Base class to initialize the base page that will be called from all pages"""
 
       def __init__(self, driver):
           self.driver = driver
 
 
   class MainPage(BasePage):
+      """Home page action methods come here. I.e. Python.org"""
 
+      #Declares a variable that will contain the retrieved text
       search_text_element = SearchTextElement()
 
       def is_title_matches(self):
+          """Verifies that the hardcoded text "Python" appears in page title"""
           return "Python" in self.driver.title
 
       def click_go_button(self):
+          """Triggers the search"""
           element = self.driver.find_element(*MainPageLocators.GO_BUTTON)
           element.click()
 
 
   class SearchResultsPage(BasePage):
+      """Search results page action methods come here"""
 
       def is_results_found(self):
           # Probably should search for this text in the specific page
@@ -97,14 +116,17 @@ The ``element.py`` will look like this::
 
 
   class BasePageElement(object):
+      """Base page class that is initialized on every page object class."""
 
       def __set__(self, obj, value):
+          """Sets the text to the value supplied"""
           driver = obj.driver
           WebDriverWait(driver, 100).until(
               lambda driver: driver.find_element_by_name(self.locator))
           driver.find_element_by_name(self.locator).send_keys(value)
 
       def __get__(self, obj, owner):
+          """Gets the text of the specified object"""
           driver = obj.driver
           WebDriverWait(driver, 100).until(
               lambda driver: driver.find_element_by_name(self.locator))
@@ -119,7 +141,9 @@ The ``locators.py`` will look like this::
   from selenium.webdriver.common.by import By
 
   class MainPageLocators(object):
+      """A class for main page locators. All main page locators should come here"""
       GO_BUTTON = (By.ID, 'submit')
 
   class SearchResultsPageLocators(object):
+      """A class for search results locators. All search results locators should come here"""
       pass