UI Automation tool for Mozilla applications
[Mozmill](https://developer.mozilla.org/en/Mozmill) is a test tool and UI automation framework for writing tests and other automation scripts for Gecko based applications like Firefox and Thunderbird. It’s built as a [python](http://python.org) command-line tool. The python package provides a mechanism for running the tests from the command line as well as providing a way to test restarting the application. Mozmill has an extensive API to help you write functional tests that simulate user interactions.
The [Mozmill test automation project](https://wiki.mozilla.org/QA/Mozmill_Test_Automation) was started in January 2009 and covers the automation work for Firefox. Checkout the [project page](https://wiki.mozilla.org/QA/Mozmill_Test_Automation) or have a look at the [Mozmill Tests documentation](https://developer.mozilla.org/en/Mozmill_Tests) to get an impression of how to contribute in writing and running [Mozmill tests](https://developer.mozilla.org/en/Mozmill_Tests). Existing tests get run in the [release testing](https://developer.mozilla.org/en/Mozmill/Release_Testing) cycle for new major or security releases of Firefox.
Also the Mozilla Messaging team has an active project which handles [Thunderbird Testing with Mozmill](https://developer.mozilla.org/en/Thunderbird/Thunderbird_MozMill_Testing).
Mozmill is available as a python package. See [the installation page](./Installation) for instructions for how to get Mozmill set up on your system.
# Python Client
The [Mozmill python package](http://pypi.python.org/pypi/mozmill) invokes and runs a Gecko application, performs automatic test scripting, and accumulates and reports results.
## Running the command line client
After [installing](./Installation) the python package you can run Mozmill with the \(mozmill\) command. The \(mozmill\) command is run with one or more test (\(-t mytest.js\)) or test manifest (\(-m manifest.ini\)):
mozmill -m functional_tests.ini mozmill -t mytest.js -t myothertest.js
\(mozmill --help\) displays the available command-line options and more in-depth information about the command line utility. For the format and usage of test manifests, see http://hg.mozilla.org/automation/ManifestDestiny/file/tip/README.txt .
## Control flow
The Mozmill python package bundles the Mozmill and [jsbridge](./jsbridge) extensions into a profile on invocation.
Mozmill is run like:
mozmill -app firefox -b path/to/binary -t path/to/test.js [options]
This will do the following:
## Example API Usage
Since Mozmill 2.0, the [MozMill class](https://github.com/mozilla/mozmill/blob/master/mozmill/mozmill/__init__.py) is usable as a robust API. An example API usage is available at https://github.com/mozilla/mozmill/tree/master/mozmill .
Python Mozmill is a test harness and an event dispatcher.
The Mozmill python package is built of a number of different package dependencies:
See [Architecture](./Architecture) for additional information on program design.
## Event Dispatching
## Getting Data to and From the Tests
See also [Bug 668550 - python should have some way of transfering data to the test on the JS side](https://bugzilla.mozilla.org/show_bug.cgi?id=668550)
## Python Callbacks
See the \(mutt\) [python_callbacks.js test](https://github.com/mozilla/mozmill/blob/master/mutt/mutt/tests/js/frame/python_callback.js) and accompanying [python_callbacks.py](https://github.com/mozilla/mozmill/blob/master/mutt/mutt/tests/js/frame/python_callback.py) for an example.
It is important for successful runs that the python callback is fired successfully. Otherwise a [jsbridge](./jsbridge) error will occur via the python error and the harness will fail.
## Restart and Shutdown
Both cases fire an [event](./EventHandlers), \(mozmill.userShutdown\), that lets the python harness anticipate the type of shutdown or restart. The following parameters are sent with the event:
See the methods \(startUserShutdown\), \(restartApplication\), and \(stopApplication\) on the [MozMillController](https://github.com/mozilla/mozmill/blob/master/mozmill/mozmill/extension/resource/modules/controller.js) for specifics.
Additionally, \(mozmill --restart\) signals a harness restart between every test file. This is good for isolating test behaviour, but negative in that the browser restart causes the run to take longer.
# Learning Mozmill Testing
## Mozmill Test API
# Finding and Reporting Bugs
Mozmill is under active development. Check out the [Auto-tools Mozmill project page](https://wiki.mozilla.org/Auto-tools/Projects/Mozmill) for information on development. If you think you’ve found a bug in Mozmill, please check the [list of existing bugs](https://bugzilla.mozilla.org/buglist.cgi?resolution=—&component=Mozmill&product=Testing). If your found bug is not listed there, please [file a new bug](https://bugzilla.mozilla.org/enter_bug.cgi?product=Testing&component=Mozmill) in [bugzilla](https://bugzilla.mozilla.org/) under the “Testing” Product and “Mozmill” Component. Please provide as much as possible details and attach the Mozmill test if available, which shows the problem. Thanks for helping us make Mozmill better!
# Updating the Documentation
The [MDN](http://developer.mozilla.org/en/Mozmill) pages are mirrored from the [mozmill repository](https://github.com/mozilla/mozmill). See the notes on our [documentation strategy](./Documentation) .
Several online resources exist for Mozmill:
In addition a \(#mozmill\) channel exists on irc://irc.mozilla.org/ . Please stop by and say hi!