Skip to main content

DSL Reference

All Gherkin steps that match the DSL expressions described here are readily executable by Gwen. The DSL matched is the operation that will be performed at execution time.

tip

Use DSL steps in your meta to compose StepDefs. Although it's possible to use them directly in feature specs too, your features should not be DSL-aware. That's what meta is for!

Variables#

Given#

<name> is "<value>"

Binds the given value to a name in the global scope.

Where

  • <name> is the name the bind the value to
  • <value> is the value to bind (can be in DocString position)

Example

  Given my name is "Gwen"
<name> is defined by <javascript|js> "<expression>"

Associates a name with the return value of a JavaScript expression or anonymous function. The value is resolved every time the name is referenced.

Where

  • <name> is the name to associate
  • <javascript|js> is javascript (or js since v2.46.0)
  • <expression> is the javascript expression or anonymous function that will return the value (can be in DocString position)
    • For an expression: no return prefix is required
    • For an anonymous function: the syntax is (function(){ body })() where body must return a value

Example

  Given iso date is defined by js "new Date().toISOString().substring(0, 10)"   Then iso date should match regex "^\d{4}-([0]\d|1[0-2])-([0-2]\d|3[01])$"
<name> is defined in <textRef> by regex "<expression>"

Captures text from a referenced text value using the given regex expression and associates it with the given name. The value is resolved every time the name is referenced.

Where

  • <name> is the name of the name to associate the captured value to
  • <textRef> is the name of the binding containing the source text
    • Can be the name of any binding that contains or resolves to a text value, including a web element in which case the text in the element will be dynamically retrieved and used.
  • <expression> is the regex selector expression

Example

  Given the date is "2021-09-22"    And the year is defined in the date by regex "(\d{4})"   Then the year should be "2021"
<name> is defined by the <nodeType> in <xmlRef> by xpath "<expression>"

Captures content from a referenced XML value using the given XPath expression and associates it with the given name. The value is resolved every time the name is referenced.

Where

  • <name> is the name of the name to associate the captured value to
  • <nodeType> is one of:
    • text to capture the text node
    • node to capture a single node
    • nodeset to capture multiple nodes
  • <xmlRef> is the name of the binding containing the XML source
    • Can be the name of any binding that contains or resolves to XML text, including a web element in which case the text in the element will be dynamically retrieved and used.
  • <expression> is the XPath selector expression

Example

  Given the xml is "<result><status>passed</status></result>"    And status is defined by the text in the xml by xpath "//result/status"   Then the status should be "passed"
<name> is defined in <jsonRef> by json path "<expression>"

Captures content from a referenced JSON value using the given JSON path expression and associates it with the given name. The value is resolved every time the name is referenced.

Where

  • <name> is the name of the name to associate the captured value to
  • <nodeType> is one of:
    • text to capture the text node
    • node to capture a single node
    • nodeset to capture multiple nodes
  • <sourceRef> is the name of the binding containing the XML source
    • Can be the name of any binding that contains or resolves to XML text, including a web element in which case the text in the element will be dynamically retrieved and used.
  • <expression> is the XPath selector expression

Example

  Given the json is "{ "status": "passed" }"    And the status is defined in the json by json path "$.status"   Then the status should be "passed"
<name> is defined by system process "<expression>"

Associates a name with the return value of a local system process. The value is resolved every time the name is referenced.

Where

  • <name> is the name to associated the returned value to
  • <expression> is the system process that will return the value to assign (can be in DocString position)

Example

  Given my hostname is defined by system process "hostname"   Then my hostname should not be ""
<name> is defined by system process "<expression>" delimited by "<delimiters>"

Associates a name with the return value of a delimited local system process. The value is resolved every time the name is referenced.

Where

  • <name> is the name to associated the returned value to
  • <expression> is the system process that will return the value to assign (can be in DocString position)
    • Delmiters are required for special cases such as when unbalanced quoted strings are passed as arguments (see example).
  • <delmiters> is a regex pattern defining the delimiter(s) used in <expression>

Example

  Given my message is defined by system process "echo,"quoted text " and orphan quote"" delimited by ","   Then my message should be ""quoted text " and orphan quote""
<name> is defined by file "<filepath>"

Associates a name with the contents of a file. The value is resolved every time the name is referenced.

Where

  • <name> is the name to associated the file contents
  • <filepath> the path to the file (can be in DocString position)

Example

  Given the content is defined by file "path/to/file.txt"

When#

I capture <textRef> as <name>

Captures the referenced text and binds it to the given name in the global scope.

Where

  • <textRef> is the name of the binding containing the source text
    • Can be the name of any binding that contains or resolves to a text value, including a web element in which case the text in the element will be dynamically retrieved and used.
  • <name> is the name to bind the captured value to

Example

  Given the username is "Gwen"   When I capture the username as my username   Then my username should be the username
I capture <name> by <javascript|js> "<expression>"

Captures the return value of a JavaScript expression or anonymous function and binds it to the given name in the global scope.

Where

  • <name> is the name to bind the returned value to
  • <javascript|js> is javascript (or js since v2.46.0)
  • <expression> is the javascript expression or anonymous function that will return the value (can be in DocString position)
    • For an expression: no return prefix is required
    • For an anonymous function: the syntax is (function(){ body })() where body must return a value

Example

   When I capture iso date by js "new Date().toISOString().substring(0, 10)"   Then iso date should match regex "^\d{4}-([0]\d|1[0-2])-([0-2]\d|3[01])$"
I capture the text in <textRef> by regex "<expression>" as <name>

Captures the referenced text using the given regex expression and binds it to the given name in the global scope.

Where

  • <textRef> is the name of the binding containing the source text
    • Can be the name of any binding that contains or resolves to a text value, including a web element in which case the text in the element will be dynamically retrieved and used.
  • <expression> is the regex selector expression
  • <name> is the name to bind the captured value to

Example

  Given the date is "2021-09-22"   When I capture the text in the date by regex "(\d{4})" as the year   Then the year should be "2021"
I capture the <nodeType> in <xmlRef> by xpath "<expression>" as <name>

Captures XML content from a referenced XML string using the given XPath expression and binds it to the given name in the global scope.

Where

  • <nodeType> is one of:
    • text to capture the text node
    • node to capture a single node
    • nodeset to capture multiple nodes
  • <xmlRef> is the name of the binding containing the XML text
    • Can be the name of any binding that contains or resolves to an XML text value, including a web element in which case the text in the element will be dynamically retrieved and used.
  • <expression> is the XPath selector expression
  • <name> is the name to bind the captured value to

Example

  Given the xml is "<result><status>passed</status></result>"   When I capture the text in the xml by xpath "//result/status" as the status   Then the status should be "passed"
I capture the content in <jsonRef> by json path "<expression>" as <name>

Captures JSON content from a referenced JSON string using the given JSON Path expression and binds it to the given name in the global scope.

Where

  • <jsonRef> is the name of the binding containing the source JSON source
    • Can be the name of any binding that contains or resolves to a JSON text value, including a web element in which case the text in the element will be dynamically retrieved and used.
  • <expression> is the JSON selector expression
  • <name> is the name to bind the captured value to

Example

  Given the json is "{ "status": "passed" }"   When I capture the content in the json by json path "$.status" as the status   Then the status should be "passed"
I base64 decode <textRef>

Base64 decodes the referenced text value and binds the result to the same name in the global scope.

Where

  • <textRef> is the name of the binding containing the text to decode
    • Can be the name of any binding that contains or resolves to a text value, including a web element in which case the text in the element will be dynamically retrieved and used.

Example

  Given the data is "c29tZSBiaW5hcnkgZGF0YQ=="   When I base64 decode the data   Then the data should be "some binary data"
I base64 decode <textRef> as <name>

Base64 decodes the referenced text value and binds the result to the give name in the global scope.

Where

  • <textRef> is the name of the binding containing the text to decode
    • Can be the name of any binding that contains or resolves to a text value, including a web element in which case the text in the element will be dynamically retrieved and used.
  • <name> is the name to bind the decoded value to

Example

  Given the encoded data is "c29tZSBiaW5hcnkgZGF0YQ=="   When I base64 decode the encoded data as the decoded data   Then the decoded data should be "some binary data"

Then#

<textRef> should[ not] <match> "<expression>"

Checks whether or not the referenced text value matches a given expression. Reports an assertion error if the match fails.

Where

  • <textRef> is the name of the binding containing the text to check
    • Can be the name of any binding that contains or resolves to a text value, including a web element in which case the text in the element will be dynamically retrieved and used.
  • not negates the match if included
  • <match> is the type of match to perform, one of:
    • be for exact match
    • contain for partial match
    • start with for partial leading match
    • end with for partial trailing match
    • match regex for regex match
    • match xpath for XML match
    • match json path for JSON match, since v1.4.0
    • match template for template match, since v2.16.0
    • match template file for template file match, since v2.16.0
  • <expression> is the expression to match (can be in DocString position)

Example

  Given the todo field can be located by class "new-todo"    And my todo list can be located by css ".todo-list"   When I navigate to "https://todomvc.com/examples/react"    And I enter "Get the milk" in the todo field    And I capture my todo list as current items   Then current items should contain "Get the milk"
<textRef> should[ not] <match> <expressionRef>

Checks whether or not the value of a variable or setting matches a referenced expression. Reports an assertion error if the match fails.

Where

  • <variable> is the name of the variable or setting to check
  • not negates the match if included
  • <match> is the type of match to perform, one of:
    • be for exact match
    • contain for partial match
    • start with for partial leading match
    • end with for partial trailing match
    • match regex for regex match
    • match xpath for XML match
    • match json path for JSON match, since v1.4.0
    • match template for template match, since v2.16.0
    • match template file for template file match, since v2.16.0
  • <expressionRef> is the name of the binding containing the expression to match
    • Can be the name of any binding that contains or resolves to an expression value, including a web element in which case the text in the element will be dynamically retrieved and used.

Example

  Given the todo field can be located by class "new-todo"    And my todo list can be located by css ".todo-list"    And my item is "Feed the cat"   When I navigate to "https://todomvc.com/examples/react"    And I enter my item in the todo field    And I capture my todo list as current items   Then current items should contain my item
<xmlRef> at xpath "<path>" should[ not>] <match> "<expression>"

Extracts text from the referenced XML value using the given XPath and checks that it matches a given expression. Reports an assertion error if the match fails.

Where

  • <xmlRef> is the name of the binding containing the XML source text
    • Can be the name of any binding that contains or resolves to an XML text value, including a web element in which case the text in the element will be dynamically retrieved and used.
  • path is the XPath selector expression
  • not negates the match if included
  • <match> is the type of match to perform, one of:
    • be for exact match
    • contain for partial match
    • start with for partial leading match
    • end with for partial trailing match
    • match regex for regex match
    • match xpath for XML match
    • match json path for JSON match, since v1.4.0
    • match template for template match, since v2.16.0
    • match template file for template file match, since v2.16.0
  • <expression> is the expression to match

Example

  Given the xml is "<result><status>passed</status></result>"   Then the xml at xpath "//result/status" should be "passed"
<jsonRef> at json path "<path>" should[ not>] <match> "<expression>"

Extracts text from the referenced JSON value using the given JSON path and checks that it matches a given expression. Reports an assertion error if the match fails.

Where

  • <jsonRef> is the name of the binding containing the JSON source text
    • Can be the name of any binding that contains or resolves to a JSON text value, including a web element in which case the text in the element will be dynamically retrieved and used.
  • path is the JSON path selector expression
  • not negates the match if included
  • <match> is the type of match to perform, one of:
    • be for exact match
    • contain for partial match
    • start with for partial leading match
    • end with for partial trailing match
    • match regex for regex match
    • match xpath for XML match
    • match json path for JSON match, since v1.4.0
    • match template for template match, since v2.16.0
    • match template file for template file match, since v2.16.0
  • <expression> is the expression to match

Example

    Given the json is "{ "status": "passed" }"     Then the json at json path "$.status" should be "passed"
<name> should be absent

Checks that a named binding is absent from the current scope.

Where

  • <name> is the name of the binding to check

Example

  Then this should be absent

Web pages#

Given#

the <page> url is "<url>"

Puts the given page into scope and binds the given URL to it.

Where

  • <page> is the name of the page
  • <url> is the page URL (can be in DocString position)

Example

  Given the todo page url is "https://todomvc.com/examples/react"    And the todo field can be located by class "new-todo"
I am on the <page>

Puts the given page into scope and makes its bindings avaialble.

Where

  • <page> is a page name

Example

  Given I navigate to "https://todomvc.com/examples/react"    And I am on the todo page    And the todo field can be located by class "new-todo"   When I enter "Walk the dog" in the todo field

When#

I navigate to the <page>

Navigates the browser to the URL bound to the given page and puts the page into scope. Starts a new browser window if one is not open.

Where

  • <page> is the name of the page to navigate to

Example

  Given the todo page url is "https://todomvc.com/examples/react"   When I navigate to the todo page
I navigate to "<url>"

Navigates the browser to the given URL. Starts a new browser window if one is not open.

Where

  • <url> is the URL to navigate to (can be in DocString position)

Example

  When I navigate to "https://todomvc.com/examples/react"
I capture the current URL

Captures the current browser URL and binds it as the current URL in the global scope.

Example

  When I capture the current URL   And I navigate to "${the current URL}?q=gwen"
I capture the current URL as <name>

Captures the current browser URL and binds it to the given name in the global scope.

Where

  • <name> is the name to bind the captured URL to

Example

  When I capture the current URL as the base URL   And I navigate to "${the base URL}?q=gwen"  Then the current URL should start with the base URL
I capture the text in the current URL by regex "<expression>" as <name>

Extracts a substring from the current browser URL using the given regex and binds it to the given name in the global scope.

Where

  • <expression> is the regex expression
  • <name> is the name to bind the captured substring to

Example

  When I capture the text in the current URL by regex "q=([^&]*)" as q  Then q should be "gwen"
I refresh the current page

Refreshes the current page in the browser.

Example

  When I refresh the current page

Then#

the current URL should[ not] <match> "<expression>"

Checks whether or not the current browser URL matches a given expression. Reports an assertion error if the match fails.

Where

  • not negates the match if included
  • <match> is the type of match to perform, one of:
    • be for exact match
    • contain for partial match
    • start with for partial leading match
    • end with for partial trailing match
    • match regex for regex match
    • match xpath for XML match
    • match json path for JSON match, since v1.4.0
    • match template for template match, since v2.16.0
    • match template file for template file match, since v2.16.0
  • <expression> is the expression to match (can be in DocString position)

Example

  When I navigate to "https://todomvc.com/examples/react"  Then the current URL should contain "todomvc.com"   And the current URL should not contain "other.com"
the current URL should[ not] <match> <expressionRef>

Checks whether or not the current URL in the browser matches a referenced expression. Reports an assertion error if the match fails.

Where

  • not negates the match if included
  • <match> is the type of match to perform, one of:
    • be for exact match
    • contain for partial match
    • start with for partial leading match
    • end with for partial trailing match
    • match regex for regex match
    • match xpath for XML match
    • match json path for JSON match, since v1.4.0
    • match template for template match, since v2.16.0
    • match template file for template file match, since v2.16.0
  • <expressionRef> is the name of the binding containing the expression to match
    • Can be the name of any binding that contains or resolves to an expression value, including a web element in which case the text in the element will be dynamically retrieved and used.

Example

  Given my domain is "todomvc.com"    And some other domain is "someother.com"   When I navigate to "https://todomvc.com/examples/react"   Then the current URL should contain my domain    And the current URL should not contain some other domain
the page title should[ not] <match> "<expression>"

Checks whether or not the title of the current page in the browser matches a given expression. Reports an assertion error if the match fails.

Where

  • not negates the match if included
  • <match> is the type of match to perform, one of:
    • be for exact match
    • contain for partial match
    • start with for partial leading match
    • end with for partial trailing match
    • match regex for regex match
    • match xpath for XML match
    • match json path for JSON path match, since v1.4.0
    • match template for template match, since v2.16.0
    • match template file for template file match, since v2.16.0
  • <expression> is the expression to match (can be in DocString position)

Example

  When I navigate to "https://todomvc.com/examples/react"  Then the page title should contain "TodoMVC"
the page title should[ not] <match> <expressionRef>

Checks whether or not the title of the current page in the browser matches a referenced expression. Reports an assertion error if the match fails.

Where

  • not negates the match if included
  • <match> is the type of match to perform, one of:
    • be for exact match
    • contain for partial match
    • start with for partial leading match
    • end with for partial trailing match
    • match regex for regex match
    • match xpath for XML match
    • match json path for JSON path match, since v1.4.0
    • match template for template match, since v2.16.0
    • match template file for template file match, since v2.16.0
  • <expressionRef> is the name of the binding containing the expression to match
    • Can be the name of any binding that contains or resolves to an expression value, including a web element in which case the text in the element will be dynamically retrieved and used.

Example

  Given the app name is "TodoMVC"   When I navigate to "https://todomvc.com/examples/react"   Then the page title should contain the app name

Web elements#

Given#

<element> can be located by <selector> "<expression>"

Binds a selector for a web element to the current scope with a default lookup timeout.

Where

  • <element> is the web element name
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression

Example

  Given the todo field can be located by class "new-todo"   When I enter "Walk the dog" in the todo field
<element> can be located by <selector> "<expression>" with no <wait|timeout>

Binds a selector for a web element to the current scope with no lookup timeout.

Where

  • <element> is the web element name
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression
  • <wait|timeout> is either wait or timeout

Example

  Given the todo field can be located by css ".new-todo" with no lookup timeout   When I enter "Walk the dog" in the todo field
<element> can be located by <selector> "<expression>" with <timeoutSecs> second <wait|timeout>

Binds a selector for a web element to the current scope with a given lookup timeout.

Where

  • <element> is the web element name
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression
  • <timeoutSecs> is the timeout period in seconds
  • <wait|timeout> is either wait or timeout

Example

  Given the todo field can be located by css ".new-todo" with 5 second timeout   When I enter "Walk the dog" in the todo field
<element> can be located by <selector> "<expression>" <relativeTo> <otherElement>

Binds a relative selector for a web element to the current scope with a default lookup timeout.

Where

  • <element> is the web element name
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression
  • <relativeTo> is the relationship to <otherElement>, one of:
    • in for a contained relationship
    • More relative options coming to Gwen 3
  • <otherElement> is the name of the web element that this one is relative to

Example

  Given the footer can be located by class "footer"    And the displayed count can be located by tag "strong" in the footer   Then the displayed count should be "3"
<element> can be located by <selector> "<expression>" <relativeTo> <otherElement> with no <wait|timeout>

Binds a relative selector for a web element to the current scope with no lookup timeout.

Where

  • <element> is the web element name
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression
  • <relativeTo> is the relationship to <otherElement>, one of:
    • in for a contained relationship
    • More relative options coming to Gwen 3
  • <otherElement> is the name of the web element that this one is relative to
  • <wait|timeout> is either wait or timeout

Example

  Given the footer can be located by class "footer"    And the displayed count can be located by tag "strong" in the footer with no wait   Then the displayed count should be "3"
<element> can be located by <selector> "<expression>" <relativeTo> <otherElement>  with <timeoutSecs> second <wait|timeout>

Binds a relative selector for a web element to the current scope with a given lookup timeout.

Where

  • <element> is the web element name
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression
  • <relativeTo> is the relationship to <otherElement>, one of:
    • in for a contained relationship
    • More relative options coming to Gwen 3
  • <otherElement> is the name of the web element that this one is relative to
  • <timeoutSecs> is the timeout period in seconds
  • <wait|timeout> is either wait or timeout

Example

   Given the footer can be located by class "footer"     And the displayed count can be located by tag "strong" in the footer with no wait    Then the displayed count should be "3"
<element> can be located by <selector> "<expression>" at index <index>

Binds an indexed selector for a web element to the current scope with a default lookup timeout.

Where

  • <element> is the web element name
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression
  • <index> is the index of the element to select in list returned by <expression>

Example

  Given the first item can be located by css ".todo-list label" at index 0   Then the first item should contain "Walk the dog"
<element> can be located by <selector> "<expression>" at index <index> with no <wait|timeout>

Binds an indexed selector for a web element to the current scope with no lookup timeout.

Where

  • <element> is the web element name
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression
  • <index> is the index of the element to select in list returned by <expression>
  • <wait|timeout> is either wait or timeout

Example

  Given the first item can be located by css ".todo-list label" at index 0 with no lookup timeout   Then the first item should contain "Walk the dog"
<element> can be located by <selector> "<expression>" at index <index> with <timeoutSecs> second <wait|timeout>

Binds an indexed selector for a web element to the current scope with a given lookup timeout.

Where

  • <element> is the web element name
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression
  • <index> is the index of the element to select in list returned by <expression>
  • <timeoutSecs> is the timeout period in seconds
  • <wait|timeout> is either wait or timeout

Example

  Given the first item can be located by css ".todo-list label" at index 0 with 5 second timeout   Then the first item should contain "Walk the dog"
<element> can be located by <selector> "<expression>" at index <index> <relativeTo> <otherElement>

Binds a relative selector for a web element to the current scope with a default lookup timeout.

Where

  • <element> is the web element name
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression
  • <index> is the index of the element to select in list returned by <expression>
  • <relativeTo> is the relationship to <otherElement>, one of:
    • in for a contained relationship
    • More relative options coming to Gwen 3
  • <otherElement> is the name of the web element that this one is relative to

Example

  Given the count info can be located by class "todo-count"    And the count unit can be located by tag "span" at index 1 in the count info   Then the count unit should contain "item"
<element> can be located by <selector> "<expression>" at index <index> <relativeTo> <otherElement> with no <wait|timeout>

Binds a relative indexed selector for a web element to the current scope with no lookup timeout.

Where

  • <element> is the web element name
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression
  • <index> is the index of the element to select in list returned by <expression>
  • <relativeTo> is the relationship to <otherElement>, one of:
    • in for a contained relationship
    • More relative options coming to Gwen 3
  • <otherElement> is the name of the web element that this one is relative to
  • <wait|timeout> is either wait or timeout

Example

  Given the count info can be located by class "todo-count"    And the count unit can be located by tag "span" at index 1 in the count info with no wait   Then the count unit should contain "item"
<element> can be located by <selector> "<expression>" at index <index> <relativeTo> <otherElement>  with <timeoutSecs> second <wait|timeout>

Binds a relative indexed selector for a web element to the current scope with a given lookup timeout.

Where

  • <element> is the web element name
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression
  • <index> is the index of the element to select in list returned by <expression>
  • <relativeTo> is the relationship to <otherElement>, one of:
    • in for a contained relationship
    • More relative options coming to Gwen 3
  • <otherElement> is the name of the web element that this one is relative to
  • <timeoutSecs> is the timeout period in seconds
  • <wait|timeout> is either wait or timeout

Example

   Given the count info can be located by class "todo-count"     And the count unit can be located by tag "span" at index 1 in the count info with 5 second wait    Then the count unit should contain "item"
<element> can be located by  | <selector 1> | <expression 1> |  | <selector 2> | <expression 2> |  |      ..      |       ..       |  | <selector n> | <expression n> |

Binds primary and fallback selectors for a web element to the current scope with a default lookup timeout. Lookups will be attempted in the order specified until one succeeds.

Where

  • <element> is the web element name
  • <selector n> is the nth selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression n> is the nth selector expression

Example

  Given the todo field can be located by        | name  | todo-field  |        | css   | .todo input |        | class | new-todo    |   When I type "Feed the cat" in the todo field
<element> can be located at index <index> by  | <selector 1> | <expression 1> |  | <selector 2> | <expression 2> |  |      ..      |       ..       |  | <selector n> | <expression n> |

Binds indexed primary and fallback selectors for a web element to the current scope with a default lookup timeout. Lookups will be attempted in the order specified until one succeeds.

Where

  • <element> is the web element name
  • <selector n> is the nth selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression n> is the nth selector expression
  • <index> is the index of the element to select in list returned by <expression n>

Example

  Given the second item can be located at index 1 by        | name  | todo-label       |        | class | todo-label       |        | css   | .todo-list label |   Then the second item should contain "Feed the cat"
<element> can be located at index <index> with no <wait|timeout> by  | <selector 1> | <expression 1> |  | <selector 2> | <expression 2> |  |      ..      |       ..       |  | <selector n> | <expression n> |

Binds indexed primary and fallback selectors for a web element to the current scope with no lookup timeout. Lookups will be attempted in the order specified until one succeeds.

Where

  • <element> is the web element name
  • <selector n> is the nth selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression n> is the nth selector expression
  • <index> is the index of the element to select in list returned by <expression n>
  • <wait|timeout> is either wait or timeout

Example

  Given the second item can be located at index 1 with no lookup timeout by        | name  | todo-label       |        | class | todo-label       |        | css   | .todo-list label |   Then the second item should contain "Feed the cat"
<element> can be located at index <index> with <timeoutSecs> second <wait|timeout> by  | <selector 1> | <expression 1> |  | <selector 2> | <expression 2> |  |      ..      |       ..       |  | <selector n> | <expression n> |

Binds indexed primary and fallback selectors for a web element to the current scope with a given lookup timeout. Lookups will be attempted in the order specified until one succeeds.

Where

  • <element> is the web element name
  • <selector n> is the nth selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression n> is the nth selector expression
  • <index> is the index of the element to select in list returned by <expression n>
  • <timeoutSecs> is the timeout period in seconds
  • <wait|timeout> is either wait or timeout

Example

  Given the second item can be located at index 1 with 5 second timeout by        | name  | todo-label       |        | class | todo-label       |        | css   | .todo-list label |   Then the second item should contain "Feed the cat"
<element> can be <actioned> by <javascript|js> "<javascript>"

Registers a javascript action on an element. When the action is performed, then the javascript will execute in place of the default behavior.

Where

  • <element> is the name of the element to register the action on
  • <actioned> is one of:
    • clicked to perform the action when the element is clicked
    • right clicked to perform the action when the element is right clicked, since v2.8.0
    • double clicked to perform the action when the element is double clicked, since v2.12.0
    • submitted to perform the action when the form element is submitted
    • checked (or ticked since v2.4.0) to perform the action when the checkbox element is ticked
    • unchecked (or unticked since v2.4.0) to perform the action when the checkbox element is unticked
    • selected to perform the action when a dropdown option is selected in the element
    • deselected to perform the action when a mutli-select dropdown option is deselected in the element, since v2.13.0
    • typed to perform the action when text is typed into the element
    • entered to perform the action when text is entered into the element
    • tabbed to perform the action when the tab key is pressed in the element, since v2.17.1
    • cleared to perform the action when the text is cleared in the element
    • moved to to perform the action when the focus is moved to the element
  • <javascript|js> is javascript (or js , since v2.46.0)
  • <javascript> is the javascript expression or anonymous function that will perform the desired action (can be in DocString position)
    • The reference to the element will be provided to the javascript through an implicit object named element.
    • For an expression: no return prefix is required
    • For an anonymous function: the syntax is (function(){ body })() where body must return a value

Example

  Given the submit button can be located by css ".submit"    And the submit button can be clicked by js "element.click()"   When I click the submit button

When#

I <click|right click|double click> <element>

Clicks a web element.

Where

  • <click|right click|double click> is one of:
    • click to click the element
    • right click to right click the element, since v2.8.0
    • double click to double click the element, since v2.12.0
  • <element> is the name of the element to click

Example

  Given the start button can be located by name "commit"   When I navigate to "https://challengers.flood.io/start"    And I click the start button
I <click|right click|double click> <element> of <context>

Clicks a context sensitive web element.

Where

  • <click|right click|double click> is one of:
    • click to click the element
    • right click to right click the element, since v2.8.0
    • double click to double click the element, since v2.12.0
  • <element> is the name of the element to click
  • <context> is the context element to focus into (in order to click <element>)

Example

  Given the menu item can be located by id "menu-item-id"    And the action button can be located by id "action-button-id"   When I click the action button of the menu item
I <modifierKeys> <click|right click|double click> <element>

Holds down the specified modifier keys and clicks an element.

Where

  • <modifierKeys> is a + separated list of modifier keys to hold down during the click
    • Modifier keys can be single keyboard characters or any supported key constants
    • Node: Keys behave differently on different platforms
  • <click|right click|double click> is one of:
    • click to click the element
    • right click to right click the element
    • double click to double click the element, since v2.12.0
  • <element> is the name of the element to click

Example

  Given the button can be located by tag "button"    And I COMMAND+SHIFT click the button
I <check|uncheck|tick|untick> <checkbox>

Ticks or unticks a checkbox element.

Where

  • <check|uncheck|tick|untick> is one of:
    • check (or tick since v2.4.0) to tick the checkbox element
    • uncheck (or untick since v2.4.0) to untick the checkbox element
  • <checkbox> is the name of the checkbox element

Example

  Given the email checkbox can be located by id "checkbox1"   When I navigate to "https://automationintesting.com/selenium/testpage"    And I tick the email checkbox
I submit <form>

Submits a web form.

Where

  • <form> is the name of the form to submit

Example

  Given the form can be located by name "contactform"   When I navigate to "https://automationintesting.com/selenium/testpage"    And I submit the form
I move to <element>

Moves to a web element and gives it the focus.

Where

  • <element> is the name of the element to move to

Example

  Given the surname field can be located by id "surname"   When I navigate to "https://automationintesting.com/selenium/testpage"    And I move to the surname field
I <enter|type> "<text>" in <element>

Enters or types text into a web element.

Where

  • <enter|type> is one of:
    • enter to send the text to the field followed by the enter key
    • type to send the text to the field only (without trailing enter key)
  • <text> is the text to send to the field
  • <element> is the name of the field to send the text to

Example

  Given the todo field can be located by class "new-todo"   When I navigate to "https://todomvc.com/examples/react"    And I enter "Walk the dog" in the todo field
I <enter|type> <textRef> in <element>

Enters or types a referenced text value into a web element.

Where

  • <enter|type> is one of:
    • enter to send the text to the field followed by the enter key
    • type to send the text to the field only (without trailing enter key)
  • <textRef> is the name of the binding containing the text to send to the field
    • Can be the name of any binding that contains or resolves to a text value, including a web element in which case the text in the element will be dynamically retrieved and used.
  • <element> is the name of the field to send the text to

Example

  Given the todo field can be located by class "new-todo"    And my item is "Walk the dog"   When I navigate to "https://todomvc.com/examples/react"    And I enter my item in the todo field
I append "<text>" to <element>

Appends the given text to the current text value of an element.

Where

  • <text> is the text to append
  • <element> is name of the element to append the text to

Example

  Given the search field can be located by name "q"   When I navigate to "https://google.com"    And I type "Gwen" in the search field    And I append " automation" to the search field
I append <textRef> to <element>

Appends the given referenced text to the current text value of an element.

Where

  • <textRef> is the name of the binding containing the text to append to the element
    • Can be the name of any binding that contains or resolves to a text value, including a web element in which case the text in the element will be dynamically retrieved and used.
  • <element> is name of the element to append the text to

Example

  Given the search field can be located by name "q"    And my additional search term is " automation"   When I navigate to "https://google.com"    And I type "Gwen" in the search field    And I append my additional search term to the search field
I press <enter|tab> in <element>

Send the enter or tab key to a web element.

Where

  • <enter|tab> is one of:
    • enter to send the enter key
    • tab to send the tab key
  • <element> is the name of the element to send the key to

Example

  Given the surname field can be located by id "surname"   When I navigate to "https://automationintesting.com/selenium/testpage"    And I press tab in the surname field
I send "<keys>" to <element>

Sends a sequence of keys to an element (for emulating keyboard shortcuts).

Where

  • <keys> is a , or + (since v2.53.0) separated list of keys to send.
    • Keys can be single keyboard characters or any supported key constants
    • Note: Keys behave differently on different platforms
  • <element> is the name of the element to send the keys to

Example

  Given the search field can be located by name "q"   When I navigate to "https://google.com"    And I type "Gwen automation" in the search field    And I send "COMMAND+A" to the search field    And I send "COMMAND+C" to the search field    And I clear the search field    And I send "COMMAND+V" to the search field    And I send "ARROW_DOWN" to the search field    And I press enter in the search field
I insert a new line in <textarea>

Inserts a new line into a textarea element.

Where

  • <textarea> is the name of the textarea element to insert the new line into

Example

  Given the more field can be located by tag "textarea"   When I navigate to "https://automationintesting.com/selenium/testpage"    And I type "Hi," in the more field    And I insert a new line in the more field    And I type "I like Gwen." in the more field    And I insert a new line in the more field    And I type "Bye!" in the more field   Then the more field should contain        """        Hi,        I like Gwen.        Bye!        """
I clear <element>

Clears a text element.

Where

  • <element> is the name of the element to clear

Example

  Given the surname field can be located by id "surname"   When I navigate to "https://automationintesting.com/selenium/testpage"    And I clear the surname field
I <select|deselect> the <position><st|nd|rd|th> option in <dropdown>

Selects an option in a dropdown by position.

Where

  • <select|deselect> is one of:
    • select to select the option
    • deselect to deselect the option, since v2.13.0
      • Note: Deselect will only work for multi-select dropdowns.
  • <position> is the position number of the option(1 for first position)
  • <st|nd|rd|th> is one of:
    • st if the position number ends in 1
    • nd if the position number ends in 2
    • rd if the position number ends in 3
    • th if the position number is greater than 3
  • <dropdown> is the name of the dropdown element

Example

  Given the age dropdown can be located by id "challenger_age"   When I navigate to "https://challengers.flood.io/step/2"    And I select the 2nd option in the age dropdown
I <select|deselect> "<option>" in <dropdown>

Selects an option in a dropdown by displayed text.

Where

  • <select|deselect> is one of:
    • select to select the option
    • deselect to deselect the option, since v2.13.0
      • Note: Deselect will only work for multi-select dropdowns.
  • <option> is the displayed option text
  • <dropdown> is the name of the dropdown element

Example

  Given the age dropdown can be located by id "challenger_age"   When I navigate to "https://challengers.flood.io/step/2"    And I select "18" in the age dropdown
I <select|deselect> <optionRef> in <dropdown>

Selects an option in a dropdown by a displayed text reference.

Where

  • <select|deselect> is one of:
    • select to select the option
    • deselect to deselect the option, since v2.13.0
      • Note: Deselect will only work for multi-select dropdowns.
  • <optionRef> is the name of the binding containing the displayed option text
    • Can be the name of any binding that contains or resolves to a text value, including a web element in which case the text in the element will be dynamically retrieved and used.
  • <dropdown> is the name of the dropdown element

Example

  Given the age dropdown can be located by id "challenger_age"    And my age is "24"   When I navigate to "https://challengers.flood.io/step/2"    And I select my age in the age dropdown
I <select|deselect> "<option>" in <dropdown> by value

Selects an option in a dropdown by hidden value.

Where

  • <select|deselect> is one of:
    • select to select the option
    • deselect to deselect the option, since v2.13.0
      • Note: Deselect will only work for multi-select dropdowns.
  • <option> is the hidden option value
  • <dropdown> is the name of the dropdown element

Example

  Given the age dropdown can be located by id "challenger_age"   When I navigate to "https://challengers.flood.io/step/2"    And I select "21" in the age dropdown by value
I <select|deselect> <optionRef> in <dropdown> by value

Selects an option in a dropdown by hidden value reference.

Where

  • <select|deselect> is one of:
    • select to select the option
    • deselect to deselect the option, since v2.13.0
      • Note: Deselect will only work for multi-select dropdowns.
  • <optionRef> is the name of the binding containing the hidden option value
    • Can be the name of any binding that contains or resolves to a text value, including a web element in which case the text in the element will be dynamically retrieved and used.
  • <dropdown> is the name of the dropdown element

Example

  Given the age dropdown can be located by id "challenger_age"    And the age is "24"   When I navigate to "https://challengers.flood.io/step/2"    And I deselect the age in the age dropdown
I scroll to the <top|bottom> of <element>

Scrolls to the top or bottom of the given element.

Where

  • <top|bottom> is one of:
    • top to scroll to the top of the element
    • bottom to scroll to the bottom of the element
  • <element> the name of the element to scroll to

Example

  Given the surname field can be located by id "surname"   When I navigate to "https://automationintesting.com/selenium/testpage"    And I scroll to the top of the surname field
I drag and drop <sourceElement> to <targetElement>

Drags and drops a source element onto a target element.

Where

  • <sourceElement> is the name of the source element to drag
  • <targetElement> is the name of the target element to drop the <sourceElement> into

Example

  Given the box can be located by xpath "//*[@id='credit2']/a"    And the cell can be located by xpath "//*[@id='bank']/li"   When I navigate to "http://demo.guru99.com/test/drag_drop.html"    And I capture the box as the box text    And I drag and drop the box to the cell   Then the cell should contain "${the box text}"
I capture <element>

Captures the text value of an element and binds it to the element name in the global scode.

Where

  • <element> is the name of the element to capture the text of

Example

  Given the heading can be located by tag "h1"   When I navigate to "https://todomvc.com/examples/react"    And I capture the heading
I capture <element> as <name>

Captures the text value of an element and binds it to the given name in the global scope.

Where

  • <element> is the name of the element to capture the text of
  • <name> is the name to bind the captured text to

Example

  Given the heading can be located by tag "h1"   When I navigate to "https://todomvc.com/examples/react"    And I capture the heading as my heading
I capture <dropdown> <text|value>

Captures the selected text or value of a dropdown element and binds it to the element name in the global scode.

Where

  • <dropdown> is the name of the dropdown element to capture the text or value of
  • <dropdown> is one of:
    • text to captured the displayed text of the selection
    • value to captured the option value of the selection

Example

  Given the age dropdown can be located by id "challenger_age"   When I navigate to "https://challengers.flood.io/step/2"    And I capture the age dropdown text
I capture <dropdown> <text|value> as <name>

Captures the selected text or value of a dropdown element and binds it to the given name in the global scope.

Where

  • <dropdown> is the name of the dropdown element to capture the text or value of
  • <dropdown> is one of:
    • text to captured the displayed text of the selection
    • value to captured the option value of the selection

Example

  Given the age dropdown can be located by id "challenger_age"   When I navigate to "https://challengers.flood.io/step/2"    And I capture the age dropdown text my age
I capture the text in <element> by regex "<expression>" as <name>

Captures text content from a web element using the given regex expression and binds it to the given name in the global scope.

Where

  • <element> is the name of the element to capture text from
  • <expression> is the regex selector expression
  • <name> is the name to bind the captured value to

Example

  # assuming a web element contains date: 2021-09-22  Given the date field can be located by class "date"   When I capture the text in the date field by regex "(\d{4})" as the year   Then the year should be "2021"
I capture the <nodeType> in <element> by xpath "<expression>" as <name>

Captures XML content from a web element using the given XPath expression and binds it to the given name in the global scope.

Where

  • <nodeType> is one of:
    • text to capture the text node
    • node to capture a single node
    • nodeset to capture multiple nodes
  • <element> is the name of the element containing the XML content
  • <expression> is the XPath selector expression
  • <name> is the name to bind the captured value to

Example

  # assuming a web element contains xml: <result><status>passed</status></result>  Given the xml web element can be located by id "xml"   When I capture the text in the xml web element by xpath "//result/status" as the status   Then the status should be "passed"
I capture the content in <element> by json path "<expression>" as <name>

Captures JSON content from a web element using the given JSON Path expression and binds it to the given name in the global scope.

Where

  • <element> is the name of the element containing the JSON content
  • <expression> is the JSON selector expression
  • <name> is the name to bind the captured value to

Example

  # assuming a web element contains json: { "status": "passed" }  Given the json web element can be located by id "json"   When I capture the content in the json web element by json path "$.status" as the status   Then the status should be "passed"
I capture <name> <of|on|in> <element> by <javascript|js> "<javascript>"

Executes a JavaScript expression or anonymous function on an element and binds the result to the given name.

Where

  • <name> is the name to bind the javascript return value to
  • <of|on|in> is of, on or in
  • <element> is the name of the element to execute the javascript on
  • <javascript|js> is javascript (or js, since v2.46.0)
  • <javascript> is the JavaScript expression or anonymous function to execute (can be in DocString position)
    • The reference to the element will be provided to the javascript through an implicit object named element.
    • For an expression: no return prefix is required
    • For an anonymous function: the syntax is (function(){ body })() where body must return a value

Example

  Given the red checkbox can be located by id "red"   When I navigate to "https://automationintesting.com/selenium/testpage"    And I click the red checkbox    And I capture my favorite color in the red checkbox by js        """        (function() {          var color = element.value          if (!element.checked) color = "Blue"          return color;        })()        """   Then my favorite color should be "Red"
I base64 decode <element>

Base64 decodes the text in the given element and binds the result to the same name in the global scope.

Where

  • <element> is the name of the element containing the text to decode

Example

  Given the data can be located by class "encoded-data"   When I base64 decode the data   Then the data should be "some binary data"
I base64 decode <element> as <name>

Base64 decodes the text in the given element and binds the result to the give name in the global scope.

Where

  • <element> is the name of the element containing the text to decode
  • <name> is the name to bind the decoded value to

Example

  Given the encoded data field can be located by class "encoded-data"   When I base64 decode the encoded data as the decoded data   Then the decoded data should be "some binary data"
I <highlight|locate> <element>

Locates and highlights the given element on the current page.

Where

  • <highlight|locate> is one of:
    • highlight or locate
  • <element> is the name of the element

Example

  Given the todo field can be located by class "new-todo"   When I navigate to "https://todomvc.com/examples/react"    And I locate the todo field

Then#

<element> should[ not] be <state>

Checks whether or not an element is in a given state.

Where

  • <element> is the name of the element to check
  • not negates the state if included
  • <state> is one of:
    • displayed to check if the element is displayed
    • hidden to check if the element is not displayed
    • checked (or ticked since v2.4.0) to check if a checkbox is ticked
    • unchecked (or unticked since v2.4.0) to check if a checkbox is not ticked
    • enabled to check if the element is enabled
    • disabled to check if the element is disabled

Example

  Given my todo list can be located by css ".todo-list"   When I navigate to "https://todomvc.com/examples/react"   Then my todo list should be hidden
<element> should[ not] <match> "<expression>"

Checks whether or not the text value of an element matches a given expression. Reports an assertion error if the match fails.

Where

  • <element> is the name of the element to check
  • not negates the match if included
  • <match> is the type of match to perform, one of:
    • be for exact match
    • contain for partial match
    • start with for partial leading match
    • end with for partial trailing match
    • match regex for regex match
    • match xpath for XML match
    • match json path for JSON match, since v1.4.0
    • match template for template match, since v2.16.0
    • match template file for template file match, since v2.16.0
  • <expression> is the expression to match (can be in DocString position)

Example

  Given the todo field can be located by class "new-todo"    And my todo list can be located by css ".todo-list"   When I navigate to "https://todomvc.com/examples/react"    And I enter "Get the milk" in the todo field   Then my todo list should contain "Get the milk"
<element> should[ not] <match> <expressionRef>

Checks whether or not the text value of an element matches a referenced expression. Reports an assertion error if the match fails.

Where

  • <element> is the name of the element to check
  • not negates the match if included
  • <match> is the type of match to perform, one of:
    • be for exact match
    • contain for partial match
    • start with for partial leading match
    • end with for partial trailing match
    • match regex for regex match
    • match xpath for XML match
    • match json path for JSON match, since v1.4.0
    • match template for template match, since v2.16.0
    • match template file for template file match, since v2.16.0
  • <expressionRef> is the name of the binding containing the expression to match
    • Can be the name of any binding that contains or resolves to an expression value, including a web element in which case the text in the element will be dynamically retrieved and used.

Example

  Given the todo field can be located by class "new-todo"    And my todo list can be located by css ".todo-list"    And my item is "Feed the cat"   When I navigate to "https://todomvc.com/examples/react"    And I enter my item in the todo field   Then my todo list should contain my item
<dropdown> <text|value> should[ not] <match> "<expression>"

Checks whether or not a dropdown selection matches a given expression. Reports an assertion error if the match fails.

Where

  • <dropdown> is the dropdown element to check
  • <text|value> is one of:
    • text to check the displayed text of the selection
    • value to check the option value of the selection
  • not negates the match if included
  • <match> is the type of match to perform, one of:
    • be for exact match
    • contain for partial match
    • start with for partial leading match
    • end with for partial trailing match
    • match regex for regex match
    • match xpath for XML match
    • match json path for JSON match, since v1.4.0
    • match template for template match, since v2.16.0
    • match template file for template file match, since v2.16.0
  • <expression> is the expression to match (can be in DocString position)

Example

  Given the age dropdown can be located by id "challenger_age"   When I navigate to "https://challengers.flood.io/step/2"    And I select the 2nd option in the age dropdown   Then the age dropdown value should be "18"
<dropdown> <text|value> should[ not] <match> <expressionRef>

Checks whether or not a dropdown selection matches a referenced expression. Reports an assertion error if the match fails.

Where

  • <dropdown> is the dropdown element to check
  • <text|value> is one of:
    • text to check the displayed text of the selection
    • value to check the option value of the selection
  • not negates the match if included
  • <match> is the type of match to perform, one of:
    • be for exact match
    • contain for partial match
    • start with for partial leading match
    • end with for partial trailing match
    • match regex for regex match
    • match xpath for XML match
    • match json path for JSON match, since v1.4.0
    • match template for template match, since v2.16.0
    • match template file for template file match, since v2.16.0
  • <expressionRef> is the name of the binding containing the expression to match
    • Can be the name of any binding that contains or resolves to an expression value, including a web element in which case the text in the element will be dynamically retrieved and used.

Example

  Given the age dropdown can be located by id "challenger_age"    And my age is "18"   When I navigate to "https://challengers.flood.io/step/2"    And I select the 2nd option in the age dropdown   Then the age dropdown value should be my age

Windows and tabs#

Given#

I have an open browser

Opens a browser if none are open

Example

  Given I have an open browser   When I navigate to "https://todomvc.com/examples/react"   Then I should have 1 open browser
I have no open browser

Closes all open browsers

Example

  Given I have no open browser   When I navigate to "https://todomvc.com/examples/react"   Then I should have 1 open browser

When#

I start a new browser

Starts a new browser session (or switches to exising one if it is already open).

Example

 Given I have no open browser  When I start a new browser  Then I should have 1 open browser
I close the[ current] browser

Closes the current browser session (or does nothing if one is not open).

Where

  • [ current] including the word current is optional and makes no difference, since v1.3.0

Example

  When I navigate to "https://todomvc.com/examples/react"   And I close the current browser   And I navigate to "https://todomvc.com/examples/vue/"   And I close the browser
I start a browser for <name>

Starts a new browser session with the given name (closes any existing browser of that name first).

Where

  • <name> is a name assigned to the browser session

Example

  When I start a browser for React   And I navigate to "https://todomvc.com/examples/react"   And I start a browser for Vue   And I navigate to "https://todomvc.com/examples/vue/"  Then I should have 2 open browsers
I switch to <name>

Switches to a named browser session (starts a new browser if one of that name is not already open). All browser actions performed after this will execute in the named session.

Where

  • <name> is the name of the browser session to switch to

Example

  When I start a browser for React   And I navigate to "https://todomvc.com/examples/react"   And I start a browser for Vue   And I navigate to "https://todomvc.com/examples/vue/"   And I switch to React  Then the current URL should contain "react"
I close the browser for <name>

Closes a named browser session (does nothing if one of that name is not open).

Where

  • <name> is the name of the browser session to close

Example

  When I start a browser for React   And I navigate to "https://todomvc.com/examples/react"   And I close the browser for React
I switch to the default content

Switches from an iframe to the default or main content window.

Example

  When I navigate to "https://page-with-iframes"   And I switch to the default content
I switch to the child <tab|window>

Switches to the most recently opened child tab or window (without closing the parent window)

Where

  • <tab|window> is either tab or window

Example

  Given the new window button can be located by name "newbrowserwindow123"   When I navigate to "https://nxtgenaiacademy.com/multiplewindows/"    And I click the new window button    And I switch to the child window
I close the child <tab|window>

Closes the currently active child tab or window and passes control back to the parent window.

Where

  • <tab|window> is either tab or window

Example

  Given the new tab button can be located by name "newbrowsertab453"   When I navigate to "https://nxtgenaiacademy.com/multiplewindows/"    And I click the new tab button    And I switch to the child tab    And I close the child tab
I switch to child <tab|window> <occurrence>

Switches to a child tab or window occurrence (without closing the parent window).

Where

  • <tab|window> is either tab or window
  • <occurrence> is the tab or window occurrence to switch to (1st opened is occurrence 1, 2nd is 2, ..)

Example

  Given the new window button can be located by name "newbrowserwindow123"   When I navigate to "https://nxtgenaiacademy.com/multiplewindows/"    And I click the new window button    And I switch to child window 1
I close child <tab|window> <occurrence>

Closes a child tab or window occurrence and passes control back to the parent window.

Where

  • <tab|window> is either tab or window
  • <occurrence> is the tab or window occurrence to close (1st opened is occurrence 1, 2nd is 2, ..)

Example

  Given the new tab button can be located by name "newbrowsertab453"   When I navigate to "https://nxtgenaiacademy.com/multiplewindows/"    And I click the new tab button    And I switch to child tab 1    And I close child tab 1
I switch to the <parent|root> <tab|window>

Switches to the parent window (without closing the currently active child window).

Where

  • <parent|root> is either parent (or root since v2.49.0)
  • <tab|window> is either tab or window

Example

  Given the new window button can be located by name "newbrowserwindow123"   When I navigate to "https://nxtgenaiacademy.com/multiplewindows/"    And I click the new window button    And I switch to child window 1    And I switch to the parent window
I <maximize|maximise> the window

Maximizes the currently active browser window to fill the entire screen area.

Where

  • <maximize|maximise> is either maximize or maximise (makes no difference)

Example

  When I navigate to "https://todomvc.com/examples/react"   And I maximize the window
I resize the window to width <w> and height <h>

Resizes the currently active browser window to the given dimensions.

Where

  • <w> is the width in pixels
  • <h> is the height in pixels

Example

  When I navigate to "https://todomvc.com/examples/react"   And I resize the window to width 1280 and height 720
I send "<keys>"

Sends a sequence of keys to the browser (for emulating keyboard shortcuts).

Where

  • <keys> is a , or + (since v2.53.0) separated list of keys to send.
    • Keys can be single keyboard characters or any supported key constants
    • Note: Keys behave differently on different platforms

Example

   When I navigate to "https://google.com"    And I send "COMMAND+t"

Then#

I should have 1 open browser

Checks that only one browser session is currently open. Reports an assertion error if not.

Example

 Given I have no open browser  When I navigate to "https://todomvc.com/examples/react"  Then I should have 1 open browser
I should have <count> open browsers

Checks that a given number of browsers are currently open. Reports an assertion error if not.

Where

  • count the expected number of open browsers

Example

 Given I have no open browser  When I navigate to "https://todomvc.com/examples/react"   And I start a browser for Vue   And I navigate to "https://todomvc.com/examples/vue"  Then I should have 2 open browsers

Alerts and popups#

When#

I accept the <alert|confirmation> popup

Accepts and closes an alert or confirmation popup by clicking OK.

Where

  • <alert|confirmation> is either:
    • alert for an alert box with an OK button
    • confirmation for a confirmation box with OK and Cancel buttons

Example

  Given the alert button can be located by css ".btn" at index 0   When I navigate to "https://www.seleniumeasy.com/test/javascript-alert-box-demo.html"    And I click the alert button    And I accept the alert popup
I dismiss the confirmation popup

Dismisses and closes a confirmation popup by clicking Cancel.

Example

  Given the confirmation button can be located by css ".btn" at index 1   When I navigate to "https://www.seleniumeasy.com/test/javascript-alert-box-demo.html"    And I click the confirmation button    And I dismiss the confirmation popup
I capture the <alert|confirmation> popup message

Captures the alert or confirmation popup message and binds it to the <alert|confirmation> popup message in the global scope.

Where

  • <alert|confirmation> is either:
    • alert for an alert box with an OK button
    • confirmation for a confirmation box with OK and Cancel buttons

Example

  Given the alert button can be located by css ".btn" at index 0   When I navigate to "https://www.seleniumeasy.com/test/javascript-alert-box-demo.html"    And I click the alert button    And I capture the alert popup message
I capture the <alert|confirmation> popup message as <name>

Captures the alert or confirmation popup message and binds it to the given name in the global scope.

Where

  • <alert|confirmation> is either:
    • alert for an alert box with an OK button
    • confirmation for a confirmation box with OK and Cancel buttons

Example

  Given the confirmation button can be located by css ".btn" at index 1   When I navigate to "https://www.seleniumeasy.com/test/javascript-alert-box-demo.html"    And I click the confirmation button    And I capture the confirmation popup message as the alert message

Then#

the <alert|confirmation> popup message should[ not] <match> "<expression>"

Checks whether or not the message in the alert or confirmation popup box matches a given expression. Reports an assertion error if the match fails.

Where

  • not negates the match if included
  • <match> is the type of match to perform, one of:
    • be for exact match
    • contain for partial match
    • start with for partial leading match
    • end with for partial trailing match
    • match regex for regex match
    • match xpath for XML match
    • match json path for JSON match, since v1.4.0
    • match template for template match, since v2.16.0
    • match template file for template file match, since v2.16.0
  • <expression> is the expression to match (can be in DocString position)

Example

  Given the alert button can be located by css ".btn" at index 0   When I navigate to "https://www.seleniumeasy.com/test/javascript-alert-box-demo.html"    And I click the alert button   Then the alert popup message should be "I am an alert box!"
the <alert|confirmation> popup message should[ not] <match> <expressionRef>

Checks whether or not the message in the alert or confirmation popup box matches a referenced expression. Reports an assertion error if the match fails.

Where

  • not negates the match if included
  • <match> is the type of match to perform, one of:
    • be for exact match
    • contain for partial match
    • start with for partial leading match
    • end with for partial trailing match
    • match regex for regex match
    • match xpath for XML match
    • match json path for JSON match, since v1.4.0
    • match template for template match, since v2.16.0
    • match template file for template file match, since v2.16.0
  • <expressionRef> is the name of the binding containing the expression to match
    • Can be the name of any binding that contains or resolves to an expression value, including a web element in which case the text in the element will be dynamically retrieved and used.

Example

  Given the confirmation button can be located by css ".btn" at index 1    And the expected message is "Press a button!"   When I navigate to "https://www.seleniumeasy.com/test/javascript-alert-box-demo.html"    And I click the confirmation button   Then the confirmation popup message should be the expected message

Screenshots and attachments#

When#

I capture the current screenshot

Captures the current screenshot and attaches it to the Gwen report.

Example

  Given the todo field can be located by class "new-todo"   When I navigate to "https://todomvc.com/examples/react"    And I enter "Walk the dog" in the todo field    And I capture the current screenshot
I capture the current screenshot as <name>

Captures the current screenshot, attaches it to the Gwen report, and binds the filepath of the saved image to the given name in the global scope.

Where

  • <name> the name to bind the captured image filepath to

Example

  Given the todo field can be located by class "new-todo"   When I navigate to "https://todomvc.com/examples/react"    And I enter "Walk the dog" in the todo field    And I capture the current screenshot as the screenshot image   Then the screenshot image should contain "path/to/image.png"
I attach "<filepath>" as "<name>"

Attaches a local file to the Gwen report and assigns it a name. The link to the attachment in the report will have the given name.

Where

  • <filepath> the path to the local file to attach
  • <name> the name to assign to the file attachment

Example

   When I attach "path/to/data.csv" as "data"

Sleeps and waits#

Given#

I wait <duration> second[s] when <element> is <actioned>

Triggers a sleep for a given number of seconds whenever a specific action is performed on an element.

Where

  • <duration> is the number of seconds to sleep
  • <element> the name of the web element
  • <actioned> is one of:
    • clicked to sleep when the element is clicked
    • right clicked to sleep when the element is right clicked, since v2.8.0
    • double clicked to sleep when the element is double clicked, since v2.12.0
    • submitted to sleep when the form element is submitted
    • checked (or ticked since v2.4.0) to sleep when the checkbox element is ticked
    • unchecked (or unticked since v2.4.0) to sleep when the checkbox element is unticked
    • selected to sleep when a dropdown option is selected in the element
    • deselected to sleep when a mutli-select dropdown option is deselected in the element, since v2.13.0
    • typed to sleep when text is typed into the element
    • entered to sleep when text is entered into the element
    • cleared to sleep when the text is cleared in the element
    • moved to to sleep when the focus is moved to the element
  • Include s after second when specifying a <duration> that is not 1, omit otherwise

Example

Given the submit button can be located by id "submit"  And I wait 3 seconds when the submit button is clicked When I navigate to "${token.website}"  And I click the submit button
I wait until <condition> when <element> is <actioned>

Triggers a wait for a condition whenever a specific action is performed on an element.

Where

  • <condition> the name of a binding containing a javascript function or expression that will return true when the condition is satisfied and false when it is not
  • <element> the name of the web element
  • <actioned> is one of:
    • clicked to wait when the element is clicked
    • right clicked to wait when the element is right clicked, since v2.8.0
    • double clicked to wait when the element is double clicked, since v2.12.0
    • submitted to wait when the form element is submitted
    • checked (or ticked since v2.4.0) to wait when the checkbox element is ticked
    • unchecked (or unticked since v2.4.0) to wait when the checkbox element is unticked
    • selected to wait when a dropdown option is selected in the element
    • deselected to wait when a mutli-select dropdown option is deselected in the element, since v2.13.0
    • typed to wait when text is typed into the element
    • entered to wait when text is entered into the element
    • cleared to wait when the text is cleared in the element
    • moved to to wait when the focus is moved to the element
  • Include s after second when specifying a <duration> that is not 1, omit otherwise

Example

  Given the submit button can be located by name "submit"    And the token field can be located by class "token"    And the submit button is displayed is defined by javascript "!!document.getElementById('submit')"    And I wait until the submit button is displayed when the token field is entered   When I navigate to "${token.website}"    And I enter "my token" in the token field    And I click the submit button

When#

I wait for <element>

Waits for an element to appear on a page for a default number of seconds before timing out.

Where

  • <element> is the name of the element to wait for

Example

  # Wait for a dynamically rendered input field   Given the dynamic input field can be located by tag "input"   When I wait for the dynamic input field   Then the dynamic input field should be displayed
I wait for <element> for <duration> second[s]

Waits for an element to appear on a page for a given number of seconds before timing out.

Where

  • <element> is the name of the element to wait for
  • <duration> is the number of seconds to wait before timing out
  • Include trailing s when specifying a <duration> that is not 1, omit otherwise

Example

  # Wait for a dynamically rendered input field   Given the dynamic input field can be located by tag "input"   When I wait for the dynamic input field for 3 seconds   Then the dynamic input field should be displayed
I wait for <element> text

Waits for the text of an element to appear on a page for a default number of seconds before timing out.

Where

  • <element> is the name of the element to wait for the text to appear

Example

  # Wait for a dynamically displayed token  Given the one time token can be located by javascript "$('.token').get(0)"   When I wait for the one time token text    And I capture the one time token
I wait for <element> text for <duration> second[s]

Waits for the text of an element to appear on a page for a given number of seconds before timing out.

Where

  • <element> is the name of the element to wait for the text to appear
  • <duration> is the number of seconds to wait before timing out
  • Include trailing s when specifying a <duration> that is not 1, omit otherwise

Example

  # Wait for a dynamically displayed token  Given the one time token can be located by javascript "$('.token').get(0)"   When I wait for the one time token text for 3 seconds    And I capture the one time token
I wait until <element> is[ not] <state>

Waits for an element to transition to a given state.

Where

  • <element> is the name of the element to wait for
  • not negates the state if included
  • <state> is one of:
    • displayed to wait until the element is displayed
    • hidden to wait until the element is not displayed
    • checked (or ticked since v2.4.0) to wait until a checkbox is ticked
    • unchecked (or unticked since v2.4.0) to wait until a checkbox is not ticked
    • enabled to wait until the element is enabled
    • disabled to wait until the element is disabled

Example

  Given my todo list can be located by css ".todo-list"    And the todo field can be located by class "new-todo"   When I navigate to "https://todomvc.com/examples/react"    And I enter "Get the milk" in the todo field    And I wait until my todo list is displayed
I wait until "<javascript>"

Repeatedly executes the given javascript expression or anonymous function until true is returned using no delay interval and default timeout period. The default timeout period is equal to the configured gwen.web.wait.seconds setting value.

Where

  • <javascript> is the javascript expression or anonymous function returning a boolean value (can be in DocString position)
    • For an expression: no return prefix is required
    • For an anonymous function: the syntax is (function(){ body })() where body must return a boolean

Example

 Given the heading can be located by tag "h1"  When I navigate to "https://challengers.flood.io/start"   And I wait until "!!$('h1')"  Then the heading should be "Welcome to our Script Challenge"
I wait until "<javascript>" using <delay> <delayUnit> delay

Repeatedly executes the given javascript expression or anonymous function until true is returned using the given delay interval and default timeout period. The default timeout period is equal to the configured gwen.web.wait.seconds setting value.

Where

  • <javascript> is the javascript expression or anonymous function returning a boolean value
    • For an expression: no return prefix is required
    • For an anonymous function: the syntax is (function(){ body })() where body must return a boolean
  • <delay> is the delay period between repetitive checks
  • <delayUnit> is one of:
    • second
    • millisecond

Example

  Given the heading can be located by tag "h1"   When I navigate to "https://challengers.flood.io/start"    And I wait until "!!$('h1')" using 200 millisecond delay   Then the heading should be "Welcome to our Script Challenge"
I wait until "<javascript>" using <timeout> <timeoutUnit> timeout

Repeatedly executes the given javascript expression or anonymous function until true is returned using no delay interval and the given timeout period.

Where

  • <javascript> is the javascript expression or anonymous function returning a boolean value
    • For an expression: no return prefix is required
    • For an anonymous function: the syntax is (function(){ body })() where body must return a boolean
  • <timeout> is the timeout period
  • <timeoutUnit> is one of:
    • minute
    • second
    • millisecond

Example

  Given the heading can be located by tag "h1"   When I navigate to "https://challengers.flood.io/start"    And I wait until "!!$('h1')" using 3 second timeout   Then the heading should be "Welcome to our Script Challenge"
I wait until "<javascript>" using <delay> <delayUnit> delay and <timeout> <timeoutUnit> timeout

Repeatedly executes the given javascript expression or anonymous function until true is returned using the given delay interval and timeout period.

Where

  • <javascript> is the javascript expression or anonymous function returning a boolean value
    • For an expression: no return prefix is required
    • For an anonymous function: the syntax is (function(){ body })() where body must return a boolean
  • <delay> is the delay period between repetitive checks
  • <delayUnit> is one of:
    • second
    • millisecond
  • <timeout> is the timeout period
  • <timeoutUnit> is one of:
    • minute
    • second
    • millisecond

Example

  Given the heading can be located by tag "h1"   When I navigate to "https://challengers.flood.io/start"    And I wait until "!!$('h1')" using 250 millisecond delay and 3 second timeout   Then the heading should be "Welcome to our Script Challenge"
I wait until <condition>

Waits until a condition is satisfied.

Where

  • <condition> is the name of a binding containing a javascript function or expression that will return true when the condition is satisfied and false when it is not

Example

 Given the heading can be located by tag "h1"   And the heading is displayed is defined by javascript "!!$('h1')"  When I navigate to "https://challengers.flood.io/start"   And I wait until the heading is displayed  Then the heading should be "Welcome to our Script Challenge"
I wait until <condition> using <delay> <delayUnit> delay

Repeatedly waits until the given condition is satisfied using the given delay interval and default timeout period. The default timeout period is equal to the configured gwen.web.wait.seconds setting value.

Where

  • <condition> is the name of a binding containing a javascript function or expression that will return true when the condition is satisfied and false when it is not
  • <delay> is the delay period between repetitive checks
  • <delayUnit> is one of:
    • second
    • millisecond

Example

  Given the heading can be located by tag "h1"    And the heading is displayed is defined by javascript "!!$('h1')"   When I navigate to "https://challengers.flood.io/start"    And I wait until the heading is displayed using 200 millisecond delay   Then the heading should be "Welcome to our Script Challenge"
I wait until <condition> using <timeout> <timeoutUnit> timeout

Repeatedly waits until the given condition is satisfied using no delay interval and the given timeout period.

Where

  • <condition> is the name of a binding containing a javascript function or expression that will return true when the condition is satisfied and false when it is not
  • <timeout> is the timeout period
  • <timeoutUnit> is one of:
    • minute
    • second
    • millisecond

Example

  Given the heading can be located by tag "h1"    And the heading is displayed is defined by javascript "!!$('h1')"   When I navigate to "https://challengers.flood.io/start"    And I wait until the heading is displayed using 3 second timeout   Then the heading should be "Welcome to our Script Challenge"
I wait until <condition> using <delay> <delayUnit> delay and <timeout> <timeoutUnit> timeout

Repeatedly waits until the given condition is satisfied using the given delay interval and timeout period.

Where

  • <condition> is the name of a binding containing a javascript function or expression that will return true when the condition is satisfied and false when it is not
  • <delay> is the delay period between repetitive checks
  • <delayUnit> is one of:
    • second
    • millisecond
  • <timeout> is the timeout period
  • <timeoutUnit> is one of:
    • minute
    • second
    • millisecond

Example

  Given the heading can be located by tag "h1"    And the heading is displayed is defined by javascript "!!$('h1')"   When I navigate to "https://challengers.flood.io/start"    And I wait until the heading is displayed using 250 millisecond delay and 3 second timeout   Then the heading should be "Welcome to our Script Challenge"
I wait <duration> second[s]

Sleeps for the given number of seconds.

Where

  • <duration> is the number of seconds to sleep
  • Include trailing s when specifying a <duration> that is not 1, omit otherwise

Example

  When I wait for 5 seconds

Scripts and processes#

When#

I execute <javascript|js> "<expression>"

Executes a JavaScript expression or anonymous function.

Where

  • <javascript|js> is javascript (or js since v2.46.0)
  • <expression> is the JavaScript expression or anonymous function to execute (can be in DocString position)
    • For an anonymous function: the syntax is (function(){ body })() where body must return a value

Example

  When I execute js "alert('Hello Gwen World')"
I execute system process "<expression>"

Executes a local system process or script.

Where

  • <expression> is the system process or script to execute

Example

  When I execute system process "echo 'Hello Gwen World'"   And I execute system process "path/to/script.bat"
I execute system process "<expression>" delimited by "<delimiters>"

Executes a delimited local system process or script.

Where

  • <expression> the delimited system process to execute
    • Delmiters are required for special cases such as when unbalanced quoted strings are passed as arguments (see example).
  • <delmiters> is a regex pattern defining the delimiter(s) used in <expression>

Example

  When I execute system process "echo,"quoted text " and orphan quote"" delimited by ","
I execute a unix system process "<expression>"

Executes a local unix system process or shell script.

Where

  • <expression> is the system process or script to execute

Example

  When I execute a unix system process "echo 'Hello Gwen World'"   And I execute a unix system process "./path/to/script.sh"
I execute a unix system process "<expression>" delimited by "<delimiters>"

Executes a delimited local unix system process or script.

Where

  • <expression> the delimited system process to execute
    • Delmiters are required for special cases such as when unbalanced quoted strings are passed as arguments (see example).
  • <delmiters> is a regex pattern defining the delimiter(s) used in <expression>

Example

  When I execute a unix system process "echo,"quoted text " and orphan quote"" delimited by ","

SQL selects and updates#

Given#

<name> is defined in the <dbName> database by sql "<selectStmt>"

Associates the result of an SQL database query to the given name in the global scope. The value is resolved every time the name is referenced.

Where

  • <name> is the name to bind the SQL query result to
  • <dbName> the name of the configured database to execute the query on
  • <selectStmt> is the SQL query that will return the value to assign (can be in DocString position)

Configuration

  • 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

Example

  Given the email address is defined in the feedback database by sql        """        select email from comments        """   Then the email address should be "some.person@example.com"

Set GWEN_CLASSPATH variable in the environment to include the JDBC driver JAR

export GWEN_CLASSPATH=/path-to-driver/mysql-connector-java-5.1.40-bin.jar

Configure the database in your settings. In this example, <dbName>=feedback

gwen.db.feedback.driver = com.mysql.jdbc.Drivergwen.db.feedback.url = jdbc:mysql://localhost/feedback?user=myUser&amp;password=myPassword&amp;

When#

I update the <dbName> database by sql "<updateStmt>"

Executes an SQL udpate statement on a configured database.

Where

  • <dbName> the name of the configured database to run the update statement on
  • <updateStmt> is the SQL update statement to execute (can be in DocString position)

Returns

  • <dbName> rows affected = the number of rows affected by the update

Configuration

  • 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

Example

  When I update the feedback database by sql       """       update comments set email='new@example.com' where email='old@example.com'       """  Then feedback rows affected should be "1"

Set GWEN_CLASSPATH variable in the environment to include the JDBC driver JAR

export GWEN_CLASSPATH=/path-to-driver/mysql-connector-java-5.1.40-bin.jar

Configure the database in your settings. In this example, <dbName>=feedback

gwen.db.feedback.driver = com.mysql.jdbc.Drivergwen.db.feedback.url = jdbc:mysql://localhost/feedback?user=myUser&amp;password=myPassword&amp;

Setting overrides#

Given#

my <name> setting is "<value>"

Overrides a Gwen setting.

Where

  • <name> is name of the Gwen setting to override
  • <value> is the value to set

Notes

  • As of v2.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.
  • Prior to v2.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.

Example

  Given my gwen.web.useragent setting is "I am robot"
I reset my <name> setting

Resets a Gwen setting to remove a previous override.

Where

Example

  Given I reset my gwen.web.useragent setting

Control structures#

ForEach#

<step> for each <element> located by <selector> "<expression>"

Executes a step for each element in a list of elements in the current scope with a default lookup timeout.

Where

  • <step> is the DSL step or StepDef to execute for each element
  • <element> is the name that will be assigned to the current element occurrence (element is accessible in <step> by this name)
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression returning one or many elements

Example

  Given the todo field can be located by class "new-todo"    And the active count can be located by css ".todo-count strong"   When I navigate to "https://todomvc.com/examples/react"    And I enter "Walk the dog" in the todo field    And I enter "Feed the cat" in the todo field    And I tick todo item for each todo item located by css ".todo-list .toggle"   Then the active count should be "0"
<step> for each <element> located by <selector> "<expression>" with no <wait|timeout>

Executes a step for each element in a list of elements in the current scope with a no lookup timeout.

Where

  • <step> is the DSL step or StepDef to execute for each element
  • <element> is the name that will be assigned to the current element occurrence (element is accessible in <step> by this name)
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression returning one or many elements
  • <wait|timeout> is either wait or timeout

Example

  Given the todo field can be located by class "new-todo"    And the active count can be located by css ".todo-count strong"   When I navigate to "https://todomvc.com/examples/react"    And I enter "Walk the dog" in the todo field    And I enter "Feed the cat" in the todo field    And I tick todo item for each todo item located by css ".todo-list .toggle" with no wait   Then the active count should be "0"
<step> for each <element> located by <selector> "<expression>" with <timeoutSecs> second <wait|timeout>

Executes a step for each element in a list of elements in the current scope with a given lookup timeout.

Where

  • <step> is the DSL step or StepDef to execute for each element
  • <element> is the name that will be assigned to the current element occurrence (element is accessible in <step> by this name)
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression returning one or many elements
  • <timeoutSecs> is the timeout period in seconds
  • <wait|timeout> is either wait or timeout

Example

  Given the todo field can be located by class "new-todo"    And the active count can be located by css ".todo-count strong"   When I navigate to "https://todomvc.com/examples/react"    And I enter "Walk the dog" in the todo field    And I enter "Feed the cat" in the todo field    And I tick todo item for each todo item located by css ".todo-list .toggle" with 5 second timeout   Then the active count should be "0"
<step> for each <element> located by <selector> "<expression>" in <containerElement>

Executes a step for each element in a list of elements in a container element in the current scope with a default lookup timeout.

Where

  • <step> is the DSL step or StepDef to execute for each element
  • <element> is the name that will be assigned to the current element occurrence (element is accessible in <step> by this name)
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression returning one or many elements
  • <containerElement> is the name assigned to the container element

Example

  Given the todo field can be located by class "new-todo"    And the todo list can be located by class "todo-list"    And the active count can be located by css ".todo-count strong"   When I navigate to "https://todomvc.com/examples/react"    And I enter "Walk the dog" in the todo field    And I enter "Feed the cat" in the todo field    And I tick todo item for each todo item located by class "toggle" in the todo list   Then the active count should be "0"
<step> for each <element> located by <selector> "<expression>" in <containerElement> with no <wait|timeout>

Executes a step for each element in a list of elements in a container element in the current scope with no lookup timeout.

Where

  • <step> is the DSL step or StepDef to execute for each element
  • <element> is the name that will be assigned to the current element occurrence (element is accessible in <step> by this name)
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression returning one or many elements
  • <containerElement> is the name assigned to the container element
  • <wait|timeout> is either wait or timeout

Example

  Given the todo field can be located by class "new-todo"    And the todo list can be located by class "todo-list"    And the active count can be located by css ".todo-count strong"   When I navigate to "https://todomvc.com/examples/react"    And I enter "Walk the dog" in the todo field    And I enter "Feed the cat" in the todo field    And I tick todo item for each todo item located by class "toggle" in the todo list with no timeout   Then the active count should be "0"
<step> for each <element> located by <selector> "<expression>" in <containerElement> with <timeoutSecs> second <wait|timeout>

Executes a step for each element in a list of elements in a container element in the current scope with a given lookup timeout.

Where

  • <step> is the DSL step or StepDef to execute for each element
  • <element> is the name that will be assigned to the current element occurrence (element is accessible in <step> by this name)
  • <selector> is the selector type, one of:
    • id for selecting by id attribute
    • name for selecting by name attribute
    • tag name (or tag since v2.46.0) for selecting by tag name
    • css selector (or css since v2.46.0) for selecting by css expression
    • class name (or class since v2.46.0) for selecting by class attribute
    • xpath for selecting by XPath
    • link text for selecting by link text
    • partial link text for selecting by partial link text
    • javascript (or js since v2.46.0) for selecting by JavaScript
  • <expression> is the selector expression returning one or many elements
  • <containerElement> is the name assigned to the container element
  • <timeoutSecs> is the timeout period in seconds
  • <wait|timeout> is either wait or timeout

Example

  Given the todo field can be located by class "new-todo"    And the todo list can be located by class "todo-list"    And the active count can be located by css ".todo-count strong"   When I navigate to "https://todomvc.com/examples/react"    And I enter "Walk the dog" in the todo field    And I enter "Feed the cat" in the todo field    And I tick todo item for each todo item located by class "toggle" in the todo list with 3 second wait   Then the active count should be "0"
<step> for each <element> in <elements>

Executes a step for each element in a list of elements in the current scope with a default lookup timeout.

Where

  • <step> is the DSL step or StepDef to execute for each element
  • <element> is the name that will be assigned to the current element occurrence (element is accessible in <step> by this name)
  • <elements> is the name of the locator binding returning multiple elements

Example

  Given the todo field can be located by class "new-todo"    And the active count can be located by css ".todo-count strong"    And all todo items can be located by css ".todo-list .toggle"   When I navigate to "https://todomvc.com/examples/react"    And I enter "Walk the dog" in the todo field    And I enter "Feed the cat" in the todo field    And I tick todo item for each todo item in all todo items   Then the active count should be "0"
<step> for each data record

Executes a step for each record in a data table.

Where

  • <step> is the DSL step or StepDef to execute for each record
  • The following implicit bindings are available in <step>:
    • record.number is the current record number (starting at 1)
    • record.index is the record index (starting at 0), since v2.30.1
    • data[name] is the data of an element in the current record, where name is the name of a record element

Example

  @StepDef  @DataTable(horizontal="Item")  Scenario: I have the following active items      Given the todo field can be located by class "new-todo"        And the active count can be located by css ".todo-count strong"       When I navigate to "https://todomvc.com/examples/react"        And I enter "${data[Item]}" in the todo field for each data record       Then the active count should be "3"
  Scenario: my scenario      Given I have the following active items            | Walk the dog |            | Get the milk |            | Feed the cat |
<step> for each <entry> in <source> delimited by "<delimiter>"

Where

  • <step> is the DSL step or StepDef to execute for each delimited entry
  • <entry> is the name that will be assigned to the current entry occurrence (entry is accessible in <step> by this name)
  • <source> is the name of the binding containing the delimitted values
    • Can be the name of any binding that contains or resolves to a delmited list of values, including a web element in which case the text in the element will be dynamically retrieved and used.
  • <delimiter> the delimiter used in <source> to separate each value

Example

  Given the todo field can be located by class "new-todo"    And the active count can be located by css ".todo-count strong"    And my items is "Walk the dog, Feed the cat, Get the milk"   When I navigate to "https://todomvc.com/examples/react"    And I enter todo item in the todo field for each todo item in my items delimited by ","   Then the active count should be "3"

Until/While#

<step> <until|while> <condition>

Repeatedly exectues a step until or while a condition is satisfied using a default delay and timeout period. 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.

Where

  • <step> is the DSL step or StepDef to execute in each iteration
  • <until|while> is one of:
    • until to repeat until the condition is satisfied
    • while to repeat while the condition is satisfied
  • <condition> the name of a binding containing a javascript function or expression that will return true when the condition is satisfied and false when it is not.
  • The following implicit binding is available in <step>:
    • iteration number (or iteration.number since v2.52.0) is the current iteration number (starting at 1)

Example

    Given the search field can be located by name "q"      And the next page link can be located by id "pnnext"      And topic is "what is gwen"      And topic link can be located by partial link text "${topic}"      And topic not found is defined by js          """          [...document.querySelectorAll("a")]            .filter(a => a.textContent.includes('${topic}'))            .length == 0          """     When I navigate to "https://google.com"      And I enter "gwen interpreter" in the search field      And I click the next page link while topic not found      And I click topic link     Then the page title should contain "${topic}"
<step> <until|while> <condition> using <delay> <delayUnit> delay

Repeatedly exectues a step until or while a condition is satisfied using the given delay interval and default timeout period. The default timeout period is 30 times the specified delay.

Where

  • <step> is the DSL step or StepDef to execute in each iteration
  • <until|while> is one of:
    • until to repeat until the condition is satisfied
    • while to repeat while the condition is satisfied
  • <condition> the name of a binding containing a javascript function or expression that will return true when the condition is satisfied and false when it is not.
  • <delay> is the delay period between steps repetitions
  • <delayUnit> is one of:
    • second
    • millisecond
  • The following implicit binding is available in <step>:
    • iteration number (or iteration.number since v2.52.0) is the current iteration number (starting at 1)

Example

  Given the search field can be located by name "q"      And the next page link can be located by id "pnnext"      And topic is "what is gwen"      And topic link can be located by partial link text "${topic}"      And topic not found is defined by js "$('h3:contains("${topic}")').length == 0)"          """          [...document.querySelectorAll("a")]            .filter(a => a.textContent.includes('${topic}'))            .length == 0          """     When I navigate to "https://google.com"      And I enter "gwen interpreter" in the search field      And I click the next page link while topic not found using 1 second delay      And I click topic link     Then the page title should contain "${topic}"
<step> <until|while> <condition> using <timeout> <timeoutUnit> timeout

Repeatedly exectues a step until or while a condition is satisfied using a default delay and given timeout period. The default delay between iterations is one tenth of the configured gwen.web.wait.seconds setting (or 1 second if not set).

Where

  • <step> is the DSL step or StepDef to execute in each iteration
  • <until|while> is one of:
    • until to repeat until the condition is satisfied
    • while to repeat while the condition is satisfied
  • <condition> the name of a binding containing a javascript function or expression that will return true when the condition is satisfied and false when it is not.
  • <timeout> is the timeout period
  • <timeoutUnit> is one of:
    • minute
    • second
    • millisecond
  • The following implicit binding is available in <step>:
    • iteration number (or iteration.number since v2.52.0) is the current iteration number (starting at 1)

Example

  Given the search field can be located by name "q"      And the next page link can be located by id "pnnext"      And topic is "what is gwen"      And topic link can be located by partial link text "${topic}"      And topic not found is defined by js          """          [...document.querySelectorAll("a")]            .filter(a => a.textContent.includes('${topic}'))            .length == 0          """     When I navigate to "https://google.com"      And I enter "gwen interpreter" in the search field      And I click the next page link while topic not found using 15 second timeout      And I click topic link     Then the page title should contain "${topic}"
<step> <until|while> <condition> using <delay> <delayUnit> delay and <timeout> <timeoutUnit> timeout

Repeatedly exectues a step until or while a condition is satisfied using the given delay interval and timeout period.

Where

  • <step> is the DSL step or StepDef to execute in each iteration
  • <until|while> is one of:
    • until to repeat until the condition is satisfied
    • while to repeat while the condition is satisfied
  • <condition> the name of a binding containing a javascript function or expression that will return true when the condition is satisfied and false when it is not.
  • <delay> is the delay period between steps repetitions
  • <delayUnit> is one of:
    • second
    • millisecond
  • <timeout> is the timeout period
  • <timeoutUnit> is one of:
    • minute
    • second
    • millisecond
  • The following implicit binding is available in <step>:
    • iteration number (or iteration.number since v2.52.0) is the current iteration number (starting at 1)

Example

  Given the search field can be located by name "q"      And the next page link can be located by id "pnnext"      And topic is "what is gwen"      And topic link can be located by partial link text "${topic}"      And topic not found is defined by js          """          [...document.querySelectorAll("a")]            .filter(a => a.textContent.includes('${topic}'))            .length == 0          """     When I navigate to "https://google.com"      And I enter "gwen interpreter" in the search field      And I click the next page link while topic not found using 1 second delay and 5 second timeout      And I click topic link     Then the page title should contain "${topic}"
<step> <until|while> <condition> using no delay and <timeout> <timeoutUnit> timeout

Repeatedly exectues a step until or while a condition is satisfied using no delay and the given timeout period.

Where

  • <step> is the DSL step or StepDef to execute in each iteration
  • <until|while> is one of:
    • until to repeat until the condition is satisfied
    • while to repeat while the condition is satisfied
  • <condition> the name of a binding containing a javascript function or expression that will return true when the condition is satisfied and false when it is not.
  • <timeout> is the timeout period
  • <timeoutUnit> is one of:
    • minute
    • second
    • millisecond
  • The following implicit binding is available in <step>:
    • iteration number (or iteration.number since v2.52.0) is the current iteration number (starting at 1)

Example

  Given the search field can be located by name "q"      And the next page link can be located by id "pnnext"      And topic is "what is gwen"      And topic link can be located by partial link text "${topic}"      And topic not found is defined by js          """          [...document.querySelectorAll("a")]            .filter(a => a.textContent.includes('${topic}'))            .length == 0          """     When I navigate to "https://google.com"      And I enter "gwen interpreter" in the search field      And I click the next page link while topic not found using no delay and 15 second timeout      And I click topic link     Then the page title should contain "${topic}"
<step> <until|while> <condition> using no delay

Repeatedly exectues a step until or while a condition is satisfied using no delay and the default timeout period of 30 seconds.

Where

  • <step> is the DSL step or StepDef to execute in each iteration
  • <until|while> is one of:
    • until to repeat until the condition is satisfied
    • while to repeat while the condition is satisfied
  • <condition> the name of a binding containing a javascript function or expression that will return true when the condition is satisfied and false when it is not.
  • The following implicit binding is available in <step>:
    • iteration number (or iteration.number since v2.52.0) is the current iteration number (starting at 1)

Example

  Given the search field can be located by name "q"      And the next page link can be located by id "pnnext"      And topic is "what is gwen"      And topic link can be located by partial link text "${topic}"      And topic not found is defined by js          """          [...document.querySelectorAll("a")]            .filter(a => a.textContent.includes('${topic}'))            .length == 0          """     When I navigate to "https://google.com"      And I enter "gwen interpreter" in the search field      And I click the next page link while topic not found using no delay      And I click topic link     Then the page title should contain "${topic}"

If#

<step> if <condition>

Executes a step if a condition is true.

Where

  • <step> is the DSL step or StepDef to potentially execute
  • <condition> the name of a binding containing a javascript function or expression that will return true when the condition is satisfied and false when it is not

Example

  Given the search field can be located by name "q"    And topic is "Automation Bindings"    And topic link can be located by partial link text "${topic}"    And topic found is defined by js        """        [...document.querySelectorAll("a")]            .filter(a => a.textContent.includes('${topic}'))            .length > 0        """   When I navigate to "https://google.com"    And I enter "gwen automation" in the search field    And I click topic link if topic found   Then the page title should contain "${topic}" if topic found