QA/Automation/Projects/Mozmill Shared Modules/API Refactor

From MozillaWiki
Jump to: navigation, search


Lead: Henrik Skupin, Dave Hunt
Co-workers: David Guo
Status: Active
Repository Location: Github
Tracking Bug / Bug List: bug 605343 Tracking Bug for API Refactor
Documentation: Internal

Project details

We're exploring different ways to structure and present both Shared APIs and tests. Some values we're optimizing for are:

  • Low learning ramp for writing Mozmill tests
  • Understandable and verifiable test code
  • Repeatable and accurate test runs

Initial ideas center around creating a custom "testing language" by splitting the Shared API into two classes of modules:

  • API modules contain functions for completing complex tasks
  • UI modules contain a map of the Firefox UI used for per-control access.

API modules would be primarily used in setup for tests where fine control isn't needed. UI modules would be used to simulate a QA Engineer running a test.

Some initial ideas for what we're targeting can be found in:

Project Plan


Our goal by end of Q1 2011 is to complete a pilot of the new shared module libraries within the Mozmill team.

Assuming no major problems unearthed during the pilot, we will be able to move forward with migration and further community rampup during Q2.

Use Case Scope

At the end of Q1 2011, the refactored shared module library should be sufficient to cleanly and efficiently implement tests involving the following elements:

  • The entire main Firefox window, especially:
    • Tabbed browsing
    • Location Bar
    • Bookmarks Bar
  • Multiple browser windows/non-modal dialogs in parallel
  • Modal dialogs, such as Preferences
  • Test and synchronization statements such as:
    • Fatal assertions
    • WaitFors

Module Scope

From a modular point of view, the shared modules can be roughly broken down into the UI Map and General Modules.

The UI Map includes proxy objects for individual XUL controls, so that a hierarchical representation of the UI layout can be created. This map will largely replace direct access of the Mozmill controller for UI operations.

General Modules are those that provide higher level utility services, test control statements, or wrap Mozilla Platform back end services.

UI Map

The UI Map is expected to cover the following scope, in priority order. While basic classes will be established for all controls, controls in italics are unlikely to be fully developed in Q1 2011.

For more reference on these controls please see the MDC XUL Control Reference.

  1. Base classes to enable proxy binding
  2. TextBox
  3. Button
  4. Description
  5. Label
  6. ToolbarButton
  7. MenuList
  8. Checkbox
  9. Radio
  10. ListBox
  11. ProgressMeter
  12. Tree
  13. RichListBox
  14. Menus
  15. Image
  16. Scale
  17. Groupbox
  18. Colorpicker
  19. Datepicker
  20. Timepicker

General Modules

The General Modules are expected to cover the following scope in priority order. Modules in italics are unlikely to be developed in Q1 2011.

  1. Assertions
  2. WaitFors
  3. Services
  4. Window Handlers (Match current functionality)
    • Modal
    • Non-Modal
    • Multiple Parallel
  5. Localization (Match current functionality)
  6. Module Initialization Functions
  7. Teardown helper functions
    • UI Reset
    • History Reset
    • Bookmarks Reset
  8. Preferences handling
  9. Screenshots
  10. Localization (Improve functionality)
  11. Window Handlers (Improve functionality)
    • Modal
    • Non-Modal
    • Multiple Parallel

Additional Firefox-specific helper functions will also be created as we encounter the need while migrating tests.

Development Flow

This project is loosely structured as an Agile project, starting with one week sprints.

Because of the distributed nature of the development team and the differing development concerns, UI Map development and General Module development will follow somewhat different flows within their sprints, as detailed below.

Milestones have been defined. When each milestone is reached, shared module structure will be reviewed for acceptance and possibly refactored to pay back any development debt incurred during the sprints.

Completion for any library module means done to the point of accomodating current common test scenarios, with sufficient structure and patterns established to add new scenarios as they occur.

Completion also includes creation of documentation and unit tests exercising each module.

UI Map

At the beginning of each sprint, a number of existing Mozmill tests will be chosen, concentrating on those that rely on the highest priority control remaining on the queue above.

These tests will be ported to the library, adding functionality to the UI Map as needed by the tests.

General Modules

At the beginning of each sprint, one or more modules will be chosen from the queue above.

The current Mozmill code will be surveyed to come up with an individual scope for that module (e.g., which assertions are currently used, what teardown functionality is needed).

The module will be developed to that level of functionality.

It is likely these modules will also be expanded as needed by the test porting detailed above.


Milestones are provided both to meter progress and to synchronize development between the two tracks. All portions of any given milestone should be reached prior to moving on to the next milestone.

Milestone 1

Completion of:

  • UI Map
    • Base classes to enable proxy binding
  • General
    • Assertions
    • WaitFors
    • Services
  • Review and Refactor

Milestone 2

Completion of:

  • UI Map
    • TextBox
    • Button
    • Description
    • Label
  • General
    • Window Handlers
    • Localization
    • Preferences handling
  • Review and Refactor

Milestone 3

Completion of:

  • UI Map
    • ToolbarButton
    • MenuList
    • Checkbox
    • Radio
  • General
    • Module Init
    • Teardown Helpers
  • Review and Refactor

Milestone 4

Completion of:

  • UI Map
    • ListBox
    • ProgressMeter
    • Tree
  • General
  • Review and Refactor
  • Planning
    • Team-wide Pilot Plan

Milestone 5

Completion of Team-wide Pilot


Sprint 1, week ending Feb 11th, 2011

  • bug 630387 Tracking Bug
    • [DONE] Investigate doc-gen
    • [MISSED] Document Element
    • [DONE] Document XmlElement
    • [MISSED] Document HtmlXulElement
    • [DONE] Document HtmlElement
    • [DONE] Document HtmlRegion
    • [DONE] Document XulElement
    • [DONE] Document XulRegion

Sprint 2, week ending Feb 25th, 2011

  • bug 634111 Tracking Bug
    • [CARRY OVER] Document Element
    • [CARRY OVER] Document HtmlXulElement
    • [DONE] Implementation of an assertion module
    • [DONE] Implementation of a services module
    • [MISSED] Porting testBackForwardButtons.js
    • [MISSED] Porting testStopReloadButtons.js

Sprint 3, week ending Mar 11th, 2011

  • [DONE] bug 634227 Implementation of a driver module
  • [DONE] bug 638967 Review/Refactor for Milestone 1
    • [DONE] bug 638969 Change naming of widget class tree
    • [DONE] bug 638970 Change acronym caps in widgets.js
    • [DONE] bug 638971 Change to aParam standard
    • [DONE] bug 638973 Change widgets.js doc tags to leaner version
    • [DONE] bug 638975 Remove controller getter from Element
    • [DONE] bug 638976 Remove XML class tree
    • [DONE] bug 638979 Expose controller.MouseEvent
    • [DONE] bug 638974 Get rid of definition list formatting for params
    • [DONE] bug 639787 Add sleep() to driver module
    • [DONE] bug 640051 Align naming of multiword modules
    • [DONE] bug 640055 Move all files to var modulename = exports style
    • [DONE] bug 640057 Change regions so that browser sets their tag
    • [DONE] bug 640058 Element._locateElem() should throw an error
    • [DONE] bug 640060 Lowercase module objects
  • [MISSED] Porting testBackForwardButtons.js
  • [MISSED] Porting testStopReloadButtons.js

Sprint 4, week ending Mar 25th, 2011