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

Mozmill Style Guide v0.1

Goal: Write clear code

Exceptions: Rules can be broken or modified, however, be prepared to defend your position

Lines of code should not exceed 80 characters (or thereabouts)

Variables

Local variables

• Use camelCase when naming local variables and functions.

  var someVariable = value;

Constants

• Use ALL_CAPS when naming all constants

  const SOME_CONSTANT_VARIABLE  = 'some value';

Unchanging Strings & Numbers

• Any specific strings or numbers should be declared as constants
• In other words, don't use bare strings or numbers in functional code

  const SOME_STRING = 'the string';
    ...
  controller.doSomething(SOME_STRING);

Commenting

Commenting of functional code

• Single line comment describing the purpose of the code
• Comment should be left-aligned with the code block

  // Download a file
  downloads.downloadFileOfUnknownType(controller, URL);

Commenting of functions

• All functions should be preceded with a JSDoc style comment block
• This should include any references to parameters and returns

  /**
   * Clear a user set preference
   *
   * @param {string} prefName
   *        The user-set preference to clear
   *
   * @return False if the preference had the default value
   * @type boolean
   **/
  clearUserPref : function preferences_clearUserPref(prefName) {

• See the JSDoc Toolkit for further information about commenting style

Functions

Function naming

• All functions should be named
• All function names should use camelCase
• Opening brace should follow the function signature by a single space on the same line

  function someFunctionToPerform(param1, paramN) {

Parameter Concatenation

• If a parameter list is too long, it should be concatenated
• The operator (+) should follow the line by a single space
• The string sections should be aligned to the left

  var someVariable = controller.someFunction('some' +
                                             'concatenated' +
                                             'string');

• If the string is an XPath or contains '/', split on the '/'

  var someVariable = controller.someFunction('/some/concatenated' +
                                             '/XPath/string');

Assertions

waitFor()

• Use whenever you are waiting for a particular element to appear

  controller.waitFor(function () {
    return someProperty == 'some value';
  }, "A positive error message about the expected state");

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