Skip to content

Supported DSL

Jump to bottom
Branko Juric edited this page Aug 6, 2019 · 102 revisions

Gwen logo

Gwen-Web DSL

Gwen evaluates steps by matching them against the DSL described here. Each Gherkin step must start with a Given, When, Then, And, or But keyword followed by a string that matches one of the expressions below. The expression matched is the operation that will be performed.

This page describes the definitive list of built in steps that Gwen supports.

Since v1.0.0

I navigate to "<url>"
  • Opens the browser to the given URL.
    • <url> = the URL to navigate to (can be a DocString)
<element> can be located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>"
the page title <should|should not> <be|contain|start with|end with|match regex|match xpath|match template|match template file> "<expression>"
  • Checks that the page title matches or does not match a given expression.
    • <expression> = the expression to match against (can be a DocString)
  • Notes:
    • match template and match template file supported since v2.16.0
the page title <should|should not> <be|contain|start with|end with|match regex|match xpath> <attribute>
  • Checks that the page title matches or does not match a bound attribute value
    • <attribute> = the attribute to match against
<element> <should|should not> be <displayed|hidden|checked|ticked|unchecked|unticked|enabled|disabled>
  • Checks that an element should or should not be in a given state.
    • <element> = the web element to check the state of
  • Notes:
    • ticked and unticked supported since v2.4.0
<element|attribute> <should|should not> <be|contain|start with|end with|match regex|match xpath|match template|match template file> "<expression>"
  • Checks that the text value of an element matches or does not match a given expression.
    • <element|attribute> = the web element or bound attribute to check
    • <expression> = the expression to match against (can be a DocString)
  • Notes:
    • match template and match template file supported since v2.16.0
<element|attribute> <should|should not> <be|contain|start with|end with|match regex|match xpath> <attribute>
  • Checks that the text value of an element matches or does not match a bound attribute.
    • <element|attribute> = the web element or bound attribute to check
    • <attribute> = the name of the bound attribute containing the value to match against
the current URL <should|should not> <be|contain|start with|end with|match regex|match xpath|match template|match template file> "<expression>"
  • Checks that the current URL in the browser matches or does not match a given expression.
    • <expression> = the expression to match against (can be a DocString)
  • Notes:
    • match template and match template file supported since v2.16.0
the current URL <should|should not> <be|contain|start with|end with|match regex|match xpath> <attribute>
  • Checks that the current URL in the browser matches or does not match a bound attribute.
    • <attribute> = the name of the bound attribute containing the value to match against
<dropdown> <text|value> <should|should not> <be|contain|start with|end with|match regex|match xpath|match template|match template file> "<expression>"
  • Checks that a dropdown selection matches or does not match a given expression.
    • <dropdown> = the dropdown element to check
    • <text|value> = use text to match selected option text, or value to match selection option value
    • <expression> = the expression to match against (can be a DocString)
  • Notes:
    • match template and match template file supported since v2.16.0
<dropdown> <text|value> <should|should not> <be|contain|start with|end with|match regex|match xpath> <attribute>
  • Checks that a dropdown selection matches or does not match a bound attribute.
    • <dropdown> = the dropdown element to check
    • <text|value> = use text to match selected option text, or value to match selection option value
    • <attribute> = the name of the bound attribute containing the value to match against
I capture the <text|node|nodeset> in <element|attribute|property> by xpath "<expression>" as <attribute>
  • Extracts and binds a value by xpath from an element, attribute, or property setting into an attribute.
    • <element|attribute|property> = the element, attribute, or property setting to extract the value from
    • <expression> = the extractor expression
    • <attribute> = the attribute to store the captured value into
I capture the text in <element|attribute|property> by regex "<expression>" as <attribute>
  • Extracts and binds a value by regex from an element, attribute, or property setting into an attribute.
    • <element|attribute|property> = the element, attribute, or property setting to extract the value from
    • <expression> = the extractor expression
    • <attribute> = the attribute to store the captured value into
I capture the text in the current URL by regex "<expression>" as <attribute>
  • Extracts and binds a value by regex from the current URL in the browser into an attribute.
    • <expression> = the extractor expression
    • <attribute> = the attribute to store the captured value into
I capture the current URL
  • Binds the current browser URL to an attribute named URL in the current page scope.
I capture the current URL as <attribute>
  • Binds the current browser URL to a named attribute in the current page scope.
    • <attribute> = the attribute to bind the URL to
I capture <element|attribute|property> as <attribute>
  • Captures the text value of an element, attribute, or property and binds it to a named attribute.
    • <element|attribute|property> = the web element, attribute, or property to capture the text of
    • <attribute> = the name of the attribute to bind the value to
I capture <element|attribute|property>
  • Captures the text value of an element and binds it to an attribute of the same name.
    • <element|attribute|property> = the web element, attribute
I capture <dropdown> <text|value> as <attribute>
  • Captures the dropdown selection and binds it to a named attribute.
    • <dropdown> = the dropdown element to capture the selection of
    • <text|value> = use text to capture the selected option text, or value to capture the selected option value
    • <attribute> = the name of the attribute to bind the value to
I capture <dropdown> <text|value>
  • Captures the dropdown selection and binds it to an attribute of the same name.
    • <dropdown> = the dropdown web element to capture the selection of and store in the attribute of the same name
    • <text|value> = use text to capture the selected option text, or value to capture the selected option value
I am on the <page>
  • Puts the given page in scope.
    • <page> = the name of the page to put in scope
the url will be "<url>"
  • Binds the given URL to the current page scope.
the url will be defined by <property|setting> "<name>"
  • Binds the URL defined in the named property to the current page scope.
    • <name> = name of property containing the URL (can be a DocString)
I navigate to the <page>
  • Opens the browser to the URL bound to the given page.
    • <page> = the name of the page to navigate to
I scroll to the <top|bottom> of <element>
  • Scrolls to the top or bottom of the named element.
    • <element> = name of web element to scroll to
my <name> <property|setting> <is|will be> "<value>"
  • Sets a Gwen runtime setting value.
    • <name> = the name of the Gwen setting to set
    • <value> = the value to set
  • Notes:
    • As of gwen-web version 2.21.0, this DSL stores all values as thread local settings (instead of system properties).
      • This supports different settings for different features in the case of parallel execution.
      • Settings loaded from properties files and system properties at startup time are not replaced, but can be overridden with values set here.
      • Setting arbitrary system properties (that is: non Gwen settings that do not start with gwen.) is not supported.
      • See also: I reset my <name> property|setting
    • Prior to gwen-web version 2.21.0, this DSL stored all values as JVM-global system properties and caution was advised because race conditions could occur if multiple features changed the same system property.
<attribute> <is|will be> defined by javascript "<expression>"
  • Binds a JavaScript expression to a named attribute. The evaluation of the script will occur when the attribute is referenced at runtime.
    • <attribute> = the name of the attribute to bind the value to
    • <expression> = the JavaScript expression or anonymous function that returns a value (can be a DocString).
      • For an expression: no return prefix is required
      • For an anonymous function: the syntax is (function(){ body })() where body must return a value
<attribute> <is|will be> defined by <system process|property|setting> "<expression>"
  • Binds an expression to a named attribute. The evaluation will occur when the attribute is referenced at runtime.
    • <attribute> = the name of the attribute to bind the value to
    • <expression> = the expression that will yield the value to bind (can be a DocString)
<attribute> <is|will be> defined by the <text|node|nodeset> in <source> by xpath "<expression>"
  • Evaluates an xpath expression on a source attribute and binds the returned value to a another named attribute. The evaluation occurs when the attribute is referenced.
    • <attribute> = the name of the attribute to bind the value to
    • <source> = the source attribute to evaluate the xpath expression on
    • <expression> = the xpath expression that will yield the value from the source to bind (can be a DocString)
<attribute> <is|will be> defined in <source> by regex "<expression>"
  • Evaluates a regex expression on a source attribute and binds the returned value to a another named attribute. The evaluation occurs when the attribute is referenced.
    • <attribute> = the name of the attribute to bind the value to
    • <source> = the source attribute to evaluate the regex expression on
    • <expression> = the regex expression that will yield the value from the source to bind (can be a DocString)
<attribute> <is|will be> "<value>"
  • Binds a given value to a named attribute.
    • <attribute> = the name of the attribute to bind the value to
    • <value> = the value to bind (can be a DocString)
I wait for <element> text for <duration> <second|seconds>
  • Waits a given number of seconds for an element's text to be loaded.
    • <element> = the element to wait for text on
    • <duration> = the number of seconds to wait before timing out
I wait for <element> text
  • Waits for an elements text to be loaded.
    • <element> = the element to wait for text on (timeout occurs after configured "gwen.web.wait.seconds", or 10 seconds by default)
I wait for <element> for <duration> <second|seconds>
  • Waits a given number of seconds for a web element to be available on the page.
    • <element> = the web element to wait for
    • <duration> = the number of seconds to wait before timing out
I wait for <element>
  • Waits for a web element to be available on the page.
    • <element> = the web element to wait for (timeout occurs after configured "gwen.web.wait.seconds", or 10 seconds by default)
I clear <element>
  • Clears a text element.
    • <element> = the web element to clear the text of
I press <enter|tab> in <element>
  • Sends the enter or tab key to a web element (emulates user pressing a non alphanumeric key in the element).
    • <element> = the element to send the key to
I <enter|type> "<value>" in <element>
  • Types or enters a value into a field ("type" just types the value, "enter" types the value and then sends the enter key to element).
    • <value> = the value to type or enter
    • <element> = the web element to type or enter the value into
I <enter|type> <attribute> in <element>
  • Types or enters a bound attribute value into a field ("type" just types the value, "enter" types the value and then sends the enter key to element).
    • <attribute> = the name of the attribute containing the value to type or enter
    • <element> = the web element to type or enter the value into
I <select|deselect> the <position><st|nd|rd|th> option in <element>
  • Selects the option in a dropdown at a given position.
    • <position> = the position of the option to select (first is 1)
    • <element> = the dropdown element to select
  • Notes:
    • deselect for multi-value dropdowns supported since v2.13.0
I <select|deselect> "<value>" in <element>
  • Selects the option (by visible text) in a dropdown containing the given value.
    • <value> = the value to select
    • <element> = the dropdown element to select
  • Notes:
    • deselect for multi-value dropdowns supported since v2.13.0
I <select|deselect> "<value>" in <element> by value
  • Selects the option (by value) in a dropdown containing the given value.
    • <value> = the value to select
    • <element> = the dropdown element to select
  • Notes:
    • deselect for multi-value dropdowns supported since v2.13.0
I <select|deselect> <attribute> in <element>
  • Selects the option (by visible text) in a dropdown containing a bound attribute value.
    • <attribute> = the name of the attribute containing the value to select
    • <element> = the dropdown element to select
  • Notes:
    • deselect for multi-value dropdowns supported since v2.13.0
I <select|deselect> <attribute> in <element> by value
  • Selects the option (by value) in a dropdown containing a bound attribute value.
    • <attribute> = the name of the attribute containing the value to select
    • <element> = the dropdown element to select
  • Notes:
    • deselect for multi-value dropdowns supported since v2.13.0
I <click|right click|double click|submit|check|tick|uncheck|untick|move to> <element>
  • Performs the specified action on an element.
    • <element> = the element to perform the action on
  • Notes:
    • tick and untick supported since v2.4.0
    • right click supported since v2.8.0
    • double click and move to supported since v2.12.0
I wait <duration> <second|seconds> when <element> is <clicked|right clicked|double clicked|submitted|checked|ticked|unchecked|unticked|selected|deselected|typed|entered|tabbed|cleared|moved to>
  • Waits a given number of seconds after an action is performed on an element.
    • <duration> = the number of seconds to wait
    • <element> = the element the action was performed on
  • Notes:
    • ticked and unticked supported since v2.4.0
    • right clicked supported since v2.8.0
    • double clicked and moved to supported since v2.12.0
    • deselected for multi-value dropdowns since v2.13.0
I wait until <condition> when <element> is <clicked|right clicked|double clicked|submitted|checked|ticked|unchecked|unticked|selected|deselected|typed|entered|tabbed|cleared|moved to>
  • Waits for a condition to be true after an action is performed on an element.
    • <condition> = the name of a javascript binding that returns true or false (a JavaScript predicate)
    • <element> = the element the action was performed on
  • Notes:
    • ticked and unticked supported since v2.4.0
    • right clicked supported since v2.8.0
    • double clicked and moved to supported since v2.12.0
    • deselected for multi-value dropdowns supported since v2.13.0
I wait until "<javascript>"
  • Waits until the given javascript expression or anonymous function returns true on the current page.
    • <javascript> = the JavaScript expression or anonymous function that returns true or false. (can be a DocString).
      • For an expression: no return prefix is required
      • For an anonymous function: the syntax is (function(){ body })() where body must return a value
I wait until <condition>
  • Waits until a condition is true on the current page.
    • <condition> = the name of a javascript binding that returns true or false (a JavaScript predicate)
I wait <duration> <second|seconds>
  • Waits for a given number of seconds to lapse.
    • <duration> = the number of seconds to wait
I <highlight|locate> <element>
  • Locates and highlights the given element on the current page.
    • <element> = the element to highlight
I execute system process "<process>"
  • Executes a local system process.
    • <process> = the system process to execute (can be a DocString)
I execute a unix system process "<process>"
  • Executes a local unix system process.
    • <process> = the unix system process to execute (can be a DocString)
I refresh the current page
  • Refreshes the current page.
I base64 decode <element|attribute> as <attribute>
  • Base64 encodes the given element or attribute value and stores the result in named attribute.
    • <element|attribute> = the web element or bound attribute to decode
    • <attribute> = the attribute to bind the result to
I base64 decode <element|attribute>
  • Base64 encodes the given element or attribute value and stores the result in the attribute of the same name.
    • <element|attribute> = the web element or bound attribute to decode
<step> <until|while> <condition>
  • Repeatedly performs the given step until or while a condition is satisfied, using default delay and timeout periods. The default delay between iterations is one tenth of the configured gwen.web.wait.seconds setting (or 1 second if not set) The default timeout period is 30 times the delay.
    • <step> = the step to repeat
    • <condition> = the name of a javascript binding that returns true or false (a JavaScript predicate)
  • Notes:
    • The current iteration number (starting at 1) is available as an implicit attribute named iteration number and can be accessed by reference or interpolation.

Since v1.1.0

<element> can be located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" in <container>
  • Creates a web element locator binding inside another web element locator binding ~ locator chaining. Timeout = gwen.locator.wait.seconds.
    • <element> = name of web element
    • <expression> = the lookup expression
    • <container> = the container element (a frame, div, or other container element)
  • Notes:
    • If using javascript locator, you can reference the container element as containerElem in <expression> (since v2.11.0)

Since v1.2.0

I start a new browser
  • Starts a new 'default' browser session (closes existing one if it is open first).
I close the current browser
  • Closes the current browser session (if one is open).
I start a browser for <session>
  • Starts a new browser session with the given name (closes existing one if it is open first).
    • <session> = the unique name to assign to the new browser session
I close the browser for <session>
  • Closes a named browser session (if one is open).
    • <session> = the name of the browser session to close
I switch to <session>
  • Switches to a named browser session (starts a new one if required). All actions performed after this execute in the named session.
    • <session> = the name of the browser session to switch to
I <click|right click|double click|check|tick|uncheck|untick|move to> <element> of <context>
  • Performs the specified action on a context sensitive element.
    • <element> = the element to perform the action on
    • <context> = the context element to move into (in order to activate )
  • Notes:
    • tick and untick supported since v2.4.0
    • right click supported since v2.8.0
    • double click and move to supported since v2.12.0

Since v1.3.0

I close the browser
  • Closes the current browser session (if one is open).

Since v1.4.0

I <accept|dismiss> the <alert|confirmation> popup
  • Accepts or dismisses an alert or confirmation popup box. Accept clicks OK and dismiss clicks Cancel. Cancel is only available in confirmation popups.
I switch to the child <window|tab>
  • Passes control over to the most recently opened child window (without closing the parent window).
I close the child <window|tab>
  • Closes the currently active child window and passes control back to the parent window.
I switch to the parent <window|tab>
  • Passes control back to the parent window (without closing the currently active child window).
the page title <should|should not> match json path "<expression>"
  • Checks that the page title matches or does not match a given JSON path expression.
the page title <should|should not> match json path <attribute>
  • Checks that the page title matches or does not match a bound JSON path.
    • <attribute> = the attribute containing the JSON path to match against
<element|attribute> <should|should not> match json path "<expression>"
  • Checks that the text value of an element matches or does not match a bound JSON path.
    • <element|attribute> = the web element or bound attribute to check
    • <expression> = the JSON path to match against (can be a DocString)
<dropdown> <text|value> <should|should not> match json path "<expression>"
  • Checks that a dropdown selection matches or does not match a given JSON path.
    • <dropdown> = the dropdown element to check
    • <text|value> = text to match selected option text, or value to match selected option value
    • <expression> = the JSON path to match against (can be a DocString)
<dropdown> <text|value> <should|should not> match json path <attribute>
  • Checks that a dropdown selection matches or does not match a bound JSON path.
    • <dropdown> = the dropdown element to check
    • <text|value> = text to match selected option text, or value to match selected option value
    • <attribute> = the name of the bound attribute containing the JSON path to match against
I capture the content in <element|attribute|property> by json path "<expression>" as <attribute>
  • Extracts and binds a value by JSON path from an element, attribute, or property setting into an attribute.
    • <element|attribute|property> = the element, attribute, or property setting to extract the value from
    • <expression> = the JSON path extractor expression
    • <attribute> = the attribute to store the captured value into
<attribute> <is|will be> defined in <source> by json path "<expression>"
  • Evaluates an JSON path on a source attribute and binds the returned value to a another named attribute. The evaluation occurs when the attribute is referenced.
    • <attribute> = the name of the attribute to bind the value to
    • <source> = the source attribute to evaluate the JSON expression on
    • <expression> = the JSON path expression that will yield the value from the source to bind (can be a DocString)

Since v1.6.0

I capture the current screenshot
  • Captures the current screenshot.

Since v1.7.0

<step> <until|while> <condition> using <delayPeriod> <second|millisecond> delay and <timeoutPeriod> <minute|second|millisecond> timeout
  • Repeatedly performs the given step until or while a condition is satisfied, using explicit delay and timeout periods.
    • <step> = the step to repeat
    • <condition> = the name of a javascript binding that returns true or false (a JavaScript predicate)
    • <delayPeriod> = the time to wait between repeats
    • <timeoutPeriod> = the total time to wait before timing out
  • Notes:
    • The current iteration number (starting at 1) is available as an implicit attribute named iteration number and can be accessed by reference or interpolation.
<step> <until|while> <condition> using <delayPeriod> <second|millisecond> delay
  • Repeatedly performs the given step until or while a condition is satisfied, using explicit delay period and default timeout period. The default timeout period is 30 times the delay.
    • <step> = the step to repeat
    • <condition> = the name of the bound attribute containing a javascript predicate expression
    • <delayPeriod> = the time to wait between repeats
  • Notes:
    • The current iteration number (starting at 1) is available as an implicit attribute named iteration number and can be accessed by reference or interpolation.
<step> <until|while> <condition> using <timeoutPeriod> <minute|second|millisecond> timeout
  • Repeatedly performs the given step until or while a condition is satisfied, using default delay period and explicit timeout period. The default delay between iterations is one tenth of the configured gwen.web.wait.seconds setting (or 1 second if not set).
    • <step> = the step to repeat
    • <condition> = the name of a javascript binding that returns true or false (a JavaScript predicate)
    • <timeoutPeriod> = the total time to wait before timing out
  • Notes:
    • The current iteration number (starting at 1) is available as an implicit attribute named iteration number and can be accessed by reference or interpolation.
<step> <until|while> <condition> using no delay and <timeoutPeriod> <minute|second|millisecond> timeout
  • Repeatedly performs the given step until or while a condition is satisfied, using no delay period and explicit timeout period.
    • <step> = the step to repeat
    • <condition> = the name of the bound attribute containing a javascript predicate expression
    • <timeoutPeriod> = the total time to wait before timing out
  • Notes:
    • The current iteration number (starting at 1) is available as an implicit attribute named iteration number and can be accessed by reference or interpolation.
<step> <until|while> <condition> using no delay
  • Repeatedly performs the given step until or while a condition is satisfied, using no delay period and default timeout period. The default timeout period is 30 times the delay.
    • <step> = the step to repeat
    • <condition> = the name of a javascript binding that returns true or false (a JavaScript predicate)
  • Notes:
    • The current iteration number (starting at 1) is available as an implicit attribute named iteration number and can be accessed by reference or interpolation.

Since v1.8.0

<element> can be <clicked|right clicked|double clicked|submitted|checked|ticked|unchecked|unticked|cleared|selected|deselected|typed|entered|tabbed|moved to> by javascript "<javascript>"
  • Registers a javascript action on an element. When the action is performed, then the javascript will execute.
    • <element> = the web element to perform the action on (a web element binding)
    • <javascript> = a javascript expression or anonymous function that performs the desired action on the element (can be a DocString).
      • The reference to the element is provided to the javascript through an implicit parameter named element
      • For example, "element.click()" will click the element
  • Notes:
    • ticked and unticked supported since v2.4.0
    • right clicked supported since v2.8.0
    • cleared supported since v2.10.0
    • double clicked and moved to supported since v2.12.0
    • selected, deselected, typed, entered, and tabbed supported since 2.17.1

Since v1.11.0

<attribute> <is|will be> defined by file "<filepath>"
  • Binds a file path to a named attribute. The contents of the file are bound to the attribute when it is referenced at evaluation time.
    • <attribute> = the name of the attribute to bind the value to
    • <filepath> = the path to the file (can be a DocString)

Since v2.1.0

<attribute> <is|will be> defined by sql "<selectStmt>" in the <dbName> database
  • Deprecated, use the new v2.10.0 DSL version of this instead which moves the <selectStmt> placeholder to the end of the line to support DocStrings

Since v2.2.0

I resize the window to width <w> and height <h>
  • Resizes the currently active browser window to the given dimensions.
    • <w> = the width in pixels
    • <h> = the height in pixels
I <maximize|maximise> the window
  • Maximizes the currently active browser window to fill the entire screen area.
  • Notes:
    • This may behave inconsistently across platforms.

Since v2.4.0

<step> for each <element> located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>"
  • Repeats a given step for each web element in an iteration of elements. Nothing is performed if no elements are found. Timeout = gwen.locator.wait.seconds.
    • <step> = the step to repeat for each element
    • <element> = the name given to the current element in the iteration
    • <expression> = the lookup expression for the element iteration (can be a DocString)
  • Notes:
    • The current element number (starting at 1) is available as an implicit attribute named <element> number and can be accessed by reference or interpolation.
<step> for each <element> located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" in <container>
  • Repeats a given step for each web element in an iteration of elements in a container. Nothing is performed if no elements are found. Timeout = gwen.locator.wait.seconds.
    • <step> = the step to repeat for each element
    • <element> = the name given to the current element in the iteration
    • <expression> = the lookup expression for the element iteration
    • <container> = the container element (a frame, div, or other container element)
  • Notes:
    • The current element number (starting at 1) is available as an implicit attribute named <element> number and can be accessed by reference or interpolation.
<step> for each <element> in <elements>
  • Repeats a given step for each web element in an iteration of elements. Nothing is performed if no elements are found.
    • <step> = the step to repeat for each element
    • <element> = the name given to the current element in the iteration
    • <elements> = the element iteration locator binding
  • Notes:
    • The current element number (starting at 1) is available as an implicit attribute named <element> number and can be accessed by reference or interpolation.

Since v2.6.0

<attribute> should be absent
  • Checks that a given attribute is absent (not bound to current scope).
    • <attribute> = the bound attribute to check
<source> at <json path|xpath> "<path>" <should|should not> <be|contain|start with|end with|match regex|match xpath|match template|match template file> "<expression>"
  • Checks that value extracted by a JSON or XPath expression on given attribute matches or does not match a given expression.
    • <source> = the source attribute to extract the value from
    • <path> = the JSON path or XPath extractor expression
    • <expression> = the expression to match against (can be a DocString)
  • Notes:
    • match template and match template file supported since v2.16.0

Since v2.8.0

<step> for each data record
  • Executes the given step for each record in a data table.
    • <step> = the step to run for each record
  • Notes:
    • The accessible current record data includes:
      • record.number = the current record number (1st is 1, 2nd is 2, and so on)
      • record.index = the record index starting at 0 (available since gwen-web 2.30.1)
      • data[name] = the data of an element in the current record, where name = name of record element
I <modifiers> <click|right click|double click> <element>
  • Holds down the specified modifier keys and clicks an element.
    • <modifiers> = '+' separated list of modifier keys to hold down (e.g: COMMAND+SHIFT)
    • <element> = the name of the element to click
  • Notes:
    • Modifier keys can be any of the key constants here (case does not have to match)
    • Keys behave differently on different platforms
    • double click supported since v2.12.0
I send "<keys>" to <element>
  • Sends a sequence of keys to an element (for emulating keyboard shortcuts).
    • <modifiers> = comma (',') separated list of keys to send (e.g: CONTROL,C)
    • <element> = the name of the element to send the keys to
  • Notes:
    • Keys can be any single keyboard character or any of the key constants here (case for key constants does not have to match)
    • Keys behave differently on different platforms

Since v2.9.0

I execute javascript "<javascript>"
  • Executes an arbitrary JavaScript expression.
    • <javascript> = the JavaScript expression or anonymous function to execute (can be a DocString).
      • For an expression: no return prefix is required
      • For an anonymous function: the syntax is (function(){ body })() where body must return a value

Since v2.10.0

<attribute> <is|will be> defined in the <dbName> database by sql "<selectStmt>"
  • Binds the result of an SQL select query to a named attribute. The query must return a result in one field only. If more than one record is returned, then the result in the first one will be returned and the others discarded. For best results, you should narrow the query using a where clause to ensure that only one record is returned. If no records are returned, then an error stating that no records were found will be reported. The query will be executed and the result will be bound to the attribute when it is referenced at evaluation time.
    • <attribute> = the name of the attribute to bind the SQL result to
    • <dbName> = the name of database to execute the query on. This name is used to configure the database as follows:
      • The GWEN_CLASSPATH environment variable must be set to include a path to the JDBC driver JAR
      • A gwen.db.<dbName>.driver setting must be set to the name of the JDBC driver implementation class
      • A gwen.db.<dbName>.url setting must be set to the JDBC URL of the database
    • <selectStmt> = the SQL select query statement (can be a DocString)
  • Example using mysql:
    • Set GWEN_CLASSPATH variable in the environment to include the JDBC driver JAR
      • Unix: export GWEN_CLASSPATH=/path-to-driver/mysql-connector-java-5.1.40-bin.jar
      • Windows: set GWEN_CLASSPATH c:/path-to-driver/mysql-connector-java-5.1.40-bin.jar
    • Configure the database in your Gwen settings. In this example, <dbName>=feedback
      • gwen.db.feedback.driver = com.mysql.jdbc.Driver
      • gwen.db.feedback.url = jdbc:mysql://localhost/feedback?user=myUser&password=myPassword&serverTimezone=UTC&useSSL=false
    • Bind a database field and use it in your feature
      • Given the email is defined in the feedback database by sql "select email from comments"
      • Then the email should be "[email protected]"

Since v2.11.0

<element> can be located by
      | <locator 1>  | <expression 1> |
      | <locator 2>  | <expression 2> |
      | ..           | ..             |
      | <locator N>  | <expression N> |
  • Creates multiple locator bindings for a web element. Each binding in the specified table will be tried in sequence until one of them is successful. Timeout = gwen.locator.wait.seconds for each binding.
    • <element> = name of web element
    • <locator #> = one of: id, name, tag name, css selector, xpath, class name, link text, partial link text, or javascript
    • <expression #> = the lookup expression
  • Example using three bindings: 
        Given the search field can be located by
          | id         | search        |
          | class name | .search-field |
          | name       | q             |

Since v2.12.0

I capture <attribute> by javascript "<expression>"
  • Eagerly executes the given JavaScript expression and binds its result to <attribute>.
    • <attribute> = the name of the attribute to bind the result to
    • <expression> = the JavaScript expression or anonymous function that returns a value (can be a DocString).
      • For an expression: no return prefix is required
      • For an anonymous function: the syntax is (function(){ body })() where body must return a value
I capture <attribute> <of|on|in> <element> by javascript "<expression>"
  • Eagerly executes the given JavaScript expression on an element and binds its result to <attribute>.
    • <attribute> = the name of the attribute to bind the result to
    • <element> the web element available to the javascript expression as a variable named 'element'
      • Example usage in expression: element.value
    • <expression> = the JavaScript expression or anonymous function that returns a value (can be a DocString).
      • For an expression: no return prefix is required
      • For an anonymous function: the syntax is (function(){ body })() where body must return a value
<step> if <condition>
  • Conditionally calls a step only if a given condition is true.
    • <step> = the step to conditionally call
    • <condition> = the name of a javascript binding that returns true or false (a JavaScript predicate)
I update the <dbName> database by sql "<updateStmt>"

  • <dbName> = the name of database to execute the query on. This name is used to configure the database as follows:

    • The GWEN_CLASSPATH environment variable must be set to include a path to the JDBC driver JAR
    • A gwen.db.<dbName>.driver setting must be set to the name of the JDBC driver implementation class
    • A gwen.db.<dbName>.url setting must be set to the JDBC URL of the database

  • <updateStmt> = the SQL insert, update, or delete statement (can be a DocString)

  • Example using mysql:

    • Set GWEN_CLASSPATH variable in the environment to include the JDBC driver JAR
      • Unix: export GWEN_CLASSPATH=/path-to-driver/mysql-connector-java-5.1.40-bin.jar
      • Windows: set GWEN_CLASSPATH c:/path-to-driver/mysql-connector-java-5.1.40-bin.jar
    • Configure the database in your Gwen settings. In this example, <dbName>=feedback
      • gwen.db.feedback.driver = com.mysql.jdbc.Driver
      • gwen.db.feedback.url = jdbc:mysql://localhost/feedback?user=myUser&password=myPassword&serverTimezone=UTC&useSSL=false
    • Execute an update statement
      • Example using DocString syntax: 
         When I update the feedback database by sql
     """
     update comments set email='[email protected]' where email='[email protected]'
     """
      • Or standard one line syntax 
        When I update the feedback database by sql "update comments set email='[email protected]' where email='[email protected]'"
      • Check the number of rows affected:
        • Then feedback rows affected should be "1"

Since v2.13.0

<step> for each <entry> in <source> delimited by "<delimiter>"
  • Repeats a given step for each value in a delimited list of values. Nothing is performed if no elements are found.
    • <step> = the step to repeat for each delimited value
    • <entry> = the name that each entry will be bound to (entry is accessible in <step> by this name)
    • <source> = the name of the attribute containing the list of delimited values
    • <delimiter> = the delimiter used to separate the values in <source>
  • Notes:
    • The current entry number (starting at 1) is available as an implicit attribute named <entry> number and can be accessed by reference or interpolation.

Since 2.16.0

I switch to the default content
  • Switches from an iframe to the top (default content) window

Since 2.17.0

I drag and drop <sourceElement> to <targetElement>
  • Drags and drops a source element onto a target element
    • <sourceElement> = the name of the source element (locator binding)
    • <targetElement> = the name of the target element (locator binding)
  • Example: 
    Given element A can be located by id "elem-a"
  And element B can be located by id "elem-b"
 Then I drag and drop element A to element B

Since 2.18.0

I append "<value>" to <element>
  • Appends a value to the existing contents of a field (does not send Enter key afterwards).
    • <value> = the value to append
    • <element> = the web element to append the value to
I append <attribute> to <element>
  • Appends the value bound to an attribute to the existing contents of a field (does not send Enter key afterwards).
    • <attribute> = the name of the attribute containing the value to append
    • <element> = the web element to append the value into

Since 2.19.0

I insert a new line in <element>
  • Inserts a new line into the given text element
    • <element> = the text element to insert the new line into
<element> can be located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" with no <wait|timeout>
  • Creates a web element locator binding with no wait or timeout (location attempt will immediately return).
    • <element> = name of web element
    • <expression> = the lookup expression (can be a DocString)
  • Notes:
    • wait interchangeable with no timeout since v2.28.0
<element> can be located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" with <timeoutPeriod> second <wait|timeout>
  • Creates a web element locator binding with specified timeout (location attempt will return when element is found or once timeout period has lapsed).
    • <element> = name of web element
    • <expression> = the lookup expression (can be a DocString)
    • <timeoutPeriod> = the number of seconds to wait for element to be found before timing out
  • Notes:
    • wait interchangeable with timeout since v2.28.0
<element> can be located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" in <container> with no <wait|timeout>
  • Creates a web element locator binding inside another web element locator binding ~ locator chaining with no wait or timeout (location attempt will immediately return).
    • <element> = name of web element
    • <expression> = the lookup expression
    • <container> = the container element (a frame, div, or other container element)
  • Notes:
    • If using javascript locator, you can reference the container element as containerElem in `
    • wait interchangeable with timeout since v2.28.0
<element> can be located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" in <container> with <timeoutPeriod> second <wait|timeout>
  • Creates a web element locator binding inside another web element locator binding ~ locator chaining with specified wait or timeout (location attempt will return when element is found or once timeout period has lapsed).
    • <element> = name of web element
    • <expression> = the lookup expression
    • <container> = the container element (a frame, div, or other container element)
    • <timeoutPeriod> = the number of seconds to wait for element to be found before timing out
  • Notes:
    • If using javascript locator, you can reference the container element as containerElem in `
    • wait interchangeable with timeout since v2.28.0
<step> for each <element> located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" with no <wait|timeout>
  • Repeats a given step for each web element in an iteration of elements with no wait or timeout (location attempt will immediately return). Nothing is performed if no elements are found.
    • <step> = the step to repeat for each element
    • <element> = the name given to the current element in the iteration
    • <expression> = the lookup expression for the element iteration (can be a DocString)
  • Notes:
    • The current element number (starting at 1) is available as an implicit attribute named <element> number and can be accessed by reference or interpolation.
    • wait interchangeable with timeout since v2.28.0
<step> for each <element> located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" with <timeoutPeriod> second <wait|timeout>
  • Repeats a given step for each web element in an iteration of elements with specified timeout (location attempt will return when element is found or once timeout period has lapsed). Nothing is performed if no elements are found.
    • <step> = the step to repeat for each element
    • <element> = the name given to the current element in the iteration
    • <expression> = the lookup expression for the element iteration (can be a DocString)
    • <timeoutPeriod> = the number of seconds to wait for element to be found before timing out
  • Notes:
    • The current element number (starting at 1) is available as an implicit attribute named <element> number and can be accessed by reference or interpolation.
    • wait interchangeable with timeout since v2.28.0
<step> for each <element> located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" in <container> with no <wait|timeout>
  • Repeats a given step for each web element in an iteration of elements in a container. Nothing is performed if no elements are found with no wait (location attempt will immediately return).
    • <step> = the step to repeat for each element
    • <element> = the name given to the current element in the iteration
    • <expression> = the lookup expression for the element iteration
    • <container> = the container element (a frame, div, or other container element)
  • Notes:
    • The current element number (starting at 1) is available as an implicit attribute named <element> number and can be accessed by reference or interpolation.
    • wait interchangeable with timeout since v2.28.0
<step> for each <element> located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" in <container> with <timeoutPeriod> second <wait|timeout>
  • Repeats a given step for each web element in an iteration of elements in a container. Nothing is performed if no elements are found with specified timeout (location attempt will return when element is found or once timeout period has lapsed).
    • <step> = the step to repeat for each element
    • <element> = the name given to the current element in the iteration
    • <expression> = the lookup expression for the element iteration
    • <container> = the container element (a frame, div, or other container element)
    • <timeoutPeriod> = the number of seconds to wait for element to be found before timing out
  • Notes:
    • The current element number (starting at 1) is available as an implicit attribute named <element> number and can be accessed by reference or interpolation.
    • wait interchangeable with timeout since v2.28.0
<element> can be located with no <wait|timeout> by
      | <locator 1>  | <expression 1> |
      | <locator 2>  | <expression 2> |
      | ..           | ..             |
      | <locator N>  | <expression N> |
  • Creates multiple locator bindings for a web element. Each binding in the specified table will be tried in sequence until one of them is successful with no wait or timeout (location attempt will immediately return) for each binding.
    • <element> = name of web element
    • <locator #> = one of: id, name, tag name, css selector, xpath, class name, link text, partial link text, or javascript
    • <expression #> = the lookup expression
  • Notes:
    • wait interchangeable with no timeout since v2.28.0
  • Example using three bindings: 
        Given the search field can be located with no wait by
          | id         | search        |
          | class name | .search-field |
          | name       | q             |
<element> can be located with <timeoutPeriod> second timeout by
      | <locator 1>  | <expression 1> |
      | <locator 2>  | <expression 2> |
      | ..           | ..             |
      | <locator N>  | <expression N> |
  • Creates multiple locator bindings for a web element. Each binding in the specified table will be tried in sequence until one of them is successful with specified timeout (location attempt will return when element is found or once timeout period has lapsed) for each binding.
    • <element> = name of web element
    • <locator #> = one of: id, name, tag name, css selector, xpath, class name, link text, partial link text, or javascript
    • <expression #> = the lookup expression
    • <timeoutPeriod> = the number of seconds to wait for element to be found before timing out
  • Example using three bindings: 
        Given the search field can be located with 5 second timeout by
          | id         | search        |
          | class name | .search-field |
          | name       | q             |

Since 2.21.0

I reset my <name> <property|setting>
  • Resets (clears) a previously set thread-local Gwen runtime setting. Only Gwen settings that start with gwen. can be reset.
    • <name> = the name of the Gwen setting to reset

Since 2.24.0

the <alert|confirmation> popup message <should|should not> <be|contain|start with|end with|match regex|match xpath|match template|match template file> "<expression>"
  • Checks that the alert or confirmation popup message matches or does not match a given expression.
    • <expression> = the expression to match against (can be a DocString)
the <alert|confirmation> popup message <should|should not> <be|contain|start with|end with|match regex|match xpath> <attribute>
  • Checks that the alert or confirmation popup message matches or does not match a bound attribute value
    • <attribute> = the attribute to match against
I capture the <alert|confirmation> popup message as <attribute>
  • Captures the alert or confirmation popup message and binds it to a named attribute.
    • <attribute> = the name of the attribute to bind the popup message to
I capture the <alert|confirmation> popup message
  • Captures the alert or confirmation popup message and binds it to an attribute named the <alert|confirmation> popup message.

Since 2.25.0

I wait until <element> <is|is not> <displayed|hidden|checked|ticked|unchecked|unticked|enabled|disabled>
  • Waits for an element to transition to a given state
    • <element> = the web element to wait on

Since 2.28.0

<element> can be located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" at index <index>
  • Creates an indexed web element locator binding. Timeout = gwen.locator.wait.seconds.
    • <element> = name of web element
    • <expression> = the lookup expression (can be a DocString)
    • <index> = the index of the element to locate in array returned by <expression>
<element> can be located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" at index <index> in <container>
  • Creates an indexed web element locator binding inside another web element locator binding ~ locator chaining. Timeout = gwen.locator.wait.seconds.
    • <element> = name of web element
    • <expression> = the lookup expression
    • <index> = the index of the element to locate in array returned by <expression>
    • <container> = the container element (a frame, div, or other container element)
  • Notes:
    • If using javascript locator, you can reference the container element as containerElem in <expression>
<element> can be located at index <index> by
      | <locator 1>  | <expression 1> |
      | <locator 2>  | <expression 2> |
      | ..           | ..             |
      | <locator N>  | <expression N> |
  • Creates multiple indexed locator bindings for a web element. Each binding in the specified table will be tried in sequence until one of them is successful. Timeout = gwen.locator.wait.seconds for each binding.
    • <element> = name of web element
    • <locator #> = one of: id, name, tag name, css selector, xpath, class name, link text, partial link text, or javascript
    • <expression #> = the lookup expression
    • <index> = the index of the element to locate in array returned by <expression #>
  • Example using three bindings: 
        Given the search field can be located at index 0 by
          | id         | search        |
          | class name | .search-field |
          | name       | q             |
    <element> can be located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" at index <index> with no <wait|timeout>
    • Creates an indexed web element locator binding with no wait or timeout (location attempt will immediately return).
      • <element> = name of web element
      • <expression> = the lookup expression (can be a DocString)
      • <index> = the index of the element to locate in array returned by <expression>
    <element> can be located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" at index <index> with <timeoutPeriod> second <wait|timeout>
    • Creates an indexed web element locator binding with specified timeout (location attempt will return when element is found or once timeout period has lapsed).
      • <element> = name of web element
      • <expression> = the lookup expression (can be a DocString)
      • <index> = the index of the element to locate in array returned by <expression>
      • <timeoutPeriod> = the number of seconds to wait for element to be found before timing out
    <element> can be located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" at index <index> in <container> with no <wait|timeout>
    • Creates an indexed web element locator binding inside another web element locator binding ~ locator chaining with no wait or timeout (location attempt will immediately return).
      • <element> = name of web element
      • <expression> = the lookup expression
      • <index> = the index of the element to locate in array returned by <expression>
      • <container> = the container element (a frame, div, or other container element)
    • Notes:
      • If using javascript locator, you can reference the container element as containerElem in `
    <element> can be located by <id|name|tag name|css selector|xpath|class name|link text|partial link text|javascript> "<expression>" at index <index> in <container> with <timeoutPeriod> second <wait|timeout>
    • Creates an indexed web element locator binding inside another web element locator binding ~ locator chaining with specified timeout (location attempt will return when element is found or once timeout period has lapsed).
      • <element> = name of web element
      • <expression> = the lookup expression
      • <index> = the index of the element to locate in array returned by <expression>
      • <container> = the container element (a frame, div, or other container element)
      • <timeoutPeriod> = the number of seconds to wait for element to be found before timing out
    • Notes:
      • If using javascript locator, you can reference the container element as containerElem in `
    <element> can be located at index <index> with no <wait|timeout> by
          | <locator 1>  | <expression 1> |
      | <locator 2>  | <expression 2> |
      | ..           | ..             |
      | <locator N>  | <expression N> |
    • Creates multiple indexed locator bindings for a web element. Each binding in the specified table will be tried in sequence until one of them is successful with no wait or timeout (location attempt will immediately return) for each binding.
      • <element> = name of web element
      • <locator #> = one of: id, name, tag name, css selector, xpath, class name, link text, partial link text, or javascript
      • <expression #> = the lookup expression
      • <index> = the index of the element to locate in array returned by <expression #>
    • Example using three bindings: 
          Given the search field can be located at index 0 with no wait by
          | id         | search        |
          | class name | .search-field |
          | name       | q             |
    <element> can be located at index <index> with <timeoutPeriod> second <wait|timeout> by
          | <locator 1>  | <expression 1> |
      | <locator 2>  | <expression 2> |
      | ..           | ..             |
      | <locator N>  | <expression N> |
    • Creates multiple indexed locator bindings for a web element. Each binding in the specified table will be tried in sequence until one of them is successful with specified timeout (location attempt will return when element is found or once timeout period has lapsed) for each binding.
      • <element> = name of web element
      • <locator #> = one of: id, name, tag name, css selector, xpath, class name, link text, partial link text, or javascript
      • <expression #> = the lookup expression
      • <index> = the index of the element to locate in array returned by <expression #>
      • <timeoutPeriod> = the number of seconds to wait for element to be found before timing out
    • Example using three bindings: 
          Given the search field can be located at index 0 with 5 second timeout by
          | id         | search        |
          | class name | .search-field |
          | name       | q             |

Since 2.32.0

I start visual test as "<name>"
  • Starts a new visual test session with the given name and current viewport size.
    • <name> = the visual test name
I start visual test as "<name>" in <width> x <height> viewport
  • Starts a new visual test session with the given name and viewport size.
    • <name> = the visual test name
    • <width> = the viewport width to set
    • <height> = the viewport height to set
I check <viewport|full page> visual as "<name>"
  • Saves a visual test checkpoint image of the current viewport or full page with the given name and default match level of STRICT.
    • <name> = the visual checkpoint name
I check <viewport|full page> visual as "<name>" using <LAYOUT|LAYOUT2|CONTENT|STRICT|EXACT|NONE> match
  • Saves a visual test checkpoint image of the current viewport or full page with the given name and match level
    • <name> = the visual checkpoint name
the visual test should pass
  • Closes the visual test session and captures the results of all checkpoint images. If the test fails an error is reported. In either case a link to the dashboard is logged to the console and displayed in generated reports next to this step.

Since v3.0.0

I put the window in full screen mode
  • Puts the current browser window in full screen view mode.

Home

Clone this wiki locally