Quick reference for Google's Web Puppeteer:
Returns true iff the element is present and has the given attribute key/value pair. Since the name of the attribute specifying the element's class is either called 'class' or 'className', depending on the browser, use clazz() instead of this function for testing the value of the class with cross-browser compatibility.
Returns true if the element is shown, and if it is, blurs it.
Returns true iff the element is shown, and if it is, clears the user input from the element. If the element contains text, clears the text. If it is a selected checkbox, clicks it to deselect it.
Returns true iff the element is shown, and if it is clicks an element at the optional x and y client coordinates, relative to the element. If this click has a target URL, ensure the link is relative so it won't go off-site.
Returns true iff the element is shown, and if it is double-clicks an element at the optional x and y client coordinates, relative to the element.
Returns true if the element is shown, and if it is, drags the element by (dx, dy).
Returns true if the element is shown, and if it is, focuses it.
Returns true if the element is shown, and if it is follow's the link of the given anchor element. Do not use follow() to simulate left-clicking a link: use click() instead. Use follow() only to simulate opening a link in a new window/tab.
Returns true if the element is shown, and if it is, inputs a value to the given text or password input element or textarea.
Returns true iff the element is shown, and if it is, fires a mouse event to the element at the optional x and y coordinates, relative to the element. No action if the element is null (to make it easier to trigger multiple mouse events in sequence).
Returns true iff the element is shown, and if it is, moves the mouse to the element, over the optional x and y coordinates relative to the element.
Returns true iff the element has the given opacity.
Pinches the target by the given distance on multitouch browsers. A positive distance makes the fingers move inwards towards each other and a negative distance makes them move outward away from each other. The optional coordinate is the point the fingers move towards, and if not provided, defaults to the center of the element.
Returns whether the element is present in the DOM.
Returns true iff the element is present and has the given property key/value pair. Since the name of the property specifying the element's inner text is either called 'innerText' or 'textContent', depending on the browser, use text() instead of this function for testing the value of the text with cross-browser compatibility.
Returns true iff the element is shown, and if it is right-clicks an element at the optional x and y client coordinates, relative to the element.
Rotates the target by the given angle for multitouch browsers. A positive angle indicates a clockwise rotation and a positive value indicates a counter-clockwise rotation. The optional coordinate is the point the fingers rotate around.
Returns true iff the element is shown, and if it is, scrolls the mouse wheel by the specified number of ticks on the element at the optional x and y coordinates relative to the element. A positive number of ticks scrolls downward and a negative number scrolls upward.
Returns true if the element is shown, and if it is, selects the given option element, checkbox, or radio button. Deprecated: Use click() instead.
Returns whether the given element is selected. Throws an exception if the element is not an option, checkbox, or radio button.
Returns whether the element is shown to the user.
Returns true iff the element is present and has a style attribute with the given key/value pair.
Returns true iff the element is present and has the given visible text.
Types a string, presses a key or key sequence to an element and returns true iff the element is shown. The parameters after the element can be: 1. A string, like: run(type, textbox, 'abc') 2. A key code to be pressed, like: run(type, textbox, goog.events.KeyCodes.ENTER) 3. An array of strings or keycodes, like: run(type, textbox, ['a', goog.events.KeyCodes.ENTER, 'b']) 4. A variable number of any of the above, like: run(type, textbox, 'a', goog.events.KeyCodes.ENTER, ['b', 'c'])
Returns a multi-element command that is true if all elements that match an xpath satisfy the given command. The multi-element command accepts an xpath and a variable number of arguments and returns true if all elements that match the xpath satisfy the command applied to those arguments. Example: - run(all(text), '//a', 'hello'); waits until all 'a' elements have text equal to 'hello'
Parameters:
command
-function((string | !Element), ...) : *
- Single-element command.
Returns: Multi-element command. function((string | !Array.<!Element>), ...[*]) : boolean
Asserts a value or return value of predicate. Throws an exception and stops testing if it is false.
Parameters:
-
value
-*
- Value or function to evaluate. -
opt_comment
-string=
- Comment to echo if false.
Asserts that both arguments are defined and equal. This simple function should not be inlined so that the stack trace shows the arguments during debugging.
Parameters:
-
x
-*
- Any object. -
y
-*
- Any object. -
opt_comment
-string=
- Comment on the equality.
Asserts that both arguments are defined and not equal. This simple function should not be inlined so that the stack trace shows the arguments during debugging.
Parameters:
-
x
-*
- Any object. -
y
-*
- Any object. -
opt_comment
-string=
- Comment on the inequality.
Go back in the browser history. The number of pages to go back can optionally be specified and defaults to 1.
Parameters:
opt_numPages
-number=
- Number of pages to go back.
Returns a multi-element command that returns true iff the specified number of elements matching an xpath satisfy the given command. The multi-element commands accepts an xpath and a variable number of arguments and returns true if the number of elements that both match the xpath and satisfy the command applied to those arguments is in the given range. If the opt_max is not provided, it defaults to num. If it is provided, but null, there is no maximum number. Examples: - run(count(shown, 3) '//a'); waits until exactly 3 'a' elements are shown on the page - run(count(shown, 3, 5), '//a'); waits until between 3 and 5 (inclusive) a's are shown on the page - run(count(shown, 0, 3), '//a'); waits until 3 or less a's are shown on the page - run(count(shown, 3, null), '//a'); waits until 3 or more a's are shown on the page
Parameters:
-
command
-function((string | !Element), ...) : *
- Single-element command. -
num
-number
- Minimum number of times the command is expected to not return false. -
opt_max
-?number=
- Maximum number of times the command is expected to not return false. If not provided, defaults to opt_min. If provided but null, there is no maximum limit.
Returns: Multi-element command. function((string | !Array.<!Element>), ...[*]) : boolean
Responds to prompt/confirm/alert dialog boxes. Given a command, returns a new command that performs the new command and waits for a dialog box to appear. When the dialog appears, responds to it with the given response value. A 'prompt' dialog must be given a response of type string, a 'confirm' dialog must be given a response of type boolean, and for an 'alert' dialog, a response type must not be provided.
Note that the dialog() function will not work when the page under test aliases and calls its window's alert, confirm, or prompt functions. Example code in a page under test in which the dialog() function will not work:
var x = window.alert; x('Hello, world!'); If Puppet's setup phase has not stubbed out the function prior to the alias assignment, then the invocation of x will cause a dialog to appear, and the test will hang and fail when it eventually reaches the whole test timeout. If Puppet's setup phase has stubbed out the function, this dialog() command will nevertheless be unable to set an expectation that an alert will appear, and the invocation of x will fail immediately due to an "unexpected" dialog. If x is accessible from the page's window object, both problems can be avoided if the test stubs out x itself before the page invokes it.
Parameters:
-
command
-function(...):*
- Command expected to trigger the dialog box. -
opt_response
-(string | boolean)=
- Response to the dialog box.
Go forward in the browser history. The number of pages to go forward can optionally be specified and defaults to 1.
Parameters:
opt_numPages
-number=
- Number of pages to go forward.
Use this command whenever a new page is to be loaded. If given a URL, it loads the URL and waits until the document is loaded. If given a command, it returns a new command that performs the given command and then waits for a document to be loaded.
Parameters:
urlOrCommand
-string | function(...) : *
- URL of the document to be loaded or a command to performed before the new document is loaded.
Returns: If given a command, this is the new command that also waits for the page to load. undefined | function(...[*]) : *
Returns a multi-element command that is true if none of the elements that match an xpath satisfy the given predicate. The multi-element command accepts an xpath and a variable number of arguments and returns true if none of the elements that match the xpath satisfy the predicate applied to those arguments. Example: - run(none(text), '//a', 'hello'); waits until none of the 'a' elements has text equal to 'hello'
Parameters:
command
-function((string | !Element), ...) : *
- Single-element command.
Returns: Multi-element command. function((string | !Array.<!Element>), ...[*]) : boolean
Negates the given command.
Parameters:
command
-function(...) : *
- Command.
Returns: Negated command. function(...[*]) : boolean
Reloads the current page and waits until the document is fully loaded.
Queues a command to be executed. Calling run(command, arg1, arg2, ...) queues the call command(arg1, arg2, ...) to be executed. If the return value of the call === false, then the command is retried after a wait period. The command is continually retried until the return value !== false. Note that a command that doesn't explicitly return has a return value of undefined, which is !== false and, therefore, will not be retried. This function also inserts pause() based on ?cmds or ?lines.
Parameters:
-
command
-(function(...) : *)=
- Command to be queued. -
var_args
-*
- Arguments to the function.
Sleeps the test execution for the specified number of seconds. Please avoid using this command if at all possible. It should be used only as a last resort, when waiting for any other changes on the page does not suffice. It is better to add hooks into the page being tested that a test can wait for than to use sleep commands. This command has no effect if the execution is paused.
Parameters:
sec
-number
- Number of seconds to sleep.
Returns a multi-element command that is true if there exists an element that matches an xpath that satisfied the given command. The multi-element command accepts an xpath and a variable number of arguments and returns true if an element that matches the xpath satisfies the command applied to those arguments. Example: - run(some(text), '//a', 'hello'); waits until some 'a' element has text equal to 'hello'
Parameters:
command
-function((string | !Element), ...) : *
- Single-element command.
Returns: Multi-element command. function((string | !Array.<!Element>), ...[*]) : boolean
Stops the test execution, skipping the rest of the commands. Useful for disabling parts of tests that require certain browsers or operating systems.