QA/TDAI/Gristmill/Boilerplate Explained

<< Back to Gristmill Main Page

The BoilerPlate

Here is the generated code from the "Test->New Boilerplate" step in the Gristmill UI. We'll go through it line by line to see what each item does.

var elementslib = {}; Components.utils.import('resource://mozmill/modules/elementslib.js', elementslib);
var controller = {}; Components.utils.import('resource://mozmill/modules/controller.js', controller);

var wm = Components.classes["@mozilla.org/appshell/window-mediator;1"].getService(Components.interfaces.nsIWindowMediator);
var _w = wm.getMostRecentWindow("navigator:browser");
var browser = new controller.MozMillController(_w);

var test_foo = function(){
 browser.type(new elementslib.ID(_w.document, 'urlbar'), "http://www.heckyes.com");
 browser.sleep(5000);
 browser.click(new elementslib.ID(_w.document, 'home-button'));
 browser.open('http://www.google.com');
}

Line by Line Explanation

Setting up the Envrionment

The first block of code sets up the proper environment for your test.

var elementslib = {}; Components.utils.import('resource://mozmill/modules/elementslib.js', elementslib);

This statement imports a Javascript library file to the scope of your test. This means that you can now access all the exported functions from the elementslib. The elementslib is used to locate and grab UI elements to interact with.

var controller = {}; Components.utils.import('resource://mozmill/modules/controller.js', controller);

This is the same thing, except we are loading the controller library. The controller allows us the ability to perform interactions on UI elements.

var wm = Components.classes["@mozilla.org/appshell/window-mediator;1"].getService(Components.interfaces.nsIWindowMediator);

The WindowMediator allows us to flip between different open windows.

var _w = wm.getMostRecentWindow("navigator:browser");

This grabs the most recent browser window.

var browser = new controller.MozMillController(_w);

This creates a controller instance for the most recently opened browser window. It names it "browser" so that the code will later look like you are telling the browser what to do. We think it makes the code more readable.

The Real Test Code

This is the test code, and it is the section you should customize to write your test. We've included a simple sample test in the boilerplate to give you a place to start.

Here is an overview of the test function before we dismantle it line by line:

var test_foo = function(){
 browser.type(new elementslib.ID(_w.document, 'urlbar'), "http://www.heckyes.com");
 browser.sleep(5000);
 browser.click(new elementslib.ID(_w.document, 'home-button'));
 browser.open('http://www.google.com');
}

var test_foo = function(){

This names our test "test_foo" and creates a function. Each test is one function, named test_<something>. Try to name them descriptively for what you are testing. The test function can call other functions, but other functions won't be called by Mozmill unless they begin with "test_".

browser.type(new elementslib.ID(_w.document, 'urlbar'), "http://www.heckyes.com");

This is a typical embedded statement. The interior: "new elementslib.ID(_w.document, 'urlbar')" piece creates an element object from the urlbar in the main window _w. "urlbar" is the XUL ID of the Location Bar in the browser. You can find that using the DOM Explorer Extension or the Explorers->DOM Explorer UI from the Mozmill IDE window.

The rest of this statement then becomes a bit clearer if we substitute the word "UrlBarObject" for the element Object we discussed above. For example it becomes:

browser.type(<UrlBarObject>, "http://www.heckyes.com");

Now, it's easy to see that this is going to type the string "http://www.heckyes.com" into the URLBar of the browser. And that's exactly what it does.

We write the action lines using this embedded statement method so that each line of the file is one action in the test. It makes sense to us to do it this way so that you can quickly read what the test does.

browser.sleep(5000);

This is a little confusing here. It looks like we are telling the browser to sleep for 5000 milliseconds (i.e. 5 seconds). What we are actually doing is telling the browser to sleep our test for 5000 milliseconds. This way the test stops executing while the typing is performed. You would use these sleeps and the related "WaitForElement" actions in order to allow the browser time to do something before you go on with the next instruction in the test. Note that all sleeps and timeouts are in milliseconds. (1000 milliseconds == 1 second).

browser.click(new elementslib.ID(_w.document, 'home-button'));

Now that we are pro's at reading these embedded statements. We see that this creates an element object from the home button (which is found in the current Window's Document interface) and clicks it. This will cause us to load the currently set home page.

browser.open('http://www.google.com');

This is a shortcut to tell the browser to open the given URL (in this case, "http://www.google.com") using the currently active tab.

}

This is the closing brace of our test_foo function. This marks the end of that function. More test_* functions can follow, and those will be executed as separate tests by Gristmill. Or, other functions can follow that do not have a name beginning with "test_", and these will be seen as helper functions by Gristmill and will not be executed automatically.