QA/Mozmill Test Automation/Test Modules Refactor/Style Guide

Mozmill Style Guide v0.1

Goal:

• Write clear code
• Please use good coding practice - see http://neil.rashbrook.org/JS.htm

Exceptions to the Rule:

• If you don't agree with something in this styleguide, or you think something could be done "better", be prepared to explain why
• The styleguide is not written in stone and is open to improvements

Rules:

• Lines of code should not exceed 80 characters (or thereabouts)
• sleep() should never be used in a test, unless absolutely necessary -- try to use waitFor() instead
• Each test file should only contain a single test
• When performing an action on an element, be sure to declare an instance of the element first
• Coding flow should follow a template:
  • MPL > REQUIRES > CONSTANTS > SETUP_MODULE > TEARDOWN_MODULE > TEST
• Use Array.forEach() to iterate array elements
• Use for() to iterate string characters
• License Block
  • If you create a test
    • Initial Author = The Mozilla Foundation, if you are a Mozilla employee
    • Initial Author = YOUR NAME, if you are not a Mozilla employee
  • If you are contributing to a test
    • Add your name and email to the bottom of the contributors list
      

      *   Firstname Lastname <email@domain.com>

• Error messages should be positive in nature
  • GOOD: Expected the notification bar to be visible
  • BAD: Didn't find a notification bar
• There should be no whitespace at the end of a line
• In general, all lines should be indented 2 spaces from their parent
• All files should have 1 newline, no more, no less
• If an XPath string needs to be concatenated, split the string on a /
• If anything needs concatenation:
  • the operator should trail the line with one space
  • each line should be left-aligned with the first
• All functions should be named and use camelCase with the opening brace trailing the signature by a single space
• All variables should be named using camelCase
• All constants should be named using ALL_CAPS
• All unchanging variables/values should be declared as constant
• All components should be declared in setupModule()
  • If it needs concatenation, split on the . leaving it on the first line
  • Ideally, necessary component loading should be handled by the appropriate API
• Commenting code should be done inline //
• Commenting functions should be done using JSDoc Toolkit style

Refactor

• Replace gDelay and 100 with DELAY
• Replace gTimeout and 5000 with TIMEOUT
• Replace other timeouts with CONSTANTS
• Replace sleep() parameter with CONSTANT
• Replace unchanging values with CONSTANT
• Move tests from testGeneral into appropriate subfolder
• Encapsulate all test pages in a LOCAL_TEST_PAGES array
• Replace failing waitForEval() with waitFor()
• Make sure proper use of "The Mozilla Foundation" in tests
• Make sure contributor list is aligned on N in Contributor(s)
• Make sure assertion messages are positive
• Remove any trailing whitespace
• Make sure all tests have 1 newline EOF
• Make sure all lines of code respect the 2-space indent rule

To be Added

13. Component declarations should be indented in line with the parent 15. Use waitFor() as much as possible. Only use sleep() when a waitFor() inappropriate or impossible

• 16,17. DELAY/TIMEOUT

    - if 100/5000, remove
    - sleep() use a global const
    - other values use a global const
    * for refactoring only, not in style guide

18/19 - leave out of style guide

    * not needed in refactor

20. Dont use for each() in arrays - strings use traditional for()

• 21. no testGeneral subfolder

    * refactoring only

22. Only one test per file

    - ok for style guide, ignore for refactoring

23. Element before action 24. Local test pages encapsulated in Array 25. Constants between requires and setupModule()

         - MPL > REQ > CONST > SETUP > TEARDOWN > TEST
         - put into a template

27. Use waitFor() when asserting for timeouts

         - leave out of style guide for now
         - refactoring: replace waitForEval() if failing

28. Use traditional for() when iterating characters of a string 29. License block

         - Initial Author: community member (Employee: Mozilla Foundation)
         - Everyone in contributor
         - contributor list in order of contribution

31. waitFor() & assert() error messages

         * refactor: ensure messages are positive
         - style guide: generally mention that error messages should be positive

32. Trailing whitespace

    - no trailing whitespace on a line
    - 2-space indent in general
    - 1 newline at EOF
         

• Please use good coding practice
• Reference http://neil.rashbrook.org/JS.htm
• Point is clear code
• If style guide is "wrong", be prepared to explain why
• Style guide is modular and modifiable