The Controller API
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:
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
open
| Parameters | |
| url | Open a given url for testing |
click
| Parameters | |
| All Locators | Click on the given node |
doubleClick
| Parameters | |
| All Locators | Double click on a given node |
select
| Parameters | |
| 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
| Parameters | |
| All Locators | Fire the mousedown event on a given node |
mouseUp
| Parameters | |
| All Locators | Fire the mouseup event on a given node |
mouseOver
| Parameters | |
| All Locators | Fire the mouseover event on a given node |
mouseOut
| Parameters | |
| All Locators | Fire the mouseout event on a given node |
mouseMoveTo
| Parameters | |
| coords | Move the mouse from it's current location to a new set of coordinates. ex. (100,200) |
mouseMove
| Parameters | |
| coords | Move the mouse from one (x,y) coordinate to another (x,y) coordinate, ex. '(startx,starty),(endx,endy)' |
dragDropElem
| Parameters | |
| All Locators, pixels | Moves a DOM element on the page by a specified offset. Format; (number of x pixels, number of y pixels), ex. (100,30) |
dragDropAbs
| Parameters | |
| 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
| Parameters | |
| All Locators, All Locators | Moves one element to another element handling all of the coordinate calculation for you. |
reWriteAlert
| Parameters | |
| None | Override the window.alert function to send the alert content to the output tab. |
check
| Parameters | |
| All Locators | Toggle a given checkbox. |
radio
| Parameters | |
| All Locators | Select a given radio button |
type
| Parameters | |
| All Locators | Enter data into any form text input field |
keyPress
| Parameters | |
| All Locators, Options comma delimited string | keySequence, canBubble, controlKeyDown, altKeyDown, shiftKeyDown, metaKeyDown (ex. a,true,false,false,false,false) |
keyDown
| Parameters | |
| All Locators, Options comma delimited string | keySequence, canBubble, controlKeyDown, altKeyDown, shiftKeyDown, metaKeyDown (ex. a,true,false,false,false,false) |
keyUp
| Parameters | |
| All Locators, Options comma delimited string | keySequence, canBubble, controlKeyDown, altKeyDown, shiftKeyDown, metaKeyDown (ex. a,true,false,false,false,false) |
storeURL
| Parameters | |
| 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} |
- See Javascript Variable Registry for more details.
storeVarFromJS
| Parameters | |
| options | Options is a pipe delimited string with two parts, example string: 'test|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}"}}.
storeVarFromLocAttrib
| Parameters | |
| "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.
execJS
| Parameters | |
| js | A JavaScript string to be executed against the testing window. |
execIDEJS
| Parameters | |
| js | A JavaScript string to be executed in the IDE window, usually used for accessing the registry. |
waits.sleep
| Parameters | |
| milliseconds | Make the browser sleep for a given number of seconds |
waits.forElement
| Parameters | |
| timeout | Waits for a DOM element to exist, or times out |
waits.forElementProperty
| Parameters | |
| 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
| Parameters | |
| timeout | Waits for a new page to load in the testing window |
waits.forJS
| Parameters | |
| js | Waits for the result of the eval'd string of JavaScript code to return true |
waits.forNotTitle
| Parameters | |
| "title", timeout | Waits for the testing window to NOT have the provided title. |
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.
{"method": "commands.getPageText", "params": {}}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.
asserts.assertText
| Parameters | |
| "All Locators", validator | Validates the existence of text in a provided DOM node |
asserts. assertNode
| Parameters | |
| "All Locators" | Asserts that a node exists in the DOM in the testing window |
asserts. assertValue
| Parameters | |
| "All Locators", validator | Assert that a value exists in the provided form element |
asserts. assertSelected
| Parameters | |
| "All Locators", validator | Assert that an option was selected in a drop down or list element |
asserts. assertChecked
| Parameters | |
| "All Locators" | Assert that a selected checkbox was checked |
asserts. assertProperty
| Parameters | |
| "All Locators", validator | Assert the value of a provided DOM nodes property, ex. ( disabled|true or style.border|1px ) |
asserts. assertImageLoaded
| Parameters | |
| "All Locators" | Assert that an image is loaded on the page |
asserts. assertJS
| Parameters | |
| "js" | Assert a JavaScript expression |
asserts. assertElemJS
| Parameters | |
| "js" | Asserting javascript with an element object available. ex. element.innerHTML.indexOf('something') != -1 |
Adding your own assertion
See 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]}"}}
