MDN may have intermittent access issues April 18 13:00 - April 19 01:00 UTC. See whistlepig.mozilla.org for all notifications.

mozilla
Your Search Results

    Mozmill Controller Object

    This is the primary object for simulating user actions in Mozmill

    Method overview

    boolean check(in Elem element, in boolean state); (deprecated)
    boolean click(in Elem element, in int left, int top); (deprecated)
    boolean doubleClick(in Elem element, in int left, in int top); (deprecated)
    boolean dragDropElemToElem(in Elem elementStart, in Elem elementFinish);
    boolean keypress(in Elem element, in string keycode, in object modifiers); (deprecated)
    boolean mouseDown(in Elem element, in int button, in int left, in int top); (deprecated)
    boolean mouseOut(in Elem element, in int button, in int left, in int top); (deprecated)
    boolean mouseOver(in Elem element, in int button, in int left, in int top); (deprecated)
    boolean mouseUp(in Elem element, in int button, in int left, in int top); (deprecated)
    boolean mouseMove(in obj start, in obj dest);
    boolean radio(in Elem element); (deprecated)
    boolean rightClick(in Elem element, in int left, in int top); (deprecated)
    boolean screenShot(in Elem element, in string name, in boolean save, in Array<elem> highlights);
    boolean select(in Elem element, in int index, in string label, in string value); (deprecated)
    void  startUserShutdown(in int timeout, in boolean restart);
    boolean type(in Elem element, in string text); (deprecated)
    void sleep(in int timeout);
    void waitFor(in func callback, in string message, in int timeout, in interval, in object this);
    void waitForElement(in Elem element, in int timeout, in int interval); (deprecated)
    void waitForEval(in string, expression, in int timeout, in int interval, in object subject); (deprecated)
    void waitForImage(in Elem element, in int timeout, in int interval);
    void waitThenClick(in Elem element, in int timeout, in int interval); (deprecated)
    void waitForPageLoad(in document, in int timeout, in int interval);
    boolean assert(in func callback, in string message, in object this);
    boolean assertChecked(in Elem element);
    boolean assertDOMProperty(in Elem element, in string attribute, in string value);
    boolean assertImageLoaded(in Elem element);
    boolean assertJS(in string expression, in object subject); (deprecated)
    boolean assertJSProperty(in Elem element, in string attribute, in string value);
    boolean assertNode(in Elem element);
    boolean assertNodeNotExist(in Elem element);
    boolean assertNotChecked(in Elem element);
    boolean assertNotDOMProperty(in Elem element, in string attribute, in string value);
    boolean assertNotJSProperty(in Elem element, in string attribute, in string value);
    boolean assertSelected(in Elem element, in string value);
    boolean assertText(in Elem element, in string text);
    boolean assertValue(in Elem element, in string value);
    void open(in string uri);
    void goBack();
    void goForward();
    void refresh();
    document tabs.activeTab();
    document tabs.getTab(int in index);
    void tabs.selectTabIndex(int in index);

    Attributes

    Attribute Type Description
    window Window Object A reference to the global window object the controller is active in  
    rootElement (2.0+) MozMillElement A reference to the root element in the window, wrapped inside of a MozMillElement. This is handy for sending global keystrokes to, e.g:
    controller.rootElement.keypress('t', {'ctrlKey':true});
    
    will open a new tab.
    menus Node A set of attributes to access the menus and menu items as elements. Click here for information
    tabs.activeTab DOMDocument Returns the document that is rendered by the current active tab in the browser
    tabs.activeTabIndex int Returns the index number of the currently active tab. It is a browser specific method

    Interaction Methods

    check()

    Deprecated as of Mozmill 2.0 - Use the mozmill element object instead.

    Fires a click at the given checkbox element to ensure it is either checked or not.

    boolean check(
      in Elem element,
      in boolean state
    ); 
    
    Parameters
    element
    An element to attempt to check (should be a checkbox or it will fail).
    state
    Pass true to ensure the element is checked, false to ensure it is unchecked. Defaults to false
    Return value

    true if the action succeeds, otherwise false.

    Example
    controller.check(new elementslib.ID(controller.window.document, 'foo'), true);
    

    click()

    Deprecated as of Mozmill 2.0 - Use the mozmill element object instead.

    Fires a normal (left) click at the given element. You can optionally pass in coordinates to the function for where to click. The coordinates are relative to the element's bounding rectangle. With no coordinates specified, it clicks as 0, 0 on that rectangle (top left corner).

    boolean click(
      in Elem element,
      in int left,
      in int top
    ); 
    
    Parameters
    element
    An element to click on
    left
    Left coordinate for click (optional, defaults to 0)
    top
    Top coordinate for click (optional, defaults to 0)
    Return value

    true if the action succeeds, otherwise false.

    Example
    controller.click(new elementslib.ID(controller.window.document, 'foo'));
    // Or specify coordinates
    controller.click(new elementslib.ID(controller.window.document, 'foo'), 20, 10);
    

    doubleClick()

    Deprecated as of Mozmill 2.0 - Use the mozmill element object instead.

    Fires a normal (left) double click at the given element. You can optionally pass in coordinates to the function for where to click. The coordinates are relative to the element's bounding rectangle. With no coordinates specified, it clicks as 0, 0 on that rectangle (top left corner).

    boolean doubleClick(
      in Elem element,
      in int left,
      in int top
    ); 
    
    Parameters
    element
    An element to click on
    left
    Left coordinate for click (optional, defaults to 0)
    top
    Top coordinate for click (optional, defaults to 0)
    Return value

    true if the action succeeds, otherwise false.

    Example
    controller.doubleClick(new elementslib.ID(controller.window.document, 'foo'));
    // Or specify coordinates
    controller.doubleClick(new elementslib.ID(controller.window.document, 'foo'), 20, 10);
    

    dragDropElemToElem()

    Drags the element specified by elementStart to the x,y coordinates of the element specified by elementFinish. Currently only works in content space (i.e. on a web page).

    boolean dragDropElemToElem(
      in Elem elementStart,
      in Elem elementFinish
    ); 
    
    Parameters
    elementStart
    Element to start dragging
    elementFinish
    Target element to drag to
    Return value

    true if the action succeeds, otherwise false.

    Example
    controller.dragDropElemToElem(new elementslib.ID(controller.window.document, 'foo'),
                                  new elementslib.ID(controller.window.document, 'bar'));
    

    keypress()

    Deprecated as of Mozmill 2.0 - Use the mozmill element object instead.

    Fires a keypress for the given keycode. The modifiers are a JSON object that specifies what key modifiers should be pressed in conjunction with the given key code. The available attribute names for the modifier object are: ctrlKey, altKey, shiftKey, metaKey, and accelKey. Try to avoid the usage of ctrlKey and metaKey if the shortcut is a combination of Ctrl (Windows/Linux) and Cmd (Mac) and use accelKey instead which will work regardless of which operating system your test is executing on.

    boolean keypress(
      in Elem element,
      in string keycode,
      in object modifiers
    ); 
    
    Parameters
    element
    An element to target the keypress at
    keycode
    The key code. Either a literal keycode like 'b' or an enum key code like 'VK_ESCAPE'
    modifiers
    Object of modifiers for this keypress.
    Return value

    true if the action succeeds, otherwise false.

    Example
    // Fire an escape key strokes at element foo:
    controller.keypress(new elementslib.ID(controller.window.document, 'foo'), 'VK_ESCAPE', {});
    
    // Fire a simple key stroke at element foo using the control/command and shift keys
    controller.keypress(new elementslib.ID(controller.window.document, 'foo'), 'b',
                        {shiftKey: true, accelKey: true});
    

    mouseDown()

    Deprecated as of Mozmill 2.0 - Use the mozmill element object instead.

    Simulates the left button being depressed on the mouse when the mouse is over the given element.

    boolean mouseDown(
      in Elem element,
      in int button,
      [in int left],
      [in int top]
    ); 
    
    Parameters
    element
    An element to target
    button
    The id of the button to press (0 - left, 1 - middle, 2 - right)
    left
    The relative horizontal coordinate inside the target element to click
    top
    The relative vertical coordinate inside the target element to click
    Return value

    true if the action succeeds, otherwise false.

    Example
    controller.mouseDown(new elementslib.ID(controller.window.document, 'foo'));
    

    mouseOut()

    Deprecated as of Mozmill 2.0 - Use the mozmill element object instead.

    Simulates the mouse leaving the area over an event without clicking on it. If the element is out of view, the element will be scrolled into view before initiating the mouseOut.

    boolean mouseOut(
      in Elem element,
      in int button,
      [in int left],
      [in int top]
    ); 
    
    Parameters
    element
    An element to target
    button
    The id of the button to press (0 - left, 1 - middle, 2 - right)
    left
    The relative horizontal coordinate inside the target element
    top
    The relative vertical coordinate inside the target element
    Return value

    true if the action succeeds, otherwise false.

    Example
    controller.mouseOut(new elementslib.ID(controller.window.document, 'foo'));
    

    mouseOver()

    Deprecated as of Mozmill 2.0 - Use the mozmill element object instead.

    Simulates the mouse entering the area over an event without clicking on it. If the element is out of view, the element will be scrolled into view before inititating the mouseOver

    boolean mouseOver(
      in Elem element,
      in int button,
      [in int left],
      [in int top]
    ); 
    
    Parameters
    element
    An element to target
    button
    The id of the button to press (0 - left, 1 - middle, 2 - right)
    left
    The relative horizontal coordinate inside the target element
    top
    The relative vertical coordinate inside the target element
    Return value

    true if the action succeeds, otherwise false.

    Example
    controller.mouseOver(new elementslib.ID(controller.window.document, 'foo'));
    

    mouseUp()

    Deprecated as of Mozmill 2.0 - Use the mozmill element object instead.

    Simulates the left button being released on the mouse when the mouse is over the given element.

    boolean mouseUp(
      in Elem element,
      in int button,
      [in int left],
      [in int top]
    ); 
    
    Parameters
    element
    An element to target
    button
    The id of the button to press (0 - left, 1 - middle, 2 - right)
    left
    The relative horizontal coordinate inside the target element
    top
    The relative vertical coordinate inside the target element
    Return value

    true if the action succeeds, otherwise false.

    Example
    controller.mouseUp(new elementslib.ID(controller.window.document, 'foo'));
    

    mouseMove()

    Simulates the mouse being moved from the start coordinates to the end coordinates.

    boolean mouseMove(
      in document doc,
      [in list start],
      [in list dest]
    ); 
    
    Parameters
    doc
    The document to send the mouse move events to
    start
    A list containing the  'x' and 'y' starting coordinates of the move
    dest
    A list containing the 'x' and 'y' ending coordinates of the move
    Return value

    true if the action succeeds, otherwise false.

    Example
    // Move the mouse from position (10,10) in the current tab to (20,20)
    controller.mouseMove(controller.tabs.activeTab, [10, 10], [20, 20]);
    

    radio()

    Deprecated as of Mozmill 2.0 - Use the mozmill element object instead.

    Selects the given radio button by firing a click at it.

    boolean radio(
      in Elem element,
    ); 
    
    Parameters
    element
    An element to select
    Return value

    true if the action succeeds, otherwise false.

    Example
    controller.radio(new elementslib.ID(controller.window.document, 'foo'));
    

    rightClick()

    Deprecated as of Mozmill 2.0 - Use the mozmill element object instead.

    Fires a right click at the given element. You can optionally pass in coordinates to the function for where to click. The coordinates are relative to the element's bounding rectangle. With no coordinates specified, it clicks as 0, 0 on that rectangle (top left corner).

    boolean rightClick(
      in Elem element,
      in int left,
      in int top
    ); 
    
    Parameters
    element
    An element to click on
    left
    Left coordinate for click (optional, defaults to 0)
    top
    Top coordinate for click (optional, defaults to 0)
    Return value

    true if the action succeeds, otherwise false.

    Example
    controller.rightClick(new elementslib.ID(controller.window.document, 'foo'));
    // Or specify coordinates
    controller.rightClick(new elementslib.ID(controller.window.document, 'foo'), 20, 10);
    

    screenShot()

    Takes a screenshot of the passed in window or DOM element. Screenshots can either be saved to the temporary directory or be returned to the reporting as a dataURL. An array of elements to be highlighted with a red rectangle can also be passed in.

    boolean screenShot(
      in Elem element,
      in string name,
      [in boolean save],
      [in Array<elem> highlights]
    ); 
    
    Parameters
    element
    An element or a window to capture
    name
    The name of the screenshot. Used in reporting and to save the file
    save
    If true, saves the screenshot in tempdir/mozmill_screens/name.png and the filepath is added to the report. Otherwise the dataURL is added to the report
    Return value

    true if the action succeeds, otherwise false.

    Example
    var elem = findElement.ID(controller.tabs.activeTab, 'elemID');
    var child = elem.getNode().childnodes[0];
    // Take a screenshot of 'elem' and draw a red rectangle around it's first child element
    controller.screenShot(elem, 'demo', true, [child]);
    

    select()

    Deprecated as of Mozmill 2.0 - Use the mozmill element object instead.

    Handles selecting an option from a menu list or an HTML select element. The "element" corresponds to the list. There are multiple ways to select from such a list, either by "index", "label", or by the "value" associated with that option.

    • index - to use an index, give it a valid index >=0. If you do not wish to use an index, pass 'null' for this field. Using an index of -1 will reset the current selection.
    • label - to use label, supply the label. If you do not wish to use an option name, then pass 'null' in this field.
    • value - to use the value attribute, supply the valid value in this field. If you choose not to supply a value, you can simply leave it off when not including it or pass in 'null'.
    boolean select(
      in Elem element,
      in int index,
      in string label,
      in string value
    ); 
    
    Parameters
    element
    An element to click on
    index
    index of item in drop down list. Use null if you do not wish to specify an index. -1 will reset the selection.
    label
    Label of the option you wish to select, if you do not wish to use it pass null
    value
    Value of the option you wish to select, if you do not wish to use this field either leave it off or pass null
    Return value

    true if the action succeeds, otherwise false.

    Example
    // Select only using the index
    controller.select(new elementslib.ID(controller.window.document, 'foo'), 2);
    
    // Select using the label of the given element
    controller.select(new elementslib.ID(controller.window.document, 'foo'), null, 'bar');
    

    startUserShutdown()

    Creates a timeout window during which the browser is allowed to be restarted or shutdown, for example by selecting 'Quit' from the 'File' menu.  If startUserShutdown() is called and the test does not restart or shutdown the browser within the specified timeout, the test will fail.  The browser must also be shutdown within the same test that called startUserShutdown().  Note: This is only available in Mozmill 1.4.2 and later.

    Parameters
    timeout
    The number of milliseconds during which the browser is allowed to be restarted or shutdown.
    restart
    True if a restart is to be expected, false if a shutdown is to be expected.
    Return value

    None

    Example
    controller.startUserShutdown(2000, false); 
    controller.click(new elementslib.Elem(controller.menus["file-menu"].menu_FileQuitItem));
    

    type()

    Deprecated as of Mozmill 2.0 - Use the mozmill element object instead.

    Types a string of text at the given element.

    boolean type(
      in Elem element,
      in string text
    ); 
    
    Parameters
    element
    An element to type at
    text
    The text to type
    Return value

    true if the action succeeds, otherwise false.

    Example
    controller.type(new elementslib.ID(controller.window.document, 'foo'), 'some text to type');
    

    Wait methods

    sleep()

    Causes the test to pause its execution until "timeout" milliseconds have passed. This is the least granular of the wait methods and is NOT encouraged to be used. It is only included here because it is sometimes useful when debugging. You should use other wait methods in your tests in order to ensure your tests are more deterministic.

    void sleep(
      in int timeout
    ); 
    
    Parameters
    timeout
    Number of milliseconds to pause.
    Return value

    None

    Example
    // Sleeps one second
    controller.sleep(1000);
    

    waitFor()

    Waits until the callback handler returns true. The handler gets called every "interval" milliseconds, and if "timeout" milliseconds have passed without the handler return true, it gives up and causes the test to fail. If you use the defaults, then it will check the return value once every 100ms and will throw an error after 30 seconds have passed.

    void waitFor(
      in func callback,
      in string message,
      in int timeout,
      in int interval,
      in object this
    ); 
    
    Parameters
    callback
    A callback function or closure which executes code inside the scope of the test and has to return true/false.
    message
    Message to use for the raised exception when return value isn't true (optional)
    timeout
    Total time in milliseconds to wait (optional, default: 5000ms)
    interval
    How often to check if the element has appeared (optional, default: 100)
    this
    Reference to the outer scope's this object. It's needed when this has to be used inside the callback function.

    None

    Example
    // Accept the default settings
    var value = { message: "g" };
    controller.waitFor(function () { 
      return value.message === 'foo'; 
    }, "This is expected to fail.");
    
    // Wait until the location bar is visible, check every 100ms, and if it isn't true by 1000ms then throw an error.
    var locationBar = new elementslib.ID('urlbar');
    controller.waitFor(function () { 
      return locationBar.getNode().visibility === true;
    }, "Location bar should be visible", 1000, 100);
    

    waitForElement()

    Deprecated as of Mozmill 2.0 - Use the mozmill element object instead.

    Waits for the "element" to appear in the user interface (for instance if you wanted to wait for part of a page or dialog to load). It checks for "element" every "interval" milliseconds, and gives up if "timeout" milliseconds have passed without the "element" appearing, causing the test to fail. If you accept the defaults, it will check for the element every 100ms and will throw an error if 30 seconds pass without the element appearing.

    void waitForElement(
      in Elem element,
      in int timeout,
      in int interval
    ); 
    
    Parameters
    element
    Element to wait for
    timeout
    Total time in milliseconds to wait
    interval
    How often to check if the element has appeared
    Return value

    None

    Example
    // Typical usage - accept defaults.  See waitForEval() to see non-default operation
    controller.waitForElement(new elementslib.ID(controller.window.document, 'foo'));
    

    waitForEval()

    Removed as of Mozmill 2.0 - This method was removed due to a potential security vulnerability. Use waitFor() instead.

    Waits for the JavaScript "expression" to be true. It checks to see if the expression is true once every "interval" milliseconds, and if "timeout" milliseconds have passed without the expression becoming true, it gives up and causes the test to fail. If you use the defaults, then it will check the expression once every 100ms and will throw an error after 30 seconds have passed. The subject parameter which is passed as last argument will be substituted with the "subject" string inside the expression string. This method is deprecated, use the waitFor method instead.

    void waitForEval(
      in string expression,
      in int timeout,
      in int interval,
      in object subject
    ); 
    
    Parameters
    expression
    Expression to evaluate, optionally containing the word "subject" for substitution
    timeout
    Total time in milliseconds to wait
    interval
    How often to check if the element has appeared
    subject
    Object to substitute for the value of "subject" in the expression
    Return value

    None

    Example
    // Accept the default settings
    controller.waitForEval('foo==true');
    
    // Wait until the location bar is visible, check every 100ms, and if it isn't true by 1000ms then throw an error.
    let locationBar = new elementslib.ID('urlbar')
    controller.waitForEval('subject.visibility == true', 1000, 100, locationBar.getNode());
    

    waitForImage()

    Waits for the image represented by "element" to appear in the user interface. It checks for the image every "interval" milliseconds, and gives up if "timeout" milliseconds have passed without the "element" appearing, causing the test to fail. If you accept the defaults, it will check for the image every 100ms and will throw an error if 30 seconds pass without the image appearing.

    void waitForElement(
      in Elem element,
      in int timeout,
      in int interval
    ); 
    
    Parameters
    element
    Element to wait for
    timeout
    Total time in milliseconds to wait
    interval
    How often to check if the element has appeared
    Return value

    None

    Example
    // Typical usage - accept defaults.  See waitForEval() to see non-default operation
    controller.waitForImage(new elementslib.ID(controller.window.document, 'foo'));
    

    waitForPageLoad()

    This is a browser specific method. It blocks the test until the current page completes loading.

    void waitForPageLoad(
      in DOMDocument document,
      in int timeout,
      in int interval
    ); 
    
    Parameters
    document
    Document to wait on, if not specified, uses the current document.
    timeout
    Total time in milliseconds to wait
    interval
    How often to check if the element has appeared
    Return value

    None

    Example
    // Waits for the current tab to load, timing out after 3 seconds have passed and
    // it will check if the page is loaded every 100ms
    controller.waitForPageLoad();
    
    // Waits for the current page to load and will timeout once the given number of
    // milliseconds have passed. For example, this times out after 1 second:
    controller.waitForPageLoad(1000);
    
    // The third version allows you to specify each parameter.  This allows you to specify
    // what document is loading, the time that it must load within and how often to check that
    // loading is complete.  For example, this waits for the page in tab 3 to load, and will
    // check whether that page is loaded every 500ms, and will timeout after 2s have passed.
    controller.waitForPageLoad(controller.tabs.getTab(3), 2000, 500);
    

    waitThenClick()

    Deprecated as of Mozmill 2.0 - Use the mozmill element object instead.

    Waits for the "element" to appear in the user interface. It checks for "element" every "interval" milliseconds, and gives up if "timeout" milliseconds have passed without the "element" appearing, causing the test to fail. Once "element" appears, a click event is immediately fired at it. This is a simple shortcut API for the common pattern of waiting for an element to appear before firing a click event on it.

    void waitThenClick(
      in Elem element,
      in int timeout,
      in int interval
    ); 
    
    Parameters
    element
    Element to wait for
    timeout
    Total time in milliseconds to wait
    interval
    How often to check if the element has appeared
    Return value

    None

    Example
    // Typical usage - accept defaults.  See waitForEval() to see non-default operation
    controller.waitThenClick(new elementslib.ID(controller.window.document, 'foo'));
    

    Assertion Methods

    assert()

    Asserts that the callback function returns true.

    boolean assert(
      in func callback,
      in string message,
      in object this
     ); 
    
    Parameters
    callback
    A callback function or closure which evaluates an expression inside the scope of the test and has to return true/false.
    message
    Message to use for the raised exception when return value isn't true (optional)
    this
    Reference to the outer scope's this object. It's needed when this has to be used inside the callback function (optional)
    Return value

    Boolean - returns true if assertion holds true, returns false if assertion is not true

    Example
    // Run specific javascript that evaluates to a non-zero value
    controller.assert(function() {
      return 2 > 1;
    });
    
    // Check if an array has the value as element (This will raise an exception with the given message)
    var value = 5;
    var items = [1, 2, 3, 4];
    controller.assert(function() {
      return items.indexOf(value) !== -1; 
    }, "The array has '5' as element.");
    

    assertChecked()

    Asserts that the passed-in checkbox "element", is checked. It will cause a failure if the checkbox is not checked. Returns true if the box is checked, false if not.

    boolean assertChecked(
      in Elem element
    ); 
    
    Parameters
    element
    Element to check
    Return value

    Boolean - returns true if assertion holds true, returns false if assertion is not true

    Example
    controller.assertChecked(new elementslib.ID(controller.window.document, 'foo'));
    

    assertDOMProperty()

    If the value parameter is not specified, asserts that the given DOM attribute exists for the given element. If the value parameter is specified, asserts that the given DOM attribute on the given element is the specified value. If the assertion passes, it returns true, otherwise, it returns false and marks a failure in the test. Note: This method is only available in Mozmill 1.4.2 and later.

    boolean assertDOMProperty(
      in Elem element
      in string attribute,
      [in string value]
    ); 
    
    Parameters
    element
    Element to check
    attribute
    The DOM attribute to check
    value
    The value that the DOM attribute is expected to contain
    Return value

    Boolean - returns true if assertion holds true, returns false if assertion is not true

    Example
    // True if the DOM attribute called 'class' exists
    controller.assertDOMProperty(new elementslib.ID(controller.window.document, 'foo'), 'class');
    // True if the DOM attribute called 'class' has a value of 'bar'
    controller.assertDOMProperty(new elementslib.ID(controller.window.document, 'foo'), 'class', 'bar');
    

    assertImageLoaded()

    Asserts that the image refrerenced by "element" is loaded. It will cause a failure if the image is not loaded. Returns true if the image is loaded, false if not.

    boolean assertImageLoaded(
      in Elem element
    ); 
    
    Parameters
    element
    Element to check
    Return value

    Boolean - returns true if assertion holds true, returns false if assertion is not true

    Example
    controller.assertImageLoaded(new elementslib.ID(controller.window.document, 'foo'));
    

    assertJS()

    Removed as of Mozmill 2.0 - This method was removed due to a potential security vulnerability.

    Asserts that JavaScript expression evaluates to true or to a non-zero value. You can optionally pass in an object for the "subject" parameter and that object will be substituted for the string "subject" in the expression.

    boolean assertJS(
      in string expression,
      in object subject
    ); 
    
    Parameters
    expression
    An expression of JavaScript code to evaluate
    subject
    An object to use in the expression, optional argument.
    Return value

    Boolean - returns true if assertion holds true, returns false if assertion is not true

    Example
    // Run specific javascript that evaluates to a non-zero value
    controller.assertJS('2 > 1');
    
    // Check if an array has three elements (this one would return false and cause a failure)
    var items = ['1', '2', '3', '4'];
    controller.assertJS('subject.length == 3', items);
    

    assertJSProperty()

    If the value parameter is not specified, asserts that the given Javascript object property exists for the given element. If the value parameter is specified, asserts that the given Javascript object property on the given element is the specified value. If the assertion passes, it returns true, otherwise, it returns false and marks a failure in the test. Note: This method is only available in Mozmill 1.4.2 and later.

    boolean assertJSProperty(
      in Elem element
      in string attribute,
      [in string value]
    ); 
    
    Parameters
    element
    Element to check
    attribute
    The Javascript object property to check
    value
    The value that the Javascript object property is expected to contain
    Return value

    Boolean - returns true if assertion holds true, returns false if assertion is not true

    Example
    // True if the Javascript object property called 'class' exists
    controller.assertJSProperty(new elementslib.ID(controller.window.document, 'foo'), 'class');
    // True if the Javascript object property called 'class' has a value of 'bar'
    controller.assertJSProperty(new elementslib.ID(controller.window.document, 'foo'), 'class', 'bar');
    

    assertNode()

    Asserts that the given element exists. If the element does not exist, this returns false and marks a failure in the test. Note that this tests existence, not visibility. If the element is not visible, but it does exist in the DOM, this will return true.

    boolean assertNode(
      in Elem element
    ); 
    
    Parameters
    element
    Element to check
    Return value

    Boolean - returns true if assertion holds true, returns false if assertion is not true

    Example
    controller.assertNode(new elementslib.ID(controller.window.document, 'foo'));
    

    assertNodeNotExist()

    Asserts that the given element DOES NOT exist. If the element does not exist, this returns true and if it does exist, it returns false and marks a failure in the test. Note that like assertNode this tests existence, not visibility.

    boolean assertNodeNotExist(
      in Elem element
    ); 
    
    Parameters
    element
    Element to check
    Return value

    Boolean - returns true if assertion holds true, returns false if assertion is not true

    Example
    controller.assertNodeNotExist(new elementslib.ID(controller.window.document, 'foo'));
    

    assertNotChecked()

    Asserts that the given element is not in a "checked" state. So, if the element is unchecked, this returns true, otherwise false.

    boolean assertNotChecked(
      in Elem element
    ); 
    
    Parameters
    element
    Element to check
    Return value

    Boolean - returns true if assertion holds true, returns false if assertion is not true

    Example
    controller.assertNotChecked(new elementslib.ID(controller.window.document, 'foo'));
    

    assertNotDOMProperty()

    If the value parameter is not specified, asserts that the given DOM attribute does not exist on the given element. If the value parameter is specified, asserts that the given DOM attribute for the given element is not equal to the given value. If the assertion passes, it returns true, otherwise, it returns false and marks a failure in the test. This is very useful for asserting that various controls are not disabled, options are not selected etc. Note: This method is only available in Mozmill 1.4.2 and later.

    boolean assertNotDOMProperty(
      in Elem element
      in string attribute
      [in string value]
    ); 
    
    Parameters
    element
    Element to check
    attribute
    The DOM attribute to check
    value
    The value the DOM attribute is expected to not contain
    Return value

    Boolean - returns true if assertion holds true, returns false if assertion is not true

    Example
    // True if there is no DOM attribute called 'disabled'
    controller.assertNotDOMProperty(new elementslib.ID(controller.window.document, 'fooControl'), 'disabled');
    // True if the DOM attribute called 'name' doesn't have a value of 'bar'
    controller.assertNotDOMProperty(new elementslib.ID(controller.window.document, 'fooControl'), 'name', 'bar');
    

    assertNotJSProperty()

    If the value parameter is not specified, asserts that the given Javascript object property does not exist for the given element. If the value parameter is specified, asserts that the given Javascript object property for the given element is not equal to the given value. If the assertion passes, it returns true, otherwise, it returns false and marks a failure in the test. This is very useful for asserting that various controls are not disabled, options are not selected etc. Note: This method is only available in Mozmill 1.4.2 and later.

    boolean assertNotJSProperty(
      in Elem element
      in string attribute
      [in string value]
    ); 
    
    Parameters
    element
    Element to check
    attribute
    The Javascript object property to check
    value
    The value the Javascript object property is expected to not contain
    Return value

    Boolean - returns true if assertion holds true, returns false if assertion is not true

    Example
    // True if there is no Javascript object property called 'disabled'
    controller.assertNotJSProperty(new elementslib.ID(controller.window.document, 'fooControl'), 'disabled');
    // True if the Javascript object property called 'name' doesn't have a value of 'bar'
    controller.assertNotJSProperty(new elementslib.ID(controller.window.document, 'fooControl'), 'name', 'bar');
    

    assertSelected()

    Asserts that the given drop-down (or option) element has the given value selected. It uses the specified value of the selected option to verify this, you will have to usually look at the DOM Inspector to determine what this value should be.

    boolean assertSelection(
      in Elem element,
      in string value
    ); 
    
    Parameters
    element
    Element to check
    value
    The value of the option you expect to be selected
    Return value

    Boolean - returns true if assertion holds true, returns false if assertion is not true

    Example
    controller.assertSelected(new elementslib.ID(controller.window.document, 'foo'), 'optionvalue');
    

    assertText()

    Asserts that the given element's innerHTML is equal to a given string of text.

    boolean assertText(
      in Elem element,
      in string text
    ); 
    
    Parameters
    element
    Element to check
    text
    The text the element's innerHTML should contain
    Return value

    Boolean - returns true if assertion holds true, returns false if assertion is not true

    Example
    // Simple use for text boxes.
    controller.assertText(new elementslib.ID(controller.window.document, 'foo'), '<b>bar</b>');
    
    // If you had a XUL Description field of the form: <description id="mydesc">Some text here</description>
    // Then you could use this statement to verify the "Some text here" string:
    controller.assertText(new elementslib.ID(controller.window.document, 'mydesc'), '<i>Some text here</i>');
    

    assertValue()

    Asserts that the element contains the given value. This is typically used with input controls, like form elements, or textboxes. A primary use case is to shortcut when looking for the "value" attribute and ascertaining that it contains a certain value. You could of course just use the assertDOMProperty method.

    boolean assertValue(
      in Elem element,
      in string value
    ); 
    
    Parameters
    element
    Element to check
    value
    The value of the element that you expect
    Return value

    Boolean - returns true if assertion holds true, returns false if assertion is not true

    Example
    controller.assertValue(new elementslib.ID(controller.window.document, 'foo'), 'bar');
    

    Browser Specific Methods

    open()

    Opens a given URI in the browser.

    void open(
      in string uri
    ); 
    
    Parameters
    uri
    URI to open
    Return value

    None

    Example
    controller.open('http://www.mozilla.org');
    

    goBack()

    Causes the browser to go back one step into the history for this page.

    boolean goBack(); 
    
    Parameters

    None

    Return value

    None

    Example
    controller.goBack();
    

    goForward()

    Causes the browser to go forward one step into the back/forward history for this page.

    void goForward(); 
    
    Parameters

    None

    Return value

    None

    Example
    controller.goForward();
    

    refresh()

    Causes the browser to refresh the current page.

    void refresh(); 
    
    Parameters

    None

    Return value

    None

    Example
    controller.refresh();
    

    tabs.getTab()

    Gets a reference to the document rendered by the tab corresponding to the given index.

    DOMDocument tabs.getTab(); 
    
    Parameters
    index
    The zero-based index number for the tab in question.
    Return value

    DOMDocument

    Example
    let doc = controller.tabs.getTab(0);
    let fooelement = doc.getElementById('foo');
    

    tabs.selectTabIndex()

    Switches to a tab based on the given zero-based index. This is the equivalent of clicking on the tab in the tab bar with the mouse to "focus" a tab.

    void tabs.selectTabIndex(); 
    
    Parameters
    index
    The zero-based index number for the tab in question.
    Return value

    None

    Example
    controller.tabs.selectTabIndex(0);
    

    Document Tags and Contributors

    Tags: 
    Contributors to this page: arai, Whimboo, ahal, jmozmoz, Ctalbert, bumpsy, harth, madarche
    Last updated by: arai,