QA/TDAI/Gristmill/Gristmill API
<< Back to Main Gristmill Page
This explains the Gristmill APIs that you can use in your tests.
Controller APIs
These APIs are from the Mozmill object and give you different controllers for different parts of the application
mozmill.getBrowserController()
Returns a controller that functions over the entire browser window (gets the most recent browser window)
mozmill.getPreferencesController()
Returns a controller for the preferences window and opens that window. You can then use the specialized controller.tabs.<tabname>.button object to simulate a click on each preference pane tab. For example the following code demonstrates a click on the Content tab of the preferences window:
controller = mozmill.getPreferencesController(); controller.click(new elementslib.Elem(controller.tabs.Content.button));
mozmill.getAddonsController()
Returns a controller for the Add-Ons window and opens the window.
mozmill.newBrowserController()
Opens a new browser window and returns a controller for it
Action APIs
controller.open(url, elementToWaitFor)
| Parameters | |
| url | A URL to open |
Open is a mechanism to open a the given URL in the currently focused tab/window of the window that is under control by the controller.
controller.keypress(el, keycode)
| Parameters | |
| el | An element that the event will be targeted at |
| keycode | The keycode that you wish to send to that element. |
Sends a single key event to the designated element object.
controller.type(el, text)
| Parameters | |
| el | An element that the event will be targeted at |
| text | The text to be typed into the given element object |
Fires type events (simulating both the keydown and keyup) at the given element object. If the text is longer than the available length on the element object, the text will be truncated to fit.
controller.click(el)
| Parameters | |
| el | An element that the event will be targeted at |
Sends a single mouse click to the element object
controller.select(el)
| Parameters | |
| el | An element that the event will be targeted at |
Selects the specified option and triggers the relevant selection events on the given element object. TODO: Determine if this code works.
controller.mousedown(el)
| Parameters | |
| el | An element that the event will be targeted at |
Sends the "mousedown" (mouse button depressed) event to the element object.
controller.mouseup(el)
| Parameters | |
| el | An element that the event will be targeted at |
Sends the "mouseup" (mouse button released) event to the element object.
controller.mouseover(el)
| Parameters | |
| el | An element that the event will be targeted at |
Sends the "mouseover" (mouse drug over an element) event to the element object.
controller.mouseout(el)
| Parameters | |
| el | An element that the event will be targeted at |
Sends the "mouseout" (mouse drug off an element) event to the element object.
controller.check(el)
| Parameters | |
| el | An element that the event will be targeted at |
Causes the element to be "checked" if it is a checkbox. If it is not a checkbox, it causes a click on the element.
controller.radio(el)
| Parameters | |
| el | An element that the event will be targeted at |
Selects a radio button element. If the element is not a radio button entry, then it causes a generic click against that element.
controller.doubleclick(el)
| Parameters | |
| el | An element that the event will be targeted at |
Causes a doubleclick event to be fired at the element object.
Browser Shortcut Action APIs
controller.goBack()
Causes the browser to go back one step in history.
controller.goForward()
Causes the browser to go forward one step in history.
controller.refresh()
Causes the browser to refresh the current document.
controller.tabs.getTab(index)
| Parameters | |
| index | The 0 based index of the tab you want the document for. |
This returns the content document object (i.e. the DOM) for the tab at the specified index.
controller.tabs.activeTab()
Returns the content document object for the active tab
controller.tabs.selectTab(index)
| Parameters | |
| index | The 0 based index of the tab you want the document for. |
Causes the tab at the specified index to be given the current focus. Simulates a click on the specified tab header. NOTE: Not working currently
Wait APIs
controller.sleep(milliseconds)
| Parameters | |
| milliseconds | Number of milliseconds to sleep the test |
Waits the specified number of milliseconds before calling the next instruction in the test.
controller.waitForEval(expression, timeout, interval, subject)
| Parameters | |
| expression | The expression that you want to wait until it evaluates to True |
| timeout | The maximum time you want to wait in milliseconds. Defaults to 30 seconds if not specified |
| interval | How long you want to wait between checking whether or not the expression now evaluates to true. Defaults to 100 milliseconds if not specified. |
| subject | Used by the "waitForElement" call. You may leave this unspecified. |
Takes an expression that should evaluate to true. For example, perhaps the color attribute on the element named "box" should be purple, and once it is, we can continue with the test. In that case, we would use the following:
controller.waitForEval('purple'==document.getElementById('box').getAttribute('color'),200, 15000);
This will evaluate whether or not the box is purple every 200 milliseconds, and will timeout after 15 seconds. If the timeout occurs the function returns false. If the expression does evaluate to 'true' before the timeout happens, then the function returns true.
controller.waitForElement(elem, timeout, interval)
| Parameters | |
| elem | The element you are waiting for |
| timeout | The maximum time you want to wait in milliseconds. Defaults to 30 seconds if not specified |
| interval | How long you want to wait between checking whether or not the expression now evaluates to true. Defaults to 100 milliseconds if not specified. |
This is a specialized call of the waitForEval function above. It will wait until the specified element exists. If it times out, it will return false. If it succeeds, it returns true.
Assert APIs
Use these APIs to test see if certain properties are true on given elements. Think of it as asserting that some statement about the page in question is true.
controller.assertText(el, text)
| Parameters | |
| el | An element that the assert will verify |
| text | The text that the element must have within it. |
Returns True if the text exists in the given element, false otherwise.
controller.assertNode(el)
| Parameters | |
| el | An element that the assert will verify the existence of |
Returns true if the node in question exists, false otherwise.
controller.assertValue(el, value)
| Parameters | |
| el | An element that the assert will verify the existence of |
| value | The value that the element should have |
Returns true if the node in question contains the provided value. (i.e. checked, selected etc)
controller.assertJS(js)
| Parameters | |
| js | Assert |
Executes a piece of javascript. The javascript must return true or false. And this will return that value as the return of the assert.
controller.assertNode(el, value)
| Parameters | |
| el | A select element (a drop down) |
| value | The value that is selected in the drop down. |
Returns true if the currently selected item is equal to the given value
controller.assertChecked(el)
| Parameters | |
| el | An checkbox element |
Returns true if the node in question is checked, false otherwise.
controller.assertProperty(el, attrib, value)
| Parameters | |
| el | An element that the assert will work with |
| attrib | The name of the attribute that we wish to check |
| value | The value we expect that attribute to have |
Returns true if the element's "attrib" property has the specified value, false otherwise.
controller.assertImageLoaded(el)
| Parameters | |
| el | An image to check |
Returns true if the given image is loaded, false otherwise
Element APIs
These APIs live on the elementslib object. You instantiate that object by the following code:
var elementslib = {};
Components.utils.import('resource://mozmill/modules/elementslib.js', elementslib);
Each of these calls can be used to find elements in either the content or the chrome space. There are several ways to look up an element, but the general paradigm is: elementslib.<method>(<document>,<node identifier>);
Here are the APIs:
elementslib.Elem(node)
| Parameters | |
| node | A fully specified element. |
This is the lowest level API. You have to give it a fully specified element, and it will wrap that element into an element lib object so that you can pass it to the controller APIs. An example:
elementlib.Elem(controller.window.content.document.getElementById('foo'));
We also use this for shortcut elements that we've defined for certain chrome objects like tabs in the preferences window:
elementslib.Elem(prefController.tabs.Content.button);
elementslib.ID(document, id)
| Parameters | |
| document | Document to reference, ex. controller.window.content.document for content or controller.window.document for chrome. |
| id | The ID of the node you want to grab out of the document |
Grabs the node with the corresponding ID from the document and wraps it into an elementlib object.
elementslib.Name(document, name)
| Parameters | |
| document | Document to reference, ex. controller.window.content.document for content or controller.window.document for chrome. |
| name | The name attribute of the node you want to grab out of the document |
Grabs the node with the corresponding name attribute from the document and wraps it into an elementlib object.