We're looking for a user researcher to understand the needs of developers and designers. Is this you or someone you know? Check out the post: https://mzl.la/2IGzdXS

First Steps

A Mozmill test is merely a small JavaScript function named "test<something>".  Below we will review a very basic Mozmill test and use that to help you understand how the Mozmill API works.  Note that Mozmill tests run with the same privileges as application-level code, so that means you are not constrained to the Mozmill API alone when crafting your tests.

Hello World

Let's look at a simple test.  The tests are written in JavaScript against a set of defined APIs for mimicking user interaction.  To get an idea of what a test looks like, let's consider the following Firefox test:

// Set up the test module by acquiring a browser controller
var setupModule = function(module) {
  module.controller = mozmill.getBrowserController();

// Our first test...
var testHelloWorld = function() {
  // Type into the location bar
  var locationBar = new elementslib.ID(controller.window.document, "urlbar");
  controller.type(locationBar, "Hello World");

  // Click the Go Button that appears
  controller.click(new elementslib.ID(controller.window.document, "go-button"));
  // Wait for the web page to load

  // On en-US locales, this will search and open
  // http://en.wikipedia.org/wiki/Hello_world_program
  // So, we want to make sure that the wikipedia page is
  // the page that is loaded.
  var heading = new elementslib.ID(controller.tabs.activeTab, "firstHeading");
  controller.assertText(heading, "Hello world program");

We can see that the basic flow of control in a Mozmill test is very simple.  In general, you:

  • Find an element to act on
  • Act on that element
  • Assert that your action had the desired effect.

First, we instantiate a controller object which gives us the ability to interact with the program.  Second, we use the elements library object to get a reference to the location bar in Firefox.  We then type in "Hello World" into the location bar and click the go button (the little arrow that appears upon typing).  Once we start loading the page, we want the test to wait for the website to finish loading.  Calling controller.waitForPageLoad() blocks test execution and allows us to wait Once the page loads, the test continues and we assert that the expected Wikipedia page has loaded.  If you run this in non-en-US locales, you will get a different page and the test will likely fail the last assertion.

One thing to note in this test is how easily we moved between acting on chrome (application user interface) and acting on content (the web page itself). You use the same objects and the same interfaces.  This underscores how powerful Mozmill can be as a user-centric automation tool.

Introducing the Objects

As we have seen, Mozmill contains several helper objects that aid you when crafting a test.

  • elementslib - The elements library acquires objects to interact with during the test.
  • controller - The controller library is the heart of Mozmill. It contains interfaces for acting on elements and asserting that their properties are what they should be for a given test.
  • mozmill - The mozmill library is a collection of application specific interfaces to initially hook into an application.
  • module and test setup APIs - While not objects per se, these interfaces provide the ability to use shared modules in your test so that you can use various utility classes that others have developed to simplify test writing.

Tutorials, Tips, and Tricks

If you want to walk step by step through a sample Mozmill test, we have crafted a set of tutorials for you.

  • Introduction to Mozmill - a great step by step tutorial that explains many of the APIs as you need them
  • Introduction to the Mozmill UI - while the user interface of the Mozmill extension is pretty straight forward, there are some hidden gems in that UI that can speed up your test writing like the record/playback feature and the interactive shell.

Document Tags and Contributors

Contributors to this page: teoli, Doomy, Whimboo, Ctalbert, Brettz9, Sheppy
Last updated by: Doomy,