Controller API

brianantonelli edited this page Jun 22, 2011 · 13 revisions

Every test authoring library and markup implements the Windmill Controller API. This API is used to simulate browser interactions, asserting elements and text exist, conditionally wait for elements to appear, and to store dynamic values for use in later tests.

Locators

Most of the controller API can take any of the locator keyword params. A locator tells windmill how to lookup a node to simulate a browser action on.

The available locators are:

locator description
id The element id.
link The text representing the link.
name The display name of the node.
jquery A jQuery selector, see http://jquery.com
xpath An XPath expression that should return a single node.
classname Access an element via the HTMLCollection returned by document.getElementsByClassName, defaults to the first element but you can specify another, ex. ‘myclass,4’
tagname Access an element via the HTMLCollection returned by document.getElementsByTagName, defaults to the first element but you can specify another, ex. ‘div,5’
jsid A javascript expression that after evaluated returns an element DOM ID.
  • JSID Note: If you don’t specify a scope by including windmill.testWindow, or _w, this will assume you would like the window scope prepended. If you do specify the scope, this will directly evaluate the JavaScript you passed. This was done this way so that if you want to keep things clean, you can just pass the path within the test window. If you would like to prepend or append text to the ID that is returned you will want to specify the test window and include valid JavaScript to be evaluated to return the ID you wanted.
Ex. {"method":"click", "params":{"jsid":"document.variable.id"}}
(Appends the scope for you, becomes _w.document.variable.id)

Ex. {"method":"click", "params":{"jsid":"'mystring'+_w.document.variable.id"}}

Available Methods

method parameters description
open “url” open a given url for testing
click “all locators” click on the given node
doubleClick “all locators” double click on a given node
rightClick “all locators” right click on a given node
select ‘’all Locators’’ & (‘option’, ‘val’ or ‘index’) select an option from a given drop down or list, ‘option’ corresponds to innerHTML, and ‘val’ to the value property, and ‘index’ is the index of the options array
mouseDown “all locators” fire the mousedown event on a given node
mouseUp “all locators” fire the mouseup event on a given node
mouseOver “all locators” fire the mouseover event on a given node
mouseOut “all locators” fire the mouseout event on a given node
mouseMoveTo “coords” move the mouse from it’s current location to a new set of coordinates. ex. (100,200)
mouseMove “coords” move the mouse from one (x,y) coordinate to another (x,y) coordinate, ex. ‘(startx,starty),(endx,endy)’
dragDropElem ‘’all locators’‘, ’’pixels" ‘’All Locators’‘, ’’pixels’
oves a DOM element on the page by a specified offset. Format; (number of x pixels, number of y pixels), ex. (100,30)
dragDropAbs ‘all locators’‘, ’’coords’’ uses absolute coordinates to click an element, and move it from one set of coords to another. Format; ex. ‘(100,100),(300,350)’
dragDropElemToElem "all locators’’, ‘all locators’’ moves one element to another element handling all of the coordinate calculation for you.
reWriteAlert override the window.alert function to send the alert content to the output tab
check "all locators’’ toggle a given checkbox
radio "all locators’’ select a given radio button
type "all locators’’ enter data into any form text input field
keyPress "all locators’’, Options comma delimited string keySequence, canBubble, controlKeyDown, altKeyDown, shiftKeyDown, metaKeyDown (ex. a,true,false,false,false,false)
keyDown "all locators’’, Options comma delimited string keySequence, canBubble, controlKeyDown, altKeyDown, shiftKeyDown, metaKeyDown (ex. a,true,false,false,false,false)
keyUp "all locators’’, Options comma delimited string keySequence, canBubble, controlKeyDown, altKeyDown, shiftKeyDown, metaKeyDown (ex. a,true,false,false,false,false)
execJS ’’js’’ A JavaScript string to be executed against the testing window.
execIDEJS ’’js’’ A JavaScript string to be executed in the IDE window, usually used for accessing the registry.
waits.sleep ’’milliseconds’’ Make the browser sleep for a given number of seconds
waits.forElement ’’timeout’’ Waits for a DOM element to exist, or times out
waits.forElementProperty ’’locator", “option” Waits for both access to the node, and the property. “option” is a pipe delimited string ie. attribute, value, optional timeout, attribute, value, timeout
waits.forPageLoad ’’timeout’’ Waits for a new page to load in the testing window
waits.forJS ’’js’’ Waits for the result of the eval’d string of !JavaScript code to return true. If you need to interact with variables then access them via ‘’_w.’’. ex. _w.pageYOffset == 0
waits.forNotTitle “title”, ’’timeout’’ Waits for the testing window to NOT have the provided title.
scroll "coords’’ how many pixels would you like to scroll: x, y
storeVarFromJS "options’’ options is a pipe delimited string with two parts, example string: ‘test pipe window.location.href’, this will store a variable named {$test} with the testing windows url
  • You can then access from any future test by simply putting the string {$test} in the options. Example of that: {method:“open”, params: {url:“{$test}”}}.
storeURL "link’’ store a URL in the Javascript variable registry to access later with the provided variable {$linktext}, ex. link “Go Home” becomes variable {$Go Home}
storeVarFromLocAttrib “all locators”, ‘’options’ options is a pipe delimited string with two parts, example string: ’test innerHTML’, this will store a variable named {$test} with the contents of the innerHTML attribute of the element you passed.
  • You can then access from any future test by simply putting the string {$test} in the options.

Usage Examples

Click a link that’s of class foo & has an attribute bar, whose value matches baz.
client.click(jquery=u'("a.foo[bar*=\'baz\']")[0]')

Find the last form with class foo. within it, find a button that matches regex bar.
client.click(jquery=u'("form.foo:last button[name=\'bar\']")[0]')

Select a node that :contains specific text
click.click(jquery=u'("div.fbs-li-name:contains(\'%s\')")[0]' % value)

Select the :visible node (where there are similar nodes that aren’t visible)
client.type(text=topic_name, jquery=u'("input.adddatameta-input:visible")[0]')

Select one node, then go to a child of it
#find a div whose fb__pid matches foo. Within it go to a node of any type with classes bar and baz. client.click(jquery=u'("div[fb__pid*=\'%s\'] .prop-edit-menu-title.popup-trigger")[0]' % property)

Select one node, go up to a parent of a certain type, and within that parent, select a given element.
client.click(jquery=u'("input[value=\'%s\']").parents("tr").find(".row-remove")[0]' % link)

Is the “Import list” link now visible?
client.asserts.assertNode(jquery=u'("div[fb__pid*=\'%s\'] .import-link:visible")[0]' % property)


windmill.controller.commands

windmill.controller.commands.getPageText
Used for getting the HTML of the testing page.
client.commands.getPageText()

windmill.controller.commands.getNodeContents [only in trunk]
Used for getting the HTML of a node on the testing page.
client.commands.getNodeContents()

windmill.controller.commands.getNodeProperty [only in trunk]
Used for getting a properties value of a node on the testing page.
client.commands.getNodeProperty()

windmill.controller.commands.setOptions

Used for setting properties without requiring the Windmill UI

When there is an error, stop running the tests: true / false
{"method": "commands.setOptions", "params": {"stopOnFailure" : false}}

windmill.controller.commands.getControllerMethods

This returns all of the available methods in the controller and its objects.
{"method": "commands.getControllerMethods", "params": {}}


  • Note that each of these have a dynamically created inverse available, ex. asserts.assertText becomes asserts.assertNotText.
  • If you are working in the IDE you can add these by inserting a new action and then selection one of the assert functions from the drop down.
method parameters description
asserts.assertText “all locators”, ’’validator’’ Validates the existence of text in a provided DOM node
asserts. assertNode “all locators” Asserts that a node exists in the DOM in the testing window
asserts. assertValue “all locators”, ’’validator’’ Assert that a value exists in the provided form element
asserts. assertSelected “all locators”, ’’validator’’ Assert that an option was selected in a drop down or list element
asserts. assertChecked “all locators” Assert that a selected checkbox was checked
asserts. assertProperty “All Locators”, ’’validator’’ Assert the value of a provided DOM nodes property, ex. disabled 'pipe' true
asserts. assertImageLoaded “all locators” Assert that an image is loaded on the page
asserts. assertJS “js” Assert a JavaScript expression
asserts. assertElemJS “js” Asserting javascript with an element object available. ex. element.innerHTML.indexOf(‘something’) != -1

Adding your own assertion

See [http://trac.getwindmill.com/wiki/advanced#Extensions The Advanced Usage Section]

Variable Registry

Although the language you’re writing tests already has variables you can set and use later in tests it can sometimes be useful to set variables through the windmill controller that stay around during the entire duration of your test run in the browser.

When your test comes into the IDE, it is parsed for variables that have been defined in the registry. If they exist, the variable is replaced with the value. If you would like random value that you can use for this session, that is possible as well.

Syntax:
Basic Variable: {$sometext} ex. {$myurl}

Behavior:
If it exists, it will be replaced with the value in the registry
If it doesn’t exist, the variable syntax will be used ie. you will actually be creating a user called {$tempUser}

Random Variable: {$random(anything you want)} ex. {$random1} ex. client.type(text=u'{$random}@domain.com', name=u'username') (This string is random and up to 16 characters)

Behavior:
If the variable exists in the registry, it will be replaced with it’s value
If it doesn’t exist a random value will be created

Example:
This is the JSON representation of a test that uses the variable registry, the storeURL function is in the controller and available in the IDE for storing a target links address to use later.

{"method": "storeURL", "params": {"link": "[Chandler]"}, "version": "0.1"} {"method": "open", "params": {"url":"{$[Chandler]}"}}

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.