Command Line API
See the section on running tests in Getting Started.
Actions simulate user interaction with the page.
Opens a URL. It takes two arguments: a mandatory URL and an optional viewport size. If not specified, the viewport size will default to 1280x1280.
open http://www.google.com
open http://www.google.com 1024x768
Go one page back in history.
back
Go one page forward in history.
forward
Moves the mouse pointer. It takes one mandatory arguments which can be either a CSS selector or a set of coordinates on the page. The pointer is not moved to the destination instantly but follows a path across the page.
moveMouseTo .hideDialog
moveMouseTo 519, 1204
If a selector is specified, Scout will first wait for at least one element matching the selector to become visible. It will then scroll the element into view (if necessary) and then move the mouse to it.
Executes a moveMouseTo with the same argument and then a left mouse click.
click .hideDialog
click 519, 1204
Executes a moveMouseTo with the same argument and then a double left mouse click.
dblclick .toggle
Executes sequential typing of keys into an element. It takes two mandatory arguments: a CSS selector and a string representing the characters that should be typed. This string can contain special instructions in the form of <KeyName> that will simulate special keys, like Tab, Enter, Up and Down.
type input[name="q"] This is a test<Enter>
type .autocomplete scout<Down><Down><Enter>
Before typing, Scout will first perform a click on the specified element. This includes waiting for the element to become visible, the moveMouseTo, etc.
Chooses one or more options from a <select> based on the option's text content.
choose [name="language"] Nederlands
choose .input-skills HTML CSS JavaScript
Choosing more than one value only works on <select multiple>.
Selects a file as value for a file input. The second parameter is the path to the file relative to the .scout file.
uploadFile input[name="avatar"] my_avatar.png
Resizes the viewport to the specified dimensions. This will fire a JavaScript onresize event.
resize 800x600
Assertions check the page for certain properties.
Checks if the argument is a substring of the document title.
assertTitle My Site - Homepage
Checks if the argument is a substring of the page URL.
assertPage /shop/products
Checks if there is an element that matches the selector that contains the specified text.
assertText .greeting Hello, world.
Checks if there is an element that matches the selector.
assertExists a[href="#top"]
Checks if there is a visible element that matches the selector.
assertVisible .confirm-dialog
Checks if there is no visible element that matches the selector.
assertHidden .confirm-dialog
Checks if there is an element that matches the selector that has no visible children.
assertEmpty #shopping_basket > ul
Checks if there is an element that matches the selector that has at least one visible child.
assertNotEmpty #shopping_basket > ul
Checks if the number of visible elements matching the selector is equal to the second argument.
assertLength #shopping_basket li 10
Checks if the number of visible elements matching the selector is at least equal to the second argument.
assertMinLength #shopping_basket li 6
Checks if the number of visible elements matching the selector is at most equal to the second argument.
assertMaxLength #shopping_basket li 15
Checks if the value attribute of the element matching the selector is equal to the second argument.
assertValue [name="city"] Detroit
Checks if there is an element matching the selector that has the second argument as a class name.
assertHasClass #main_menu li .selected
Checks if there is no element matching the selector that has the second argument as a class name.
assertNotHasClass #main_menu li .disabled
Checks if there is an element matching the selector that is disabled.
assertDisabled input[type="submit"]
Makes a screendump and checks if it matches a previously made screendump. It takes two arguments: a mandatory file name (without extension) and an optional selector specifying which part of the screen should be dumped. If no selector is specified, the entire viewport will be dumped.
If there is no previously saved screendump, it will create it for future tests and pass the assert.
assertResembles screendump-loginpage
assertResembles screendump-loginform form[action="/login"]
A line starting with # is commented and will be ignored.
# This is a comment
Logs the text after the ## to the terminal
## This is a log statement
Sets a PhantomJS page setting to the specified value. See the PhantomJS documentation for a complete list of settings and their effects.
# This sets basic HTTP auth
@userName my_user_name
@password my_password
Setting @javascriptEnabled to false will break Scout.
Makes an action or assert optional. It will be tried once and skipped when it fails.
# This will deal with the cookies dialog if it appears
?click "Accept cookies"
Saves a screendump to disk. It takes two arguments: a mandatory file name (without extension) and an optional selector specifying which part of the screen should be dumped. If no selector is specified, the entire viewport will be dumped. Screendumps are saved as .png in the directory where Scout was called.
# Saves "entire_viewport.png"
screendump entire_viewport
# Saves "partial.png"
screendump partial .some-selector
Stores the text or value (in case of an <input> or <select>) of an element in a temporary variable. Stored variables can be used as {varname}. More info on variables
# Store the value of a password field in a variable called pwd
remember :password pwd
# Store the text content of a paragraph in a variable called txt
remember p:first txt
Includes another .scout file as part of the current test file. Useful for instructions that are required for more than one test file, e.g. submitting a login form. The include argument is a path relative to the including file. Includes can include other files.
include ../common/_login.scout
Test files that are prefixed with an underscore are only run when included by another file or when explicitly passed via the command line.
Intercepts requests matching the pattern (which is converted to a regular expression) and responds with the contents of the specified file. The path to the file is relative to the .scout file.
If the request matches more than one registered pattern, the pattern/file combination that was registered first is used.
mockRequest /api/users mocks/users.json
While the most common use case will be mocking Ajax requests, mockRequest can mock any request made by the page: CSS, JavaScript, images, etc.
Removes registered request mocks and restores the original setup.
# Stop mocking this pattern with this file
unmockRequest /api/users mocks/users.json
# Stop mocking this pattern with any file
unmockRequest /api/users
# Stop mocking entirely
unmockRequest
All standard CSS3 selectors can be used to target elements, as well as all the convenient jQuery extensions, like :checkbox, :has() and :odd.
click :submit
assertVisible #modal_dialog
assertHasClass input[name="email"] .input-error
Besides the standard jQuery selectors, Scout supports a shortcut for selecting by text content: if a text in double quotes is passed, it will look for elements matching that text exactly. This can be used in place of any argument that expects a selector.
click "Next page"
assertVisible "Welcome, John Connor"
assertHasClass "Features" .selected
Sometimes, usually when testing a form, you need the ability to generate random strings. For example, when you test a registration form you might need a unique email address to prevent any "already registered" type errors.
Scout can generate random strings of any length with {{...}}, where ... can have the following formats:
{{length}}length characters.{{variable_name:length}}length characters and stores it in variable_name.{{length:"character_list"}}length characters from character_list.{{variable_name:length:"character_list"}}length characters from character_list and stores it in variable_name.
length must be an integer > 0.
variable_name can contain only lowercase a-z and underscores.
character_list must be surrounded by " and must contain at least one character.
The default character list is: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_-.0123456789.
# Type a random password of 8 characters
type [name="password"] {{8}}
# Type a random username of 8 lowercase vowels
type [name="username"] {{8:"aeiou"}}
# Type a random phone number of 10 numbers and store it in "telephone"
type [name="phone"] {{telephone:10:"0123456789"}}
# The {{...}} pattern can occur multiple times in any argument.
type [name="email"] {{4}}@{{6}}.com
Variables that have been stored with the remember command can be reused with the {varname} pattern.
type [name="username"] {{8}}
remember [name="username"] username
assertText .info {username} is still available
See the section on running tests in Getting Started.