MozillaWiki

QA/Execution/Web Testing/Docs/Automation/StyleGuide: Difference between revisions

Page Discussion

QA/Execution/Web Testing/Docs/Automation/StyleGuide (view source)

Revision as of 16:13, 10 November 2015

4,159 bytes added ,  10 November 2015
Undo revision 1105014 by Jlorenzo (talk) - I edited the wrong page
(Created page with "The goal of the style guide is to try write code that looks the same no matter what project. It is a guide and is always up for discussion by the team. I have created templates (...")
 
(Undo revision 1105014 by Jlorenzo (talk) - I edited the wrong page)
 
(47 intermediate revisions by 6 users not shown)
Line 1: Line 1:
The goal of the style guide is to try write code that looks the same no matter what project. It is a guide and is always up for discussion by the team. I have created templates (https://github.com/AutomatedTester/mozwebqa-test-templates) based on the details below and will update as the discussion goes on.
The goal of the style guide is to try provide rules to write code that looks the same no matter what project. It is a guide and is always up for discussion by the team.
All Files
File headers


    At the top of each file should have python file header  #!/usr/bin/env python
= All Files =


    Each file should have a copy of the MPL http://www.mozilla.org/MPL/boilerplate-1.1/mpl-tri-license-sh
== File Headers ==
* Each file should have a completed copy of the [http://www.mozilla.org/MPL/2.0/ MPL2] license block, immediately followed by an empty line.
* Each file should pass [http://www.python.org/dev/peps/pep-0008/ PEP8] except for line length, see below. 


    Each file should pass PEP8 except for line length, see below. 
<source lang="python">
# Good
def method(self, parameter)


    I.e. parameters  should have a comma and a space e.g.  def method(self, parameter) not def method(self,parameter), etc
# Bad
def method(self,parameter)
</source>


    http://www.python.org/dev/peps/pep-0008/
* Lines should try not to have more than 100 characters.
* Docstrings should conform to [http://www.python.org/dev/peps/pep-0257/ PEP0257] and should be on a single line wherever possible.


    Lines should try not to have more than 100 characters. This allows 2 files to be side by side with no overlap for easier development.(I base this on MacVim on my MBP)
<source lang="python">
# Good
def click_login():
"""Clicks the login link."""


    Indenting should be a soft tab(4 spaces) as common with in Python. Do not mix tabs and spaces
# Bad
def click_login():
"""
Clicks the login link.
"""
</source>


    My VIM settings https://github.com/AutomatedTester/VimSettings
Where not possible, the first line should be a summary.


    There should be no whitespace at the end of the file(as per PEP8)
<source lang="python">
# Good
def login():
"""Logs in.


    Comments should be on the line above. Remember to update comments when changing code so that code matches the comments.
Clicks the login link and then waits for the home page to load.


    Class names should be in Pascal style as this is Python idiomatic
"""


    Good: class TestThisSite(unittest.TestCase):
# Bad
def login():
"""Logs in.
Clicks the login link and then waits for the home page to load."""
</source>


    Bad: class test_this_site(unittest.TestCase):
* Indenting should be a soft tab (4 spaces) as common with in Python. Do not mix tabs and spaces!
* There should be no whitespace at the end of the file (as per PEP8).
* Comments should be on the line above. Remember to update comments when changing code so that code matches the comments.
* Class names should be in Pascal style as this is Python idiomatic.


Page Object Style Guide
<source lang="python">
# Good
class TestThisSite:
   
# Bad
class test_this_site:
</source>
 
= Page Objects =
 
== General ==
* All page objects should inherit from <code>Page</code> in page.py.
* Page objects should not do asserts. This should be done within the test.
* Each page should be grouped within one module.
* If using multiple words to describe a module separate them with underscores '_'
* Timeout time should be taken from pytest-mozwebqa via <code>page.py's</code> timeout property.
* Single quotes (') should be used instead of double (") throughout.
* Methods should have a single purpose.
 
== Logic ==
* Methods should not contain logic that depends on properties of the page. The logic and expectations should be within the test, and adding this to the page object could guard your tests against genuine failures.


     All Page Objects should inherit from Page in page.py
<source lang="python">
# Good
def click_login(self)
     self.selenium.find_element(*self._login_locator).click()


     Page Objects should not do asserts. This should be done within the test
# Bad
def click_login(self)
     if not self.is_user_logged_in:
        self.selenium.find_element(*self._login_locator).click()
    else:
        pass
</source>


    Each Page should be grouped within one module
== Locators ==
* Locator variables should be prefixed with <code>_</code> to show that it is [http://docs.python.org/tutorial/classes.html#private-variables private].
* Variables should be descriptive of the area and not clash with any properties.
* Should have a suffix of <code>_locator</code>.
* Accessing locators should be done through a property or method as this keeps the locator as read-only.


     If using mutliple words to describe a module separate them with underscores '_'
<source lang="python">
@property
def search_term(self):
     return self.selenium.find_element(*self._search_box_locator).value
</source>


    timeout time should be taken from vars.py
* We should use locators in the following order of preference (there will be exceptions):
** ID
** Name
** Class name
** CSS selector
** XPath
* CSS locators should use whitespace for readability when using direct descendants.


Locators Class Variables
<source lang="python">
# Good
_my_locator = "css=#content > p > a"
   
# Bad
_my_locator = "css=#content>p>a"
</source>


    Locator variables should be prefixed with _ to show that it is "private"(http://docs.python.org/tutorial/classes.html#private-variables)
* Use Python tuples to define locators:


    Variables should be descriptive of the area and not clash with any properties
<source lang="python">
# Good
_my_locator = (By.ID, "content")
</source>


    Suffix of _locator?
== Actions ==
* Methods that perform actions on the page should indicate the action in the method name.


Accessing Locator Variables
<source lang="python">
# Good
def click_report_with_length(length)


    Accessing Locators should be done through a property method as this keeps the locator as readonly.
# Bad
def report_length(length)
</source>


   
* Actions should wait for the appropriate action to complete. This could be an implicit or explicit wait. For example, clicking a login button might explicitly wait for a username field to be visible.
    @property
 
    def search_box(self):
== Advanced: Page Regions ==
        return self.search_box_locator
In some circumstances, for example where a header/navigation is common across the website, we will use a page region. The page region is a child class of the base Page object, which is inherited by all page objects. This means that the navigation can be reached from any page object and herein lies the DRY!
       
 
A brief example:


    This approach can also be used with get_* calls with Selenium making it more idiomatic for the call.
<source lang="python">
class BasePage(Page):


     @property
     @property
     def page_title(self):
     def header(self):
         return self.selenium.get_title()
         return BasePage.HeaderRegion(self.testsetup)
Action methods
   
    class HeaderRegion(Page):
 
        _login_link = (By.ID, "home")


    Methods that perform actions on the page should indicate the action in the method name
        @def click_login(self):
            self.selenium.find_element(*self._login_link).click()
</source>


    GOOD: def click_report_with_length(length)
Referring to this page region with a property makes it very readable and concise from within the test. Clicking login during a test would be performed like this:
<source lang="python">
my_page.header.click_login()
</source>


    BAD: def report_length(length)
Another example where this might be used is on a search results page, the page region being the search results element.


Test Style Guide
= Tests =
* Module names should be called test_ and then behavioral areas.
    test_search.py
* Test method signature should include mozwebqa to use pytest-mozwebqa plugin.


    Module names should be called test_ and then behavioural areas. E.g. test_search_positive.py
<source lang="python">
def test_example(self, mozwebqa):
</source>


    Selenium setup should read in details from vars.py
* Test method names should always show the intent of the test case.


    Test Case names should always show the intent of the test case.
<source lang="python">
# Good
def test_that_advanced_search_does_not_find_item(self, mozwebqa):


    GOOD: def test_that_advanced_search_doesnt_find_item(self):
# Bad
def test_advanced_search(self, mozwebqa):
</source>


    BAD: def test_advanced_search(self):
== Assertions ==


    CAVEAT: setUp and tearDown are exceptions to the rule as they are needed for unittest
* Tests should handle the asserts -- not the page objects.
* Tests should use Python's native [https://docs.python.org/2/reference/simple_stmts.html#the-assert-statement assert] statement.
** Note that this is a change from our previous standard of using the [https://wiki.mozilla.org/Web_Testing/Automation/UnittestZero UnittestZero] package.
* When doing equivalency assertions, put the expected value first, followed by the actual value, for example:
<source lang="python">
assert 'expected' == 'actual'  # good
assert 'actual' == 'expected'  # bad
</source>
* When doing negative equivalency, use != and put the unexpected value first, followed by the actual value, for example:
<source lang="python">
assert 'unexpected' != 'actual'  # good
assert 'actual' != 'unexpected'  # bad
</source>
* To directly cause a test to fail raise an AssertionError with an appropriate message, for example:
<source lang="python">
raise AssertionError('message')
</source>
* See [http://pytest.org/latest/assert.html pytest's documentation on asserts] for more help.


    Tests should handle the asserts not the Page objects
= Size of patches =
To make sure that we can review your patch as quickly and efficiently as possibly we would like patches to have a single test in them and the necessary changes to the page objects. This also limits the chances of merge conflicts later.


    Every Test module will have an main() function caller
== Using new and old standards together ==
As we (and Selenium and automation) develop more knowledge some projects might fall behind the standards in this style guide. It can be tempting to want to fix all of the outdated style but in order to keep patches/pulls small (see above!) we are happy to have new and old standards of code sit side by side. As we regularly review and update tests the project will be brought completely up to our current standards.


        if __name__ == "__main__":
Or if you prefer, log a GitHub issue to have a section of code addressed separately to the job you are doing.
            unittest.main()
Jlorenzo
Confirmed users
213

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/272864...1105022"