View source for QA/TDAI/Gristmill/Boilerplate Explained

<small>[[QA/TDAI/Gristmill|<< Back to Gristmill Main Page]]</small>

= 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.
<pre>
var elementslib = {}; 
Components.utils.import('resource://mozmill/modules/elementslib.js', elementslib);
var mozmill = {}; 
Components.utils.import('resource://mozmill/modules/mozmill.js', mozmill);

var test_foo = function(){
 var controller = mozmill.getBrowserController();
 controller.open('http://www.google.com');
 controller.sleep(2000);
 controller.type(new elementslib.Name(controller.window.content.document, 'q'), 'Mozilla');
 controller.click(new elementslib.Name(controller.window.content.document, 'btnG'));
}
}</pre>

= Line by Line Explanation =
== Setting up the Envrionment ==
The first block of code sets up the proper environment for your test.

<pre>var elementslib = {};
Components.utils.import('resource://mozmill/modules/elementslib.js', elementslib);</pre>
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.

<pre>var mozmill = {}; 
Components.utils.import('resource://mozmill/modules/mozmill.js', mozmill);</pre>
This is the same thing, except we are loading the mozmill library.  The mozmill library is the library that will give us access to everything else in the application, particularly the controller library.

== 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:
<pre>var test_foo = function(){
 var controller = mozmill.getBrowserController();
 controller.open('http://www.google.com');
 controller.sleep(2000);
 controller.type(new elementslib.Name(controller.window.content.document, 'q'), 'Mozilla');
 controller.click(new elementslib.Name(controller.window.content.document, 'btnG'));
}</pre>

<pre>var test_foo = function(){</pre>
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 Gristmill unless they begin with "test_".

<pre>var controller = mozmill.getBrowserController();</pre>
This gives us a controller object for the current browser window.  Most of the [[QA/TDAI/Gristmill/Gristmill_API|Gristmill API's]] are accessible through the controller object.

<pre>controller.open('http://www.google.com');</pre>
This opens a new page to google.com

<pre>controller.sleep(2000);</pre>
It looks like we are telling the controller to put the browser to sleep for 2000 milliseconds (i.e. 2 seconds).  What we are '''actually''' doing is telling the controller to sleep our test for 2000 milliseconds.  This way the test stops executing while we await the page load of google.com.  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)

<pre>controller.type(new elementslib.Name(controller.window.content.document, 'q'), 'Mozilla');</pre>
This is a typical embedded statement.  The interior: "new elementslib.Name(controller.window.content.document, 'q')" piece creates an element object from the element in the content document named 'q'.  The content document is the loaded web page.  And the element named on this page named 'q'  is the search bar text box.  So this generates an element object referring to the search textbox.  You can find this name 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 "TextBoxObject" for the element object we discussed above.  For example it becomes:
<pre>controller.type(<TextBoxObject>, "Mozilla");</pre>
Now, it's easy to see that this is going to type the string "Mozilla" into the Google search textbox of the HTML page.  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.

<pre>controller.click(new elementslib.Name(controller.window.content.document, 'btnG'));</pre>
Now that we are pro's at reading these embedded statements.  We see that this creates an element object from the button named 'btnG' in the content document and clicks it.  So, this causes us to click the search button, initiating a Google search for "Mozilla".

<pre>}</pre>
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.