Gwen DSL
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.
Bindings
Text bindings
<name> is "<value>"
Binds the given value to a name in the global scope.
<name> is "<value>"
<name> is <blank|empty|true|false>
Binds a literal value to a name in the global scope.
<name> is <blank|empty|true|false>
File bindings
<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.
<name> is defined by file "<filepath>"
Where
<name>is the name to associated the file contents<filepath>the path to the file (can be in DocString position)
Optionally accepts the @Eager or @Lazy annotations.
@Eagerimmediately evaluates the<expression>and binds the result to<name>@Lazyevaluates the<expression>and binds the result to<name>when it is first referenced- In the absence of either annotation,
<expression>is evaluated every time<name>is referenced
Example
Given the content is defined by file "path/to/file.txt"
<name> is defined by <encoding> file "<filepath>"
Associates a name with the contents of a file using a given character encoding. The value is resolved every time the name is referenced.
<name> is defined by <encoding> file "<filepath>"
Where
<name>is the name to associated the file contents<encoding>is the encoding to use when reading the file<filepath>the path to the file (can be in DocString position)
Optionally accepts the @Eager or @Lazy annotations.
@Eagerimmediately evaluates the<expression>and binds the result to<name>@Lazyevaluates the<expression>and binds the result to<name>when it is first referenced- In the absence of either annotation,
<expression>is evaluated every time<name>is referenced
Example
Given the content is defined by UTF-8 file "path/to/file.txt"
Regex bindings
<name> is defined in <textRef> by regex "<expression>"
Captures text from a text reference using the given regex expression and associates it with the given name. The value is resolved every time the name is referenced.
<name> is defined in <textRef> by regex "<expression>"
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
Optionally accepts the @Eager, @Lazy or @Masked annotations.
@Eagerimmediately evaluates the<expression>and binds the result to<name>@Lazyevaluates the<expression>and binds the result to<name>when it is first referenced- In the absence of either of the above annotations,
<expression>is evaluated every time<name>is referenced @Maskedmasks the captured value to prevent it from being logged as clear text
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"
XML bindings
<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.
<name> is defined by the <nodeType> in <xmlRef> by xpath "<expression>"
Where
<name>is the name of the name to associate the captured value to<nodeType>is one of:textto capture the text nodenodeto capture a single nodenodesetto 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
Optionally accepts the @Eager, @Lazy or @Masked annotations.
@Eagerimmediately evaluates the<expression>and binds the result to<name>@Lazyevaluates the<expression>and binds the result to<name>when it is first referenced- In the absence of either of the above annotations,
<expression>is evaluated every time<name>is referenced @Maskedmasks the captured value to prevent it from being logged as clear text
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"
JSON bindings
<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.
<name> is defined in <jsonRef> by json path "<expression>"
Where
<name>is the name of the name to associate the captured value to<nodeType>is one of:textto capture the text nodenodeto capture a single nodenodesetto 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
Optionally accepts the @Eager, @Lazy or @Masked annotations.
@Eagerimmediately evaluates the<expression>and binds the result to<name>@Lazyevaluates the<expression>and binds the result to<name>when it is first referenced- In the absence of either of the above annotations,
<expression>is evaluated every time<name>is referenced @Maskedmasks the captured value to prevent it from being logged as clear text
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"
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.
I capture the content in <element> by json path "<expression>" as <name>
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"
JS bindings
<name> is defined by <javascript|js> "<script>"
Associates a name with the return value of a JavaScript expression or function.
<name> is defined by <javascript|js> "<script>"
Where
<name>is the name to associate<javascript|js>isjavascript(orjssince v2.46.0)<script>is the javascript expression or function that will return the value (can be in DocString position)- For a one liner expression, no function, arrow declaration or
returnprefix is required For a function, use either:
- Arrow syntax (preferred):
(arg1, arg2, ..argN) => { body }(Since v3.56.0) - Or anonymous function syntax (legacy):
(function(arg1, arg2, ..argN){ body })(arguments[0], arguments[1], ..arguments[N])
- Arrow syntax (preferred):
- For a one liner expression, no function, arrow declaration or
Optionally accepts the @Eager, @Lazy or @Masked annotations.
@Eagerimmediately evaluates the<expression>and binds the result to<name>@Lazyevaluates the<expression>and binds the result to<name>when it is first referenced- In the absence of either of the above annotations,
<expression>is evaluated every time<name>is referenced @Maskedmasks the captured value to prevent it from being logged as clear text
Examples
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 by <javascriptRef> applied to "<argument>"
Applies a JavaScript function to an argument and binds the result to <name> in the global scope.
<name> is defined by <javascriptRef> applied to "<argument>"
<name> in the global scope.Where
<name>is the name to bind the function result to<javascriptRef>is the name of the binding containing the javascript function to apply<argument>argument to apply the function
Optionally accepts the @Eager, @Lazy or @Masked annotations.
@Eagerimmediately evaluates the<expression>and binds the result to<name>@Lazyevaluates the<expression>and binds the result to<name>when it is first referenced- In the absence of either of the above annotations,
<expression>is evaluated every time<name>is referenced @Maskedmasks the captured value to prevent it from being logged as clear text
Examples
Given iso date is defined by js "new Date().toISOString().substring(0, 10)"
And toDMY is defined by js
"""
(ymd) => {
var parts = ymd.split('-');
return parts[2] + '/' + parts[1] + '/' + parts[0];
}
"""
And dmy date is defined by toDMY applied to "${iso date}"
Then dmy date should match regex "^([0-2]\d|3[01])/([0]\d|1[0-2])/\d{4}$"
Given toMDY is defined by js
"""
(ymd) => {
var months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
var parts = ymd.split('-');
return months[parseInt(parts[1]) - 1] + ' ' + parts[2] + ' ' + parts[0];
}
"""
And dmy date is defined by toMDY applied to "2022-04-05"
Then dmy date should be "Apr 05 2022"
<name> is defined by <javascriptRef> applied to "<arguments>" delimited by "<delimiter>"
Applies a JavaScript function to mutiple arguments using a customer delimiter and binds the result to <name> in the global scope.
<name> is defined by <javascriptRef> applied to "<arguments>" delimited by "<delimiter>"
<name> in the global scope.Where
<name>is the name to bind the function result to<javascriptRef>is the name of the binding containing the javascript function to apply<arguments>a delimited list of arguments to apply the function to<delimiter>is the delmiter used in<arguments>- The 1st agrument is referenced in the JavaScript as
arguments[0], the 2nd argument asarguments[1], the 3rd asarguments[2]and so on.
- The 1st agrument is referenced in the JavaScript as
Optionally accepts the @Eager, @Lazy or @Masked annotations.
@Eagerimmediately evaluates the<expression>and binds the result to<name>@Lazyevaluates the<expression>and binds the result to<name>when it is first referenced- In the absence of either of the above annotations,
<expression>is evaluated every time<name>is referenced @Maskedmasks the captured value to prevent it from being logged as clear text
Examples
Given iso date is defined by js "new Date().toISOString().substring(0, 10)"
And toDMY is defined by js "(y,m,d) => d + '/' + m + '/' + y"
And dmy date is defined by toDMY applied to "${iso date}" delimited by "-"
Then dmy date should match regex "^([0-2]\d|3[01])/([0]\d|1[0-2])/\d{4}$"
Given toISO is defined by js
"""
(m,d,y) => {
var months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
var mNo = months.indexOf(m) + 1;
if (mNo < 10) mNo = '0' + mNo;
return y + '-' + mNo + '-' + d;
}
"""
And iso date is defined by toISO applied to "Apr 05 2022" delimited by " "
Then iso date should be "2022-04-05"
<name> is defined by <javascriptRef> applied to <element>
Applies a JavaScript function to an element and binds the result to <name> in the global scope.
<name> is defined by <javascriptRef> applied to <element>
<name> in the global scope.Where
<name>is the name to bind the function result to<javascriptRef>is the name of the binding containing the javascript single argument function to apply<element>is the name of the web element to apply the function to
Optionally accepts the @Eager, @Lazy or @Masked annotations.
@Eagerimmediately applies the function to the element and binds the result to<name>@Lazyapplies the function to the element and binds the result to<name>when it is first referenced- In the absence of either of the above annotations, the function is applied to the element every time
<name>is referenced @Maskedmasks the captured value to prevent it from being logged as clear text
Examples
Given getHref is defined by js "(elem) => elem.getAttribute('href')"
And the todo link can be located by xpath "//a[contains(text(),'TodoMVC')]"
And href is defined by getHref applied to the todo link
When I navigate to "https://todomvc.com/examples/react/dist/"
Then href should be "http://todomvc.com"
Given getHref is defined by js
"""
(elem) => {
return elem.getAttribute('href')
}
"""
And the todo link can be located by xpath "//a[contains(text(),'TodoMVC')]"
When I navigate to "https://todomvc.com/examples/react/dist/"
And @Eager href is defined by getHref applied to the todo link
Then href should be "http://todomvc.com"
System Processes bindings
<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.
<name> is defined by system process "<expression>"
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)
Optionally accepts the @Eager, @Lazy or @Masked annotations.
@Eagerimmediately evaluates the<expression>and binds the result to<name>@Lazyevaluates the<expression>and binds the result to<name>when it is first referenced- In the absence of either of the above annotations,
<expression>is evaluated every time<name>is referenced @Maskedmasks the captured value to prevent it from being logged as clear text
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.
<name> is defined by system process "<expression>" delimited by "<delimiters>"
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>
Optionally accepts the @Eager, @Lazy or @Masked annotations.
@Eagerimmediately evaluates the<expression>and binds the result to<name>@Lazyevaluates the<expression>and binds the result to<name>when it is first referenced- In the absence of either of the above annotations,
<expression>is evaluated every time<name>is referenced @Maskedmasks the captured value to prevent it from being logged as clear text
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 unix system process "<expression>"
Associates a name with the return value of a local unix system process. The value is resolved every time the name is referenced.
<name> is defined by unix system process "<expression>"
Where
<name>is the name to associated the returned value to<expression>is the unix system process that will return the value to assign (can be in DocString position)
Optionally accepts the @Eager, @Lazy or @Masked annotations.
@Eagerimmediately evaluates the<expression>and binds the result to<name>@Lazyevaluates the<expression>and binds the result to<name>when it is first referenced- In the absence of either of the above annotations,
<expression>is evaluated every time<name>is referenced @Maskedmasks the captured value to prevent it from being logged as clear text
Example
Given a file.csv with content:
Word1,Word2,Compound
basket,ball,basketball
sun,flower,sunflower
The following will print the data and line up each column
Given my table is defined by unix system process "cat file.csv | column -t -s\,"
Then my table should be
"""
Word1 Word2 Compound
basket ball basketball
sun flower sunflower
"""
Element locators
<element> can be located by <selector> "<expression>"
Binds a selector for a web element to the current scope with a default lookup timeout that can be overridden with the @Timeout annotation.
<element> can be located by <selector> "<expression>"
@Timeout annotation.Where
<element>is the web element name<selector>is the selector type, one of:idfor selecting by id attributenamefor selecting by name attributetag name(ortagsince v2.46.0) for selecting by tag namecss selector(orcsssince v2.46.0) for selecting by css expressionclass name(orclasssince v2.46.0) for selecting by class attributexpathfor selecting by XPathlink textfor selecting by link textpartial link textfor selecting by partial link textjavascript(orjssince 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
With explicit timeout since v3.73.0
Given @Timeout('10s') the todo field can be located by class "new-todo"
When I enter "Walk the dog" in the todo field
Without any timeout since v3.73.0
Given @Timeout('0s') 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>" at index <index>
Binds an indexed selector for a web element to the current scope with a default lookup timeout that can be overridden with the @Timeout annotation.
<element> can be located by <selector> "<expression>" at index <index>
@Timeout annotation.Where
<element>is the web element name<selector>is the selector type, one of:idfor selecting by id attributenamefor selecting by name attributetag name(ortagsince v2.46.0) for selecting by tag namecss selector(orcsssince v2.46.0) for selecting by css expressionclass name(orclasssince v2.46.0) for selecting by class attributexpathfor selecting by XPathlink textfor selecting by link textpartial link textfor selecting by partial link textjavascript(orjssince 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"
With explicit timeout since v3.73.0
Given @Timeout('12s') the first item can be located by css ".todo-list label" at index 0
Then the first item should contain "Walk the dog"
Without any timeout since v3.73.0
Given @Timeout('0s') 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> in <otherElement>
Binds an indexed selector for a web element (contained in another) to the current scope with a default lookup timeout that can be overridden with the @Timeout annotation.
<element> can be located by <selector> "<expression>" at index <index> in <otherElement>
@Timeout annotation.Where
<element>is the web element name<selector>is the selector type, one of:idfor selecting by id attributenamefor selecting by name attributetag name(ortagsince v2.46.0) for selecting by tag namecss selector(orcsssince v2.46.0) for selecting by css expressionclass name(orclasssince v2.46.0) for selecting by class attributexpathfor selecting by XPathlink textfor selecting by link textpartial link textfor selecting by partial link textjavascript(orjssince 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><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"
With explicit timeout since v3.73.0
Given @Timeout('20s') the count info can be located by class "todo-count"
And @Timeout('10s') the count unit can be located by tag "span" at index 1 in the count info
Then the count unit should contain "item"
Without any timeout since v3.73.0
Given @Timeout('0s') the count info can be located by class "todo-count"
And @Timeout('0s') 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 |
| <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 that can be overridden with the @Timeout annotation.
Lookups will be attempted in the order specified until one succeeds.
<element> can be located by
| selector | expression |
| <selector 1> | <expression 1> |
| <selector 2> | <expression 2> |
| .. | .. |
| <selector n> | <expression n> |
@Timeout annotation.
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:idfor selecting by id attributenamefor selecting by name attributetag name(ortagsince v2.46.0) for selecting by tag namecss selector(orcsssince v2.46.0) for selecting by css expressionclass name(orclasssince v2.46.0) for selecting by class attributexpathfor selecting by XPathlink textfor selecting by link textpartial link textfor selecting by partial link textjavascript(orjssince v2.46.0) for selecting by JavaScript
<expression n>is the nth selector expression
Example
Given the todo field can be located by
| selector | expression |
| name | todo-field |
| css | .todo input |
| class | new-todo |
When I type "Feed the cat" in the todo field
With explicit timeout since v3.73.0
Given @Timeout('8s') the todo field can be located by
| selector | expression |
| name | todo-field |
| css | .todo input |
| class | new-todo |
When I type "Feed the cat" in the todo field
Without any timeout since v3.73.0
Given @Timeout('0s') the todo field can be located by
| selector | expression |
| 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 | expression |
| <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 that can be overridden with the @Timeout annotation.
Lookups will be attempted in the order specified until one succeeds.
<element> can be located at index <index> by
| selector | expression |
| <selector 1> | <expression 1> |
| <selector 2> | <expression 2> |
| .. | .. |
| <selector n> | <expression n> |
@Timeout annotation.
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:idfor selecting by id attributenamefor selecting by name attributetag name(ortagsince v2.46.0) for selecting by tag namecss selector(orcsssince v2.46.0) for selecting by css expressionclass name(orclasssince v2.46.0) for selecting by class attributexpathfor selecting by XPathlink textfor selecting by link textpartial link textfor selecting by partial link textjavascript(orjssince 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
| selector | expression |
| name | todo-label |
| class | todo-label |
| css | .todo-list label |
Then the second item should contain "Feed the cat"
With explicit timeout since v3.73.0
Given @Timeout('9s') the second item can be located at index 1 by
| selector | expression |
| name | todo-label |
| class | todo-label |
| css | .todo-list label |
Then the second item should contain "Feed the cat"
Without any timeout since v3.73.0
Given @Timeout('0s') the second item can be located at index 1 by
| selector | expression |
| name | todo-label |
| class | todo-label |
| css | .todo-list label |
Then the second item should contain "Feed the cat"
Relative Locators
<element> can be located by <selector> "<expression>" <relativeTo> <otherElement>
Binds a selector for a web element (relative to another) to the current scope with a default lookup timeout that can be overridden with the @Timeout annotation.
<element> can be located by <selector> "<expression>" <relativeTo> <otherElement>
@Timeout annotation.Where
<element>is the web element name<selector>is the selector type, one of:idfor selecting by id attributenamefor selecting by name attributetag name(ortagsince v2.46.0) for selecting by tag namecss selector(orcsssince v2.46.0) for selecting by css expressionclass name(orclasssince v2.46.0) for selecting by class attributexpathfor selecting by XPathlink textfor selecting by link textpartial link textfor selecting by partial link textjavascript(orjssince v2.46.0) for selecting by JavaScript
<expression>is the selector expression<relativeTo>is one ofinto select element contained in<otherElement>Or since v3.0.0
aboveto select element above<otherElement>belowto select element below<otherElement>to left ofto select element to the left of<otherElement>to right ofto select element to the right of<otherElement>nearto select element near<otherElement>near and within <noOfPixels> pixel[s] ofto select element near and within a given number of pixels of<otherElement>- Where
<noOfPixels>is a postive integer denoting a number of pixels (max proximity to<otherElement>)
- Where
<otherElement>is the name of the web element that this one is relative to
Example
Given the button can be located by tag "button"
And the left field can be located by css "input" to left of the button
When I navigate to "https://chercher.tech/practice/relative-locators"
And I type "I am left of the button" in the left field
Then the left field should contain "I am left of the button"
Settings overrides
my <name> setting is "<value>"
Overrides a Gwen setting.
my <name> setting is "<value>"
Where
<name>is name of the setting to override<value>is the value to set
Notes
Or 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.
I reset my <name> setting
Capture
Text capture
I capture <textRef> as <name>
Captures the referenced text and binds it to the given name in the global scope.
I capture <textRef> as <name>
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 <element>
Captures the text value of an element and binds it to the element name in the global scode.
I capture <element>
I capture <element> as <name>
Captures the text value of an element and binds it to the given name in the global scope.
I capture <element> as <name>
I capture <name> <of|on|in> <element> by <javascript|js> "<script>"
Executes a JavaScript expression or function on an element and binds the result to the given name.
I capture <name> <of|on|in> <element> by <javascript|js> "<script>"
Where
<name>is the name to bind the javascript return value to<of|on|in>isof,onorin<element>is the name of the element to execute the javascript on<javascript|js>isjavascript(orjs, since v2.46.0)<script>is the javascript expression or function that will return the value (can be in DocString position)- The reference to the element will be provided to the javascript through an implicit object named
element. - For a one liner expression, no function, arrow declaration or
returnprefix is required For a function, use either:
- Arrow syntax (preferred):
() => { body }(Since v3.56.0) - Or anonymous function syntax (legacy):
(function(){ body })()
- Arrow syntax (preferred):
- The reference to the element will be provided to the javascript through an implicit object named
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
"""
() => {
var color = element.value
if (!element.checked) color = "Blue"
return color;
}
"""
Then my favorite color should be "Red"
Regex capture
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.
I capture the text in <textRef> by regex "<expression>" as <name>
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 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.
I capture the text in <element> by regex "<expression>" as <name>
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"
XPath capture
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.
I capture the <nodeType> in <xmlRef> by xpath "<expression>" as <name>
Where
<nodeType>is one of:textto capture the text nodenodeto capture a single nodenodesetto 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 <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.
I capture the <nodeType> in <element> by xpath "<expression>" as <name>
Where
<nodeType>is one of:textto capture the text nodenodeto capture a single nodenodesetto 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"
JSON capture
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.
I capture the content in <jsonRef> by json path "<expression>" as <name>
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"
Similarity capture
I capture the similarity score of <textRef> compared to "<text>" as <name>
Compares a text reference with a text value for similarity using the DSC (Dice Similarity Coefficient) algorithm and binds the calculated score to name in the global scope.
I capture the similarity score of <textRef> compared to "<text>" as <name>
name in the global scope.Where
<textRef>is the name of the binding containing a text reference- 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.
<text>is the text to compare<textRef>against<name>is the name to bind the calculated score to
Example
Given the phrase is "Hello world!"
When I capture the similarity score of the phrase compared to "Hello world" as similarity score 1
And I capture the similarity score of the phrase compared to "hello world" as similarity score 2
And @IgnoreCase I capture the similarity score of the phrase compared to "hello world" as similarity score 3
Then similarity score 1 should be "0.9411764705882353"
And similarity score 2 should be "0.8235294117647058"
And similarity score 3 should be "0.9411764705882353"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
I capture the similarity score of <textRef1> compared to <textRef2> as <name>
Compares a text reference with another for similarity using the DSC (Dice Similarity Coefficient) algorithm and binds the calculated score to name in the global scope.
I capture the similarity score of <textRef1> compared to <textRef2> as <name>
name in the global scope.Where
<textRef1>is the name of the binding containing a text reference- 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.
<textRef2>is the name of the binding containing the second text reference to compare <textRef1> against- 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 calculated score to
Example
Given phrase 1 is "Hello world!"
And phrase 2 is "hello world"
When I capture the similarity score of phrase 1 compared to phrase 2 as similarity score 1
And @IgnoreCase I capture the similarity score of phrase 1 compared to phrase 2 as similarity score 2
Then similarity score 1 should be "0.8235294117647058"
And similarity score 2 should be "0.9411764705882353"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
I capture the similarity score of <textRef> compared to "<text>"
Compares a text reference with a text value for similarity using the DSC (Dice Similarity Coefficient) algorithm and binds the calculated score to the similarity score attribute in the global scope.
I capture the similarity score of <textRef> compared to "<text>"
similarity score attribute in the global scope.Where
<textRef>is the name of the binding containing a text reference- 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.
<text>is the text to compare<textRef>against
Example
Given the phrase is "Hello world!"
When I capture the similarity score of the phrase compared to "Hello world"
Then similarity score should be "0.9411764705882353"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
I capture the similarity score of <textRef1> compared to <textRef2>
Compares a text reference with another for similarity using the DSC (Dice Similarity Coefficient) algorithm and binds the calculated score to the similarity score attribute in the global scope.
I capture the similarity score of <textRef1> compared to <textRef2>
similarity score attribute in the global scope.Where
<textRef1>is the name of the binding containing a text reference- 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.
<textRef2>is the name of the binding containing the second text reference to compare <textRef1> against- 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 phrase 1 is "Hello world!"
And phrase 2 is "hello world"
When I capture the similarity score of phrase 1 compared to phrase 2
Then similarity score should be "0.8235294117647058"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
PDF capture
I capture the PDF text from the current URL
Captures the text in a PDF document from the current URL in the browser and binds it to the PDF text variable in the global scope.
I capture the PDF text from the current URL
the PDF text variable in the global scope.I capture the PDF text from the current URL as <name>
Captures the text in a PDF document from the current URL in the browser and binds it to the given name in the global scope.
I capture the PDF text from the current URL as <name>
I capture the PDF text from url "<url>"
Captures the text in a PDF document from a given URL location and binds it to the PDF text variable in the global scope.
I capture the PDF text from url "<url>"
the PDF text variable in the global scope.I capture the PDF text from url "<url>" as <name>
Captures the text in a PDF document from a given URL location and binds it to the given name in the global scope.
I capture the PDF text from url "<url>" as <name>
I capture the PDF text from file "<filepath>"
Captures the text in a PDF document from a local file and binds it to the PDF text variable in the global scope.
I capture the PDF text from file "<filepath>"
the PDF text variable in the global scope.I capture the PDF text from file "<filepath>" as <name>
Captures the text in a PDF document from a local file and binds it to the given name in the global scope.
I capture the PDF text from file "<filepath>" as <name>
I capture the base64 encoded PDF text from <blobRef>
Captures the text in a PDF document from a base64 encoded BLOB and binds it to the PDF text variable in the global scope.
I capture the base64 encoded PDF text from <blobRef>
the PDF text variable in the global scope.Base64 capture
I base64 decode <textRef>
Base64 decodes the text reference and binds the result to the same name in the global scope.
I base64 decode <textRef>
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 text reference and binds the result to the give name in the global scope.
I base64 decode <textRef> as <name>
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"
I base64 decode <element>
Base64 decodes the text in the given element and binds the result to the same name in the global scope.
I base64 decode <element>
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.
I base64 decode <element> as <name>
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"
URL capture
I capture the current URL
Captures the current browser URL and binds it as the current URL in the global scope.
I capture the current URL
the current URL in the global scope.I capture the current URL as <name>
Captures the current browser URL and binds it to the given name in the global scope.
I capture the current URL as <name>
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.
I capture the text in the current URL by regex "<expression>" as <name>
Dropdown capture
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.
I capture <dropdown> <text|value>
Where
<dropdown>is the name of the dropdown element to capture the text or value of<dropdown>is one of:textto captured the displayed text of the selectionvalueto 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.
I capture <dropdown> <text|value> as <name>
Where
<dropdown>is the name of the dropdown element to capture the text or value of<dropdown>is one of:textto captured the displayed text of the selectionvalueto 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
Screenshot capture
I capture the current screenshot
Captures the current screenshot and attaches it to the Gwen report.
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.
I capture the current screenshot as <name>
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/dist"
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"
Element capture
I capture element screenshot of <element>
Captures the screenshot of a web element and attaches it to the Gwen report.
I capture element screenshot of <element>
Where
<element>the name of the web element to capture the screenshot of
Example
Given the todo field can be located by class "new-todo"
When I navigate to "https://todomvc.com/examples/react/dist"
And I type "Walk the dog" in the todo field
And I capture element screenshot of the todo field
I capture element screenshot of <element> as <name>
Captures the screenshot of a web element, attaches it to the Gwen report, and binds the filepath of the saved image to the given name in the global scope.
I capture element screenshot of <element> as <name>
Where
<element>the name of the web element to capture the screenshot of<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/dist"
And I type "Walk the dog" in the todo field
And I capture element screenshot of the todo field as my element screenshot
Data lookups
I lookup <name> in the "<filepath>" file where "<predicate>"
Looks up a named data value in a CSV or JSON file based on a predicate function and binds its value to the same name in the global scope.
I lookup <name> in the "<filepath>" file where "<predicate>"
Where
<name>the name of the data to look up the value of and the name to bind it to<filepath>the path to the CSV or JSON file to look up<predicate>is the javascript predicate expression that will returntruewhen a match is found for a record orfalseotherwise (can be in DocString position) Data fields can be referenced in the predicate using either:${data.record.NAME}(since v3.47.0)${csv.record.NAME}for CSV data or${json.record.NAME}for JSON data (for prior versions)
The data value contained in the first record that satisifes the given predicate will be bound to the global scope. Otherwise if no records match, then no value will be bound.
Examples
CSV Lookup
Given the CSV file: lookup/StateCodes.csv
Code,Name
ACT,Australian Capital Territory
NSW,New South Wales
NT,Northern Territory
QLD,Queensland
SA,South Australia
TAS,Tasmania
VIC,Victoria
WA,Western Australia
The following will bind "Western Australia" in the last record to Name in the global scope
When I lookup Name in the "lookup/StateCodes.csv" file where "'${data.record.Code}' == 'WA'"
Then Name should be "Western Australia"
JSON Lookup
Since v3.47.0
Given the JSON file: lookup/StateCodes.json
[
{ "Code": "ACT", "Name": "Australian Capital Territory" },
{ "Code": "NSW", "Name": "New South Wales" },
{ "Code": "NT", "Name": "Northern Territory" },
{ "Code": "QLD", "Name": "Queensland" },
{ "Code": "SA", "Name": "South Australia" },
{ "Code": "TAS", "Name": "Tasmania" },
{ "Code": "VIC", "Name": "Victoria" },
{ "Code": "WA", "Name": "Western Australia" }
]
The following will bind "Western Australia" in the last record to Name in the global scope
When I lookup Name in the "lookup/StateCodes.json" file where "'${data.record.Code}' == 'WA'"
Then Name should be "Western Australia"
I lookup <name> in <filepathRef file> where "<predicate>"
Looks up a named data value in a referenced CSV or JSON file based on a predicate function and binds its value to the same name in the global scope.
I lookup <name> in <filepathRef file> where "<predicate>"
Where
<name>the name of the data to look up the value of and the name to bind it to<filepathRef file>is the name of the binding containing the path of the CSV or JSON file to look up<predicate>is the javascript predicate expression that will returntruewhen a match is found for a record orfalseotherwise (can be in DocString position) Data fields can be referenced in the predicate using either:${data.record.NAME}(since v3.47.0)${csv.record.NAME}for CSV data or${json.record.NAME}for JSON data (for prior versions)
The data value contained in the first record that satisifes the given predicate will be bound to the global scope. Otherwise if no records match, then no value will be bound.
Examples
CSV Lookup
Given the CSV file: lookup/StateCodes.csv
Code,Name
ACT,Australian Capital Territory
NSW,New South Wales
NT,Northern Territory
QLD,Queensland
SA,South Australia
TAS,Tasmania
VIC,Victoria
WA,Western Australia
The following will bind "QLD" in the 4th record to Code in the global scope
Given mapping file is "lookup/StateCodes.csv"
When I lookup Code in mapping file where "'${data.record.Name}' == 'Queensland'"
Then Code should be "QLD"
JSON Lookup
Since v3.47.0
Given the JSON file: lookup/StateCodes.json
[
{ "Code": "ACT", "Name": "Australian Capital Territory" },
{ "Code": "NSW", "Name": "New South Wales" },
{ "Code": "NT", "Name": "Northern Territory" },
{ "Code": "QLD", "Name": "Queensland" },
{ "Code": "SA", "Name": "South Australia" },
{ "Code": "TAS", "Name": "Tasmania" },
{ "Code": "VIC", "Name": "Victoria" },
{ "Code": "WA", "Name": "Western Australia" }
]
The following will bind "QLD" in the 4th record to Code in the global scope
Given mapping file is "lookup/StateCodes.json"
When I lookup Code in mapping file where "'${data.record.Name}' == 'Queensland'"
Then Code should be "QLD"
I lookup <dataName> in the "<filepath>" file as <name> where "<predicate>"
Looks up a named data value in a CSV or JSON file based on a predicate function and binds its value to a given name in the global scope.
I lookup <dataName> in the "<filepath>" file as <name> where "<predicate>"
Where
<dataName>the name of the data to look up the value of<filepath>the path to the CSV or JSON file to look up<name>the name to bind the looked up value to in the global scope<predicate>is the javascript predicate expression that will returntruewhen a match is found for a record orfalseotherwise (can be in DocString position) Data fields can be referenced in the predicate using either:${data.record.NAME}(since v3.47.0)${csv.record.NAME}for CSV data or${json.record.NAME}for JSON data (for prior versions)
The data value contained in the first record that satisifes the given predicate will be bound to the global scope. Otherwise if no records match, then no value will be bound.
Examples
CSV Lookup
Given the CSV file: lookup/StateCodes.csv
Code,Name
ACT,Australian Capital Territory
NSW,New South Wales
NT,Northern Territory
QLD,Queensland
SA,South Australia
TAS,Tasmania
VIC,Victoria
WA,Western Australia
The following will bind "New South Wales" in the 2nd record to state name in the global scope
When I lookup Name in the "lookup/StateCodes.csv" file as state name where "'${data.record.Code}' == 'NSW'"
Then state name should be "New South Wales"
JSON Lookup
Since v3.47.0
Given the JSON file: lookup/StateCodes.json
[
{ "Code": "ACT", "Name": "Australian Capital Territory" },
{ "Code": "NSW", "Name": "New South Wales" },
{ "Code": "NT", "Name": "Northern Territory" },
{ "Code": "QLD", "Name": "Queensland" },
{ "Code": "SA", "Name": "South Australia" },
{ "Code": "TAS", "Name": "Tasmania" },
{ "Code": "VIC", "Name": "Victoria" },
{ "Code": "WA", "Name": "Western Australia" }
]
The following will bind "New South Wales" in the 2nd record to state name in the global scope
When I lookup Name in the "lookup/StateCodes.json" file as state name where "'${data.record.Code}' == 'NSW'"
Then state name should be "New South Wales"
I lookup <dataName> in <filepathRef file> as <name> where "<predicate>"
Looks up a named column value in a referenced CSV or JSON file based on a predicate function and binds its value to a given name in the global scope.
I lookup <dataName> in <filepathRef file> as <name> where "<predicate>"
Where
<dataName>the name of the data in the CSV or JSON file to look up the value of<filepathRef file>is the name of the binding containing the path of the CSV or JSON file to look up<name>the name to bind the looked up value to in the global scope<predicate>is the javascript predicate expression that will returntruewhen a match is found for a record orfalseotherwise (can be in DocString position) Data fields can be referenced in the predicate using either:${data.record.NAME}(since v3.47.0)${csv.record.NAME}for CSV data or${json.record.NAME}for JSON data (for prior versions)
The data value contained in the first record that satisifes the given predicate will be bound to the global scope. Otherwise if no records match, then no value will be bound.
Examples
CSV Lookup
Given the CSV file: lookup/StateCodes.csv
Code,Name
ACT,Australian Capital Territory
NSW,New South Wales
NT,Northern Territory
QLD,Queensland
SA,South Australia
TAS,Tasmania
VIC,Victoria
WA,Western Australia
The following will bind "VIC" in the 7th record to state code in the global scope
Given mapping file is "lookup/StateCodes.csv"
When I lookup Code in mapping file as state code where "'${data.record.Name}' == 'Victoria'"
Then state code should be "VIC"
JSON Lookup
Since v3.47.0
Given the JSON file: lookup/StateCodes.json
[
{ "Code": "ACT", "Name": "Australian Capital Territory" },
{ "Code": "NSW", "Name": "New South Wales" },
{ "Code": "NT", "Name": "Northern Territory" },
{ "Code": "QLD", "Name": "Queensland" },
{ "Code": "SA", "Name": "South Australia" },
{ "Code": "TAS", "Name": "Tasmania" },
{ "Code": "VIC", "Name": "Victoria" },
{ "Code": "WA", "Name": "Western Australia" }
]
The following will bind "VIC" in the 7th record to state code in the global scope
Given mapping file is "lookup/StateCodes.json"
When I lookup Code in mapping file as state code where "'${data.record.Name}' == 'Victoria'"
Then state code should be "VIC"
Actions
Page actions
I refresh the current page
Refreshes the current page in the browser.
I refresh the current page
Element actions
I <click|right click|double click> <element>
Clicks a web element.
I <click|right click|double click> <element>
Where
<click|right click|double click>is one of:<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.
I <click|right click|double click> <element> of <context>
Where
<click|right click|double click>is one of:<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.
I <modifierKeys> <click|right click|double click> <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:clickto click the elementright clickto right click the elementdouble clickto 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.
I <check|uncheck|tick|untick> <checkbox>
Where
<check|uncheck|tick|untick>is one of:<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 move to <element>
Moves to a web element and gives it the focus.
I move to <element>
I <enter|type> "<text>" in <element>
Enters or types text into a web element.
I <enter|type> "<text>" in <element>
Where
<enter|type>is one of:enterto send the text to the field followed by the enter keytypeto 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/dist"
And I enter "Walk the dog" in the todo field
I <enter|type> <textRef> in <element>
Enters or types a text reference value into a web element.
I <enter|type> <textRef> in <element>
Where
<enter|type>is one of:enterto send the text to the field followed by the enter keytypeto 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/dist"
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.
I append "<text>" to <element>
I append <textRef> to <element>
Appends the given referenced text to the current text value of an element.
I append <textRef> to <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.
I press <enter|tab> in <element>
Where
<enter|tab>is one of:enterto send the enter keytabto 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).
I send "<keys>" to <element>
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 "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.
I insert a new line in <textarea>
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.
I clear <element>
Dropdown actions
I <select|deselect> the <position><st|nd|rd|th> option in <dropdown>
Selects an option in a dropdown by position.
I <select|deselect> the <position><st|nd|rd|th> option in <dropdown>
Where
<select|deselect>is one of:selectto select the optiondeselectto 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:stif the position number ends in 1ndif the position number ends in 2rdif the position number ends in 3thif 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.
I <select|deselect> "<option>" in <dropdown>
Where
<select|deselect>is one of:selectto select the optiondeselectto 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.
I <select|deselect> <optionRef> in <dropdown>
Where
<select|deselect>is one of:selectto select the optiondeselectto 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.
I <select|deselect> "<option>" in <dropdown> by value
Where
<select|deselect>is one of:selectto select the optiondeselectto 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.
I <select|deselect> <optionRef> in <dropdown> by value
Where
<select|deselect>is one of:selectto select the optiondeselectto 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
Form actions
I submit <form>
Submits a web form.
I submit <form>
Window and tab actions
I have an open browser
Opens a browser if none are open
I have an open browser
I have no open browser
Closes all open browsers
I have no open browser
I start a new browser
Starts a new browser session (or switches to exising one if it is already open).
I start a new browser
I close the[ current] browser
Closes the current browser session (or does nothing if one is not open).
I close the[ current] browser
I start a browser for <name>
Starts a new browser session with the given name (closes any existing browser of that name first).
I start a browser for <name>
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.
I switch to <name>
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/dist"
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).
I close the browser for <name>
I start a new browser <tab|window>
Starts a new browser tab or window (or starts a new browser session if one is not open).
I start a new browser <tab|window>
I switch to <tab|window> <occurrence>
Switches to a previously opened tab or window occurrence.
I switch to <tab|window> <occurrence>
Where
<tab|window>is eithertaborwindow<occurrence>is the tab or window occurrence to switch to (1st opened is occurrence 1, 2nd is 2, ..)- Note: the occurrence number of the default tab/window in a new browser session is 0
Example
When I navigate to "https://google.com"
And I start a new browser tab
And I navigate to "https://todomvc.com/examples/react/dist"
And I switch to window 1
Then the page title should contain "Google"
I close <tab|window> <occurrence>
Closes a previously opened tab or window occurrence.
I close <tab|window> <occurrence>
Where
<tab|window>is eithertaborwindow<occurrence>is the tab or window occurrence to close to (1st opened is occurrence 1, 2nd is 2, ..)- Note: you cannot close the default tab/window opened by starting a new browser session with this DSL. Use
I close the[ current] browserinstead in that case.
- Note: you cannot close the default tab/window opened by starting a new browser session with this DSL. Use
Example
When I navigate to "https://google.com"
And I start a new browser tab
And I navigate to "https://todomvc.com/examples/react/dist"
And I close tab 1
Then the page title should contain "Google"
If used in conjunction with @Try, will switch to the parent window regardless of whether or not a tab or window was closed (since 3.12.4).
I switch to the child <tab|window>
Switches to the most recently opened child tab or window (without closing the parent window)
I switch to the child <tab|window>
I close the child <tab|window>
Closes the currently active child tab or window and passes control back to the parent window.
I close the child <tab|window>
Where
<tab|window>is eithertaborwindow
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
If used in conjunction with @Try, will switch to the parent window regardless of whether or not a child window was closed (since 3.12.4).
I switch to child <tab|window> <occurrence>
Switches to a child tab or window occurrence (without closing the parent window).
I switch to child <tab|window> <occurrence>
Where
<tab|window>is eithertaborwindow<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.
I close child <tab|window> <occurrence>
Where
<tab|window>is eithertaborwindow<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
If used in conjunction with @Try, will switch to the parent window regardless of whether or not a child window was closed (since 3.12.4).
I switch to the <parent|root> <tab|window>
Switches to the parent window (without closing the currently active child window).
I switch to the <parent|root> <tab|window>
Where
<parent|root>is eitherparent(orrootsince v2.49.0)<tab|window>is eithertaborwindow
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.
I <maximize|maximise> the window
I resize the window to width <w> and height <h>
Resizes the currently active browser window to the given dimensions.
I resize the window to width <w> and height <h>
I send "<keys>"
Sends a sequence of keys to the browser (for emulating keyboard shortcuts).
I send "<keys>"
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"
I set the window position to x <x> and y <y>
Positions the currently active browser window to the given co-ordinates.
I set the window position to x <x> and y <y>
I send "<keys>"
Sends a sequence of keys to the browser (for emulating keyboard shortcuts).
I send "<keys>"
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"
Frame actions
I switch to the default content
Switches to either the first frame on the page, or the main document when a page contains iframes.
I switch to the default content
I switch to <frame> content
Switches the context to a frame.
I switch to <frame> content
Alert and Popup actions
I accept the <alert|confirmation> popup
Accepts and closes an alert or confirmation popup by clicking OK.
I accept the <alert|confirmation> popup
Where
<alert|confirmation>is either:alertfor an alert box with an OK buttonconfirmationfor 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.
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.
I capture the <alert|confirmation> popup message
the <alert|confirmation> popup message in the global scope.Where
<alert|confirmation>is either:alertfor an alert box with an OK buttonconfirmationfor 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.
I capture the <alert|confirmation> popup message as <name>
Where
<alert|confirmation>is either:alertfor an alert box with an OK buttonconfirmationfor 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
Scroll actions
I scroll to the <top|bottom> of the page
Scrolls to the top or bottom of the current page.
I scroll to the <top|bottom> of the page
I scroll to the <top|bottom> of <element>
Scrolls to the top or bottom of the given element.
I scroll to the <top|bottom> of <element>
Where
<top|bottom>is one of:topto scroll to the top of the elementbottomto 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
Drag Drop actions
I drag and drop <sourceElement> to <targetElement>
Drags and drops a source element onto a target element.
I drag and drop <sourceElement> to <targetElement>
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}"
JS actions
<element> can be <actioned> by <javascript|js> "<script>"
Registers a javascript action on an element. When the action is performed, then the javascript will execute in place of the default behaviour.
<element> can be <actioned> by <javascript|js> "<script>"
Where
<element>is the name of the element to register the action on<actioned>is one of:clickedto perform the action when the element is clickedright clickedto perform the action when the element is right clicked, since v2.8.0double clickedto perform the action when the element is double clicked, since v2.12.0submittedto perform the action when the form element is submittedchecked(ortickedsince v2.4.0) to perform the action when the checkbox element is tickedunchecked(oruntickedsince v2.4.0) to perform the action when the checkbox element is untickedselectedto perform the action when a dropdown option is selected in the elementdeselectedto perform the action when a mutli-select dropdown option is deselected in the element, since v2.13.0typedto perform the action when text is typed into the elemententeredto perform the action when text is entered into the elementtabbedto perform the action when the tab key is pressed in the element, since v2.17.1clearedto perform the action when the text is cleared in the elementmoved toto perform the action when the focus is moved to the element
<javascript|js>isjavascript(orjs, since v2.46.0)<script>is the javascript expression or function that will perform the action (can be in DocString position)- The reference to the element will be provided to the javascript through an implicit object named
element. - For a one liner expression, no function, arrow declaration or
returnprefix is required For a function, use either:
- Arrow syntax (preferred):
() => { body }(Since v3.56.0) - Or anonymous function syntax (legacy):
(function(){ body })()
- Arrow syntax (preferred):
- The reference to the element will be provided to the javascript through an implicit object named
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
Download actions
I download "<url>" to "<filepath>"
Downloads a resource from a URL to a file.
I download "<url>" to "<filepath>"
I download "<url>" to <filepathRef file>
Downloads a resource from a URL to a referenced file.
I download "<url>" to <filepathRef file>
I download the current URL to "<filepath>"
Downloads the resource at the current URL to a file.
I download the current URL to "<filepath>"
I download the current URL to <filepathRef file>
Downloads a resource at the current URL to a referenced file.
I download the current URL to <filepathRef file>
File actions
I attach "<filepath>" as "<name>"
or since v3.0.0
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.
I attach "<filepath>" as "<name>"
I attach "<filepath>" as <name>
I attach "<filepath>"
Attaches a local file to the Gwen report and assigns it the same name as the file.
I attach "<filepath>"
I <write|append> "<text>" to "<filepath>" file
Writes or appends text to a file.
I <write|append> "<text>" to "<filepath>" file
Where
<write|append>is one of:<write>to overwrite entire content of file with the provided text<append>to append the provided text to existing content in file
<text>the text to write or append to the file<filepath>the path to the local file to write or append the text to
Example
When I write "automation" to "path/to/file.txt" file
I <write|append> <textRef> to "<filepath>" file
Writes or appends a text reference value to a file.
I <write|append> <textRef> to "<filepath>" file
Where
<write|append>is one of:<write>to overwrite entire content of file with the provided text<append>to append the provided text to existing content in file
<textRef>is the name of the binding containing the text to write or append to the file- 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.
<filepath>the path to the local file to write or append the text to
Example
Given my content is
"""
Automation and robotics
for Gherkin
"""
When I write my content to "path/to/file.txt" file
I <write|append> new line to "<filepath>" file
Writes or appends a new line to a file.
I <write|append> new line to "<filepath>" file
I <write|append> "<text>" to <filepathRef file>
Writes or appends text to a referenced file.
I <write|append> "<text>" to <filepathRef file>
Where
<write|append>is one of:<write>to overwrite entire content of file with the provided text<append>to append the provided text to existing content in file
<text>the text to write or append to the file<filepathRef file>is the name of the binding containing the path of the file to write or append the provided text to
Example
Given my file is "path/to/file.txt"
When I append "automation" to my file
I <write|append> <textRef> to <filepathRef file>
Writes or appends a text reference value to a referenced file.
I <write|append> <textRef> to <filepathRef file>
Where
<write|append>is one of:<write>to overwrite entire content of file with the provided text<append>to append the provided text to existing content in file
<textRef>is the name of the binding containing the text to write or append to the file- 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.
<filepathRef file>is the name of the binding containing the path of the file to write or append the provided text to
Example
Given my file is "path/to/file.txt"
And my content is
"""
Automation and robotics
for Gherkin
"""
When I write my content to my file
I <write|append> new line to <filepathRef file>
Writes or appends a new line to a referenced file.
I <write|append> new line to <filepathRef file>
Where
<write|append>is one of:<write>to overwrite entire content of file with a new line<append>to append a new line to existing content in file
<filepathRef file>is the name of the binding containing the path of the file to write or append the new line to
Example
Given my file is "path/to/file.txt"
When I append new line to my file
I log record to <resultsFileId> file
Logs a record to the results file having the given ID (if results is specifed in the format launch option only).
I log record to <resultsFileId> file
Where
<resultsFileId>the ID of the results file to log a record to
Example
When I log record to my.results file
Sleeps and waits
I wait for <element>
Waits for an element to appear on a page for a default number of seconds before timing out. The default timeout period is equal to the configured gwen.web.wait.seconds setting value. The default timeout can be overridden using the @Timeout annotation.
I wait for <element>
@Timeout annotation.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.
I wait for <element> text
I wait until <element> is[ not] <state>
Waits for an element to transition to a given state. The default timeout period is equal to the configured gwen.web.wait.seconds setting value. The default timeout can be overridden using the @Timeout annotation.
I wait until <element> is[ not] <state>
@Timeout annotation.Where
<element>is the name of the element to wait fornotnegates the state if included<state>is one of:displayedto wait until the element is displayedhiddento wait until the element is not displayedchecked(ortickedsince v2.4.0) to wait until a checkbox is tickedunchecked(oruntickedsince v2.4.0) to wait until a checkbox is not tickedenabledto wait until the element is enableddisabledto 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/dist"
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 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. The default timeout can be overridden using the @Timeout annotation.
I wait until "<javascript>"
gwen.web.wait.seconds setting value. The default timeout can be overridden using the @Timeout annotation.Where
<javascript>is the javascript expression or function that will return a boolean value (can be in DocString position)- For a one liner expression, no function, arrow declaration or
returnprefix is required For a function, use either:
- Arrow syntax (preferred):
() => { body }(Since v3.56.0) - Or anonymous function syntax (legacy):
(function(){ body })()
- Arrow syntax (preferred):
- For a one liner expression, no function, arrow declaration or
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 "<filepath>" file[ not] exists
Waits until a file exists (or not). The default timeout period is equal to the configured gwen.web.wait.seconds setting value. The default timeout can be overridden using the @Timeout annotation.
I wait until "<filepath>" file[ not] exists
I wait until "<filepath>" file does not exist
Waits until a file does not exist. The default timeout period is equal to the configured gwen.web.wait.seconds setting value. The default timeout can be overridden using the @Timeout annotation.
I wait until "<filepath>" file does not exist
I wait until <filepathRef file>[ not] exists
Waits until a file exists (or not). The default timeout period is equal to the configured gwen.web.wait.seconds setting value. The default timeout can be overridden using the @Timeout annotation.
I wait until <filepathRef file>[ not] exists
I wait until <filepathRef file> does not exist
Waits until a file does not exist. The default timeout period is equal to the configured gwen.web.wait.seconds setting value. The default timeout can be overridden using the @Timeout annotation.
I wait until <filepathRef file> does not exist
I wait until "<filepath>" file is[ not] empty
Waits until a file is empty. The default timeout period is equal to the configured gwen.web.wait.seconds setting value. The default timeout can be overridden using the @Timeout annotation.
I wait until "<filepath>" file is[ not] empty
I wait until <filepathRef file> is[ not] empty
Waits until a file is empty. The default timeout period is equal to the configured gwen.web.wait.seconds setting value. The default timeout can be overridden using the @Timeout annotation.
I wait until <filepathRef file> is[ not] empty
I wait until <condition>
Waits until a condition is satisfied. The default timeout period is equal to the configured gwen.web.wait.seconds setting value. The default timeout can be overridden using the @Timeout annotation.
I wait until <condition>
@Timeout annotation.Where
<condition>is either:Since v3.54.0
- the name of any binding that will return
truewhen the condition is satisfied orfalsewhen it is not
- the name of any binding that will return
Or in prior versions
- the name of a binding containing a javascript function or expression that will return
truewhen the condition is satisfied orfalsewhen it is not - the name of a binding containing a
trueorfalsevalue literal, since v3.50.0
- the name of a binding containing a javascript function or expression that will return
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 <duration> second[s]
Sleeps for the given number of seconds.
I wait <duration> second[s]
JS execution
I execute <javascript|js> "<script>"
Executes a JavaScript expression or function.
I execute <javascript|js> "<script>"
Where
<javascript|js>isjavascript(orjssince v2.46.0)<script>is the javascript expression or function to execute (can be in DocString position)- For a one liner expression, no function, arrow declaration or
returnprefix is required For a function, use either:
- Arrow syntax (preferred):
() => { body }(Since v3.56.0) - Or anonymous function syntax (legacy):
(function(){ body })()
- Arrow syntax (preferred):
- For a one liner expression, no function, arrow declaration or
Example
When I execute js "alert('Hello Gwen World')"
System process execution
I execute system process "<expression>"
Executes a local system process or script.
I execute system process "<expression>"
I execute system process "<expression>" delimited by "<delimiters>"
Executes a delimited local system process or script.
I execute system process "<expression>" delimited by "<delimiters>"
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>"
or since v3.14.2
I execute unix system process "<expression>"
Executes a local unix system process or shell script.
I execute a unix system process "<expression>"
I execute unix system process "<expression>"
I execute unix system process "<expression>" delimited by "<delimiters>"
Executes a delimited local unix system process or script.
I execute unix system process "<expression>" delimited by "<delimiters>"
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 execution
<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.
<name> is defined in the <dbName> database by sql "<selectStmt>"
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_CLASSPATHenvironment variable must be set to include a path to the JDBC driver JAR - A
gwen.db.<dbName>.driversetting must be set to the name of the JDBC driver implementation class - A
gwen.db.<dbName>.urlsetting must be set to the JDBC URL of the database
Optionally accepts the @Eager, @Lazy or @Masked annotations.
@Eagerimmediately evaluates the<expression>and binds the result to<name>@Lazyevaluates the<expression>and binds the result to<name>when it is first referenced- In the absence of either of the above annotations,
<expression>is evaluated every time<name>is referenced @Maskedmasks the captured value to prevent it from being logged as clear text
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"
- Linux
- Windows
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
Set GWEN_CLASSPATH variable in the environment to include the JDBC driver JAR
set GWEN_CLASSPATH c:/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.Driver
gwen.db.feedback.url = jdbc:mysql://localhost/feedback?user=myUser&password=myPassword&
I update the <dbName> database by sql "<updateStmt>"
Executes an SQL udpate statement on a configured database.
I update the <dbName> database by sql "<updateStmt>"
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_CLASSPATHenvironment variable must be set to include a path to the JDBC driver JAR - A
gwen.db.<dbName>.driversetting must be set to the name of the JDBC driver implementation class - A
gwen.db.<dbName>.urlsetting 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"
- Linux
- Windows
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
Set GWEN_CLASSPATH variable in the environment to include the JDBC driver JAR
set GWEN_CLASSPATH c:/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.Driver
gwen.db.feedback.url = jdbc:mysql://localhost/feedback?user=myUser&password=myPassword&
Assertions
Text asserts
<textRef> should[ not] be <blank|empty>
Checks whether or not the text reference matches a blank or empty string. Reports an assertion error if the match fails.
<textRef> should[ not] be <blank|empty>
With custom assertion error message (as of v3.9.0):
<textRef> should[ not] be <blank|empty> @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <textRef> should[ not] be blank
With custom timeout (as of v3.73.0):
@Timeout('10s') <textRef> should[ not] be blank
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.
notnegates the match if included<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
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/dist"
And I enter "Get the milk" in the todo field
And I capture my todo list as current items
Then current items should not be empty
Trimming (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing
<textRef> should[ not] <match> "<expression>"
Checks whether or not the text reference matches a given expression. Reports an assertion error if the match fails.
<textRef> should[ not] <match> "<expression>"
With custom assertion error message (as of v3.9.0):
<textRef> should[ not] <match> "<expression>" @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <textRef> should[ not] <match> "<expression>"
With custom timeout (as of v3.73.0):
@Timeout('10s') <textRef> should[ not] <match> "<expression>"
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.
notnegates the match if included<match>is the type of match to perform, one of:befor exact matchcontainfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatch regexfor regex matchmatch xpathfor XML matchmatch json pathfor JSON match, since v1.4.0match templatefor template match, since v2.16.0match template filefor template file match, since v2.16.0
<expression>is the expression to match (can be in DocString position)<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
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/dist"
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"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
<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.
<textRef> should[ not] <match> <expressionRef>
With custom assertion error message (as of v3.9.0):
<textRef> should[ not] <match> <expressionRef> @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <textRef> should[ not] <match> <expressionRef>
With custom timeout (as of v3.73.0):
@Timeout('10s') <textRef> should[ not] <match> <expressionRef>
Where
<variable>is the name of the variable or setting to checknotnegates the match if included<match>is the type of match to perform, one of:befor exact matchcontainfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatch regexfor regex matchmatch xpathfor XML matchmatch json pathfor JSON match, since v1.4.0match templatefor template match, since v2.16.0match template filefor 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.
<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
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/dist"
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
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
<textRef> should[ not] <match> <percentage>% similar to "<text>"
Compares a text reference with a text value for similarity using the DSC (Dice Similarity Coefficient) algorithm.
<textRef> should[ not] <match> <percentage>% similar to "<text>"
With custom assertion error message (as of v3.9.0):
<textRef> should[ not] <match> <percentage>% similar to "<text>" @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <textRef> should[ not] <match> <percentage>% similar to "<text>"
With custom timeout (as of v3.73.0):
@Timeout('10s') <textRef> should[ not] <match> <percentage>% similar to "<text>"
Where
<textRef>is the name of the binding containing a text reference- 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.
notnegates the match if includedmatchis one of:befor exact matchbe less thanfor less than matchbe at mostfor less than or equal to matchbe more thanfor greater than matchbe at leastfor greater than or equal to match
<text>is the text to compare<textRef>against<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
The calculated similarity score is implicity bound to the similarity score attribute in the global scope.
Examples
Given the phrase is "Hello world!"
Then the phrase should be more than 90% similar to "Hello world"
And @IgnoreCase the phrase should be at least 90% similar to "hello world"
And the phrase should be 94.12% similar to "Hello world"
And @IgnoreCase the phrase should be 94.12% similar to "hello world"
And the phrase should be 82.35% similar to "hello world"
And the phrase should not be less than 90% similar to "Hello world"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
<textRef1> should[ not] <match> <percentage>% similar to <textRef2>
Compares a text reference with another for similarity using the DSC (Dice Similarity Coefficient) algorithm.
<textRef1> should[ not] <match> <percentage>% similar to <textRef2>
With custom assertion error message (as of v3.9.0):
<textRef1> should[ not] <match> <percentage>% similar to <textRef2> @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <textRef1> should[ not] <match> <percentage>% similar to <textRef2>
With custom timeout (as of v3.73.0):
@Timeout('10s') <textRef1> should[ not] <match> <percentage>% similar to <textRef2>
Where
<textRef1>is the name of the binding containing the first text reference- 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.
notnegates the match if includedmatchis one of:befor exact matchbe less thanfor less than matchbe at mostfor less than or equal to matchbe more thanfor greater than matchbe at leastfor greater than or equal to match
<percentage>is a percentage number between 0 and 100 (internally rounded to 2 decimal places)<textRef2>is the name of the binding containing the second text reference to compare<textRef1>against- 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.
<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
The calculated similarity score is implicity bound to the similarity score attribute in the global scope.
Examples
Given phrase 1 is "Hello world!"
And phrase 2 is "Hello world"
And phrase 3 is "hello world"
Then phrase 1 should be more than 90% similar to phrase 2
And @IgnoreCase phrase 1 should be at least 90% similar to phrase 2
And phrase 1 should be 94.12% similar to phrase 2
And @IgnoreCase phrase 1 should be 94.12% similar to phrase 3
And phrase 1 should be 82.35% similar to phrase 3
And phrase 1 should not be less than 90% similar to phrase 2
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
File asserts
"<filepath>" file should[ not] exist
Assers that a file should exist (or not).
"<filepath>" file should[ not] exist
<filepathRef file> should[ not] exist
Assers that a file should exist (or not).
<filepathRef file> should[ not] exist
Where
<filepathRef file>is the name of the binding containing the path of the file to checknotto check that the file does not exist (negation)
Example
Given my existing file is "path/to/existing.txt"
And my missing file is "path/to/missing.txt"
Then my existing file should exist
Then my missing file should not exist
"<filepath>" file should[ not] be empty
Assers that a file should be empty (or not).
"<filepath>" file should[ not] be empty
<filepathRef file> should[ not] be empty
Assers that a file should be empty (or not).
<filepathRef file> should[ not] be empty
Where
<filepathRef file>is the name of the binding containing the path of the file to checknotto check that the file is not empty (negation)
Example
Given my empty file is "path/to/empty.txt"
And my populated file is "path/to/populated.txt"
Then my empty file should be empty
Then my populated file should not be empty
XML asserts
<xmlRef> at xpath "<path>" should[ not] be <blank|empty>
Extracts text from the referenced XML value using the given XPath and checks whether or not it matches a blank or empty string. Reports an assertion error if the match fails.
<xmlRef> at xpath "<path>" should[ not] be <blank|empty>
With custom assertion error message (as of v3.9.0):
<xmlRef> at xpath "<path>" should[ not] be blank @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <xmlRef> at xpath "<path>" should[ not] be blank
With custom timeout (as of v3.73.0):
@Timeout('10s') <xmlRef> at xpath "<path>" should[ not] be blank
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.
pathis the XPath selector expressionnotnegates the match if included<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
Example
Given the xml is "<result><status>passed</status></result>"
Then the xml at xpath "//result/status" should not be blank
Trimming (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing
<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.
<xmlRef> at xpath "<path>" should[ not] <match> "<expression>"
With custom assertion error message (as of v3.9.0):
<xmlRef> at xpath "<path>" should[ not] <match> "<expression>" @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <xmlRef> at xpath "<path>" should[ not] <match> "<expression>"
With custom timeout (as of v3.73.0):
@Timeout('10s') <xmlRef> at xpath "<path>" should[ not] <match> "<expression>"
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.
pathis the XPath selector expressionnotnegates the match if included<match>is the type of match to perform, one of:befor exact matchcontainfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatch regexfor regex matchmatch xpathfor XML matchmatch json pathfor JSON match, since v1.4.0match templatefor template match, since v2.16.0match template filefor template file match, since v2.16.0
<expression>is the expression to match<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
Example
Given the xml is "<result><status>passed</status></result>"
Then the xml at xpath "//result/status" should be "passed"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
JSON asserts
<jsonRef> at json path "<path>" should[ not] be <blank|empty>
Extracts text from the referenced JSON value using the given JSON path and checks whether or not it matches a blank or empty string. Reports an assertion error if the match fails.
<jsonRef> at json path "<path>" should[ not] be <blank|empty>
With custom assertion error message (as of v3.9.0):
<jsonRef> at json path "<path>" should[ not] be blank @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <jsonRef> at json path "<path>" should[ not] be blank
With custom timeout (as of v3.73.0):
@Timeout('10s') <jsonRef> at json path "<path>" should[ not] be blank
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.
pathis the JSON path selector expressionnotnegates the match if included<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
Example
Given the json is "{ "status": "passed" }"
Then the json at json path "$.status" should not be blank
Trimming (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing
<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.
<jsonRef> at json path "<path>" should[ not] <match> "<expression>"
With custom assertion error message (as of v3.9.0):
<jsonRef> at json path "<path>" should[ not] <match> "<expression>" @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <jsonRef> at json path "<path>" should[ not] <match> "<expression>"
With custom timeout (as of v3.73.0):
@Timeout('10s') <jsonRef> at json path "<path>" should[ not] <match> "<expression>"
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.
pathis the JSON path selector expressionnotnegates the match if included<match>is the type of match to perform, one of:befor exact matchcontainfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatch regexfor regex matchmatch xpathfor XML matchmatch json pathfor JSON match, since v1.4.0match templatefor template match, since v2.16.0match template filefor template file match, since v2.16.0
<expression>is the expression to match<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
Example
Given the json is "{ "status": "passed" }"
Then the json at json path "$.status" should be "passed"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
URL asserts
the current URL should[ not] be <blank|empty>
Checks whether or not the current browser URL matches a blank or empty string. Reports an assertion error if the match fails.
the current URL should[ not] be <blank|empty>
With custom assertion error message (as of v3.9.0):
the current URL should[ not] be blank @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') the current URL should[ not] be blank
With custom timeout (as of v3.73.0):
@Timeout('10s') the current URL should[ not] be blank
Where
notnegates the match if included<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
Example
When I navigate to "https://todomvc.com/examples/react/dist"
Then the current URL should not be blank
Trimming (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing
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.
the current URL should[ not] <match> "<expression>"
With custom assertion error message (as of v3.9.0):
the current URL should[ not] <match> "<expression>" @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') the current URL should[ not] <match> "<expression>"
With custom timeout (as of v3.73.0):
@Timeout('10s') the current URL should[ not] <match> "<expression>"
Where
notnegates the match if included<match>is the type of match to perform, one of:befor exact matchcontainfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatch regexfor regex matchmatch xpathfor XML matchmatch json pathfor JSON match, since v1.4.0match templatefor template match, since v2.16.0match template filefor template file match, since v2.16.0
<expression>is the expression to match (can be in DocString position)<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
Example
When I navigate to "https://todomvc.com/examples/react/dist"
Then the current URL should contain "todomvc.com"
And the current URL should not contain "other.com"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
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.
the current URL should[ not] <match> <expressionRef>
With custom assertion error message (as of v3.9.0):
the current URL should[ not] <match> <expressionRef> @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') the current URL should[ not] <match> <expressionRef>
With custom timeout (as of v3.73.0):
@Timeout('10s') the current URL should[ not] <match> <expressionRef>
Where
notnegates the match if included<match>is the type of match to perform, one of:befor exact matchcontainfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatch regexfor regex matchmatch xpathfor XML matchmatch json pathfor JSON match, since v1.4.0match templatefor template match, since v2.16.0match template filefor 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.
<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
Example
Given my domain is "todomvc.com"
And some other domain is "someother.com"
When I navigate to "https://todomvc.com/examples/react/dist"
Then the current URL should contain my domain
And the current URL should not contain some other domain
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
Page title asserts
the page title should[ not] be <blank|empty>
Checks whether or not the title of the current page matches a blank or empty string. Reports an assertion error if the match fails.
the page title should[ not] be <blank|empty>
With custom assertion error message (as of v3.9.0):
the page title should[ not] be blank @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') the page title should[ not] be blank
With custom timeout (as of v3.73.0):
@Timeout('10s') the page title should[ not] be blank
Where
notnegates the match if included<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
Example
When I navigate to "https://todomvc.com/examples/react/dist"
Then the page title should not be blank
Trimming (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing
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.
the page title should[ not] <match> "<expression>"
With custom assertion error message (as of v3.9.0):
the page title should[ not] <match> "<expression>" @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') the page title should[ not] <match> "<expression>"
With custom timeout (as of v3.73.0):
@Timeout('10s') the page title should[ not] <match> "<expression>"
Where
notnegates the match if included<match>is the type of match to perform, one of:befor exact matchcontainfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatch regexfor regex matchmatch xpathfor XML matchmatch json pathfor JSON path match, since v1.4.0match templatefor template match, since v2.16.0match template filefor template file match, since v2.16.0
<expression>is the expression to match (can be in DocString position)<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
Example
When I navigate to "https://todomvc.com/examples/react/dist"
Then the page title should contain "TodoMVC"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
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.
the page title should[ not] <match> <expressionRef>
With custom assertion error message (as of v3.9.0):
the page title should[ not] <match> <expressionRef> @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') the page title should[ not] <match> <expressionRef>
With custom timeout (as of v3.73.0):
@Timeout('10s') the page title should[ not] <match> <expressionRef>
Where
notnegates the match if included<match>is the type of match to perform, one of:befor exact matchcontainfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatch regexfor regex matchmatch xpathfor XML matchmatch json pathfor JSON path match, since v1.4.0match templatefor template match, since v2.16.0match template filefor 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.
<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
Example
Given the app name is "TodoMVC"
When I navigate to "https://todomvc.com/examples/react/dist"
Then the page title should contain the app name
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
Element asserts
<element> should[ not] be <state>
Checks whether or not an element is in a given state.
<element> should[ not] be <state>
With custom assertion error message (as of v3.9.0):
<element> should[ not] be <state> @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <element> should[ not] be <state>
With custom timeout (as of v3.73.0):
@Timeout('10s') <element> should[ not] be <state>
Where
<element>is the name of the element to checknotnegates the state if included<state>is one of:displayedto check if the element is displayedhiddento check if the element is not displayedchecked(ortickedsince v2.4.0) to check if a checkbox is tickedunchecked(oruntickedsince v2.4.0) to check if a checkbox is not tickedenabledto check if the element is enableddisabledto check if the element is disabled
<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
Example
Given my todo list can be located by css ".todo-list"
When I navigate to "https://todomvc.com/examples/react/dist"
Then my todo list should be empty
<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.
<element> should[ not] <match> "<expression>"
With custom assertion error message (as of v3.9.0):
<element> should[ not] <match> "<expression>" @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <element> should[ not] <match> "<expression>"
With custom timeout (as of v3.73.0):
@Timeout('10s') <element> should[ not] <match> "<expression>"
Where
<element>is the name of the element to checknotnegates the match if included<match>is the type of match to perform, one of:befor exact matchcontainfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatch regexfor regex matchmatch xpathfor XML matchmatch json pathfor JSON match, since v1.4.0match templatefor template match, since v2.16.0match template filefor template file match, since v2.16.0
<expression>is the expression to match (can be in DocString position)<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
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/dist"
And I enter "Get the milk" in the todo field
Then my todo list should contain "Get the milk"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
<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.
<element> should[ not] <match> <expressionRef>
With custom assertion error message (as of v3.9.0):
<element> should[ not] <match> <expressionRef> @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <element> should[ not] <match> <expressionRef>
With custom timeout (as of v3.73.0):
@Timeout('10s') <element> should[ not] <match> <expressionRef>
Where
<element>is the name of the element to checknotnegates the match if included<match>is the type of match to perform, one of:befor exact matchcontainfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatch regexfor regex matchmatch xpathfor XML matchmatch json pathfor JSON match, since v1.4.0match templatefor template match, since v2.16.0match template filefor 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.
<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
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/dist"
And I enter my item in the todo field
Then my todo list should contain my item
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
Dropdown asserts
<dropdown> <text|value> should[ not] be <blank|empty>
Checks whether or not a dropdown selection matches a blank or empty string. Reports an assertion error if the match fails.
<dropdown> <text|value> should[ not] be <blank|empty>
With custom assertion error message (as of v3.9.0):
<dropdown> <text|value> should[ not] be blank @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <dropdown> <text|value> should[ not] be blank
With custom timeout (as of v3.73.0):
@Timeout('10s') <dropdown> <text|value> should[ not] be blank
Where
<dropdown>is the dropdown element to check<text|value>is one of:textto check the displayed text of the selectionvalueto check the option value of the selection
notnegates the match if included<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
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 not be blank
Trimming (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing
<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.
<dropdown> <text|value> should[ not] <match> "<expression>"
With custom assertion error message (as of v3.9.0):
<dropdown> <text|value> should[ not] <match> "<expression>" @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <dropdown> <text|value> should[ not] <match> "<expression>"
With custom timeout (as of v3.73.0):
@Timeout('10s') <dropdown> <text|value> should[ not] <match> "<expression>"
Where
<dropdown>is the dropdown element to check<text|value>is one of:textto check the displayed text of the selectionvalueto check the option value of the selection
notnegates the match if included<match>is the type of match to perform, one of:befor exact matchcontainfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatch regexfor regex matchmatch xpathfor XML matchmatch json pathfor JSON match, since v1.4.0match templatefor template match, since v2.16.0match template filefor template file match, since v2.16.0
<expression>is the expression to match (can be in DocString position)<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
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"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
<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.
<dropdown> <text|value> should[ not] <match> <expressionRef>
With custom assertion error message (as of v3.9.0):
<dropdown> <text|value> should[ not] <match> <expressionRef> @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <dropdown> <text|value> should[ not] <match> <expressionRef>
With custom timeout (as of v3.73.0):
@Timeout('10s') <dropdown> <text|value> should[ not] <match> <expressionRef>
Where
<dropdown>is the dropdown element to check<text|value>is one of:textto check the displayed text of the selectionvalueto check the option value of the selection
notnegates the match if included<match>is the type of match to perform, one of:befor exact matchcontainfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatch regexfor regex matchmatch xpathfor XML matchmatch json pathfor JSON match, since v1.4.0match templatefor template match, since v2.16.0match template filefor 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.
<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
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
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
Browser asserts
I should have 1 open browser
Checks that only one browser session is currently open. Reports an assertion error if not.
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.
I should have <count> open browsers
With custom assertion error message (as of v3.9.0):
I should have <count> open browsers @Message("my custom assert fail message")
Where
countthe expected number of open browsers
Example
Given I have no open browser
When I navigate to "https://todomvc.com/examples/react/dist"
And I start a browser for Vue
And I navigate to "https://todomvc.com/examples/vue"
Then I should have 2 open browsers
Alert and Popup asserts
the <alert|confirmation> popup message should[ not] be <blank|empty>
Checks whether or not the message in the alert or confirmation popup box matches a blank or empty string. Reports an assertion error if the match fails.
the <alert|confirmation> popup message should[ not] be <blank|empty>
With custom assertion error message (as of v3.9.0):
the <alert|confirmation> popup message should[ not] be blank @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') the <alert|confirmation> popup message should[ not] be blank
With custom timeout (as of v3.73.0):
@Timeout('10s') the <alert|confirmation> popup message should[ not] be blank
Where
notnegates the match if included<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
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 not be blank
Trimming (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing
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.
the <alert|confirmation> popup message should[ not] <match> "<expression>"
With custom assertion error message (as of v3.9.0):
the <alert|confirmation> popup message should[ not] <match> "<expression>" @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') the <alert|confirmation> popup message should[ not] <match> "<expression>"
With custom timeout (as of v3.73.0):
@Timeout('10s') the <alert|confirmation> popup message should[ not] <match> "<expression>"
Where
notnegates the match if included<match>is the type of match to perform, one of:befor exact matchcontainfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatch regexfor regex matchmatch xpathfor XML matchmatch json pathfor JSON match, since v1.4.0match templatefor template match, since v2.16.0match template filefor template file match, since v2.16.0
<expression>is the expression to match (can be in DocString position)<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
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!"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
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.
the <alert|confirmation> popup message should[ not] <match> <expressionRef>
With custom assertion error message (as of v3.9.0):
the <alert|confirmation> popup message should[ not] <match> <expressionRef> @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') the <alert|confirmation> popup message should[ not] <match> <expressionRef>
With custom timeout (as of v3.73.0):
@Timeout('10s') the <alert|confirmation> popup message should[ not] <match> <expressionRef>
Where
notnegates the match if included<match>is the type of match to perform, one of:befor exact matchcontainfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatch regexfor regex matchmatch xpathfor XML matchmatch json pathfor JSON match, since v1.4.0match templatefor template match, since v2.16.0match template filefor 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.
<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
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
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
Existential asserts
<name> should be absent
Checks that a named binding is absent from the current scope.
<name> should be absent
With custom assertion error message (as of v3.9.0):
<name> should be absent @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <name> should be absent
With custom timeout (as of v3.73.0):
@Timeout('10s') <name> should be absent
Where
<name>is the name of the binding to check<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
Example
Then this should be absent
or equivalently (as of v3.29.0)
Then that should not be defined
<name> should[ not] be defined
Checks whether or not a named binding exists in the current scope.
<name> should[ not] be defined
With custom assertion error message:
<name> should be defined @Message("my custom assert fail message")
Without any timeout(as of v3.73.0):
@Timeout('0s') <name> should be defined
With custom timeout (as of v3.73.0):
@Timeout('10s') <name> should be defined
Where
<name>is the name of the binding to checknotnegates the check (for absence/non existence)<timeoutSecs>is the timeout period in seconds<wait|timeout>is eitherwaitortimeout
Example
To check for the presence of a binding
Then this should be defined
To check for the absence of a binding
Then that should not be defined
or equivalently
Then that should be absent
Cumulative asserts
there should be no accumulated errors
Checks that no errors were raised prior to this been called and raises all accumulated error messages (if any) in one assertion error.
there should be no accumulated errors
Example
Then @Soft x should not be blank
And @Soft y should be "1"
And @Soft z should be true
And there should be no accumulated errors
Line 4 will pass if all the preceeding assertions pass. If however, the assertions on line 1 and 3 fail (and the one on line 2 passes), then it will raise an assertion error containing the two messages as follows:
2 errors:
(1) x should not be blank
(2) z should be true but got false
I reset accumulated errors
Resets (clears) any previously accumulated errors.
I reset accumulated errors
Example
When I reset accumulated errors
Then @Soft x should not be blank
And @Soft y should be "1"
And @Soft z should be true
And there should be no accumulated errors
Line 1 will clear any previously accumulated errors from the currently executing context.
So only the messages of all failed assertions leading up to line 4 will be included.
Control structures
ForEach
Since v3.48.0, the following implicit attributes are available to
<step>s:
gwen.iteration.number= current iteration starting at 1gwen.iteration.index= current iteration starting at 0
<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 that can be overridden with the @Timeout annotation.
<step> for each <element> located by <selector> "<expression>"
@Timeout annotation.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:idfor selecting by id attributenamefor selecting by name attributetag name(ortagsince v2.46.0) for selecting by tag namecss selector(orcsssince v2.46.0) for selecting by css expressionclass name(orclasssince v2.46.0) for selecting by class attributexpathfor selecting by XPathlink textfor selecting by link textpartial link textfor selecting by partial link textjavascript(orjssince 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"
When I navigate to "https://todomvc.com/examples/react/dist"
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 contain "0"
With explicit timeout since v3.73.0
Given the todo field can be located by class "new-todo"
And the active count can be located by css ".todo-count"
When I navigate to "https://todomvc.com/examples/react/dist"
And I enter "Walk the dog" in the todo field
And I enter "Feed the cat" in the todo field
And @Timeout('10s') I tick todo item for each todo item located by css ".todo-list .toggle"
Then the active count should contain "0"
Without any timeout since v3.73.0
Given the todo field can be located by class "new-todo"
And the active count can be located by css ".todo-count"
When I navigate to "https://todomvc.com/examples/react/dist"
And I enter "Walk the dog" in the todo field
And I enter "Feed the cat" in the todo field
And @Timeout('0s') I tick todo item for each todo item located by css ".todo-list .toggle"
Then the active count should contain "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 that can be overridden with the @Timeout annotation.
<step> for each <element> located by <selector> "<expression>" in <containerElement>
@Timeout annotation.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:idfor selecting by id attributenamefor selecting by name attributetag name(ortagsince v2.46.0) for selecting by tag namecss selector(orcsssince v2.46.0) for selecting by css expressionclass name(orclasssince v2.46.0) for selecting by class attributexpathfor selecting by XPathlink textfor selecting by link textpartial link textfor selecting by partial link textjavascript(orjssince 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"
When I navigate to "https://todomvc.com/examples/react/dist"
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 contain "0"
With explicit timeout since v3.73.0
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"
When I navigate to "https://todomvc.com/examples/react/dist"
And I enter "Walk the dog" in the todo field
And I enter "Feed the cat" in the todo field
And @Timeout('10s') I tick todo item for each todo item located by class "toggle" in the todo list
Then the active count should contain "0"
Without any timeout since v3.73.0
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"
When I navigate to "https://todomvc.com/examples/react/dist"
And I enter "Walk the dog" in the todo field
And I enter "Feed the cat" in the todo field
And @Timeout('0s') I tick todo item for each todo item located by class "toggle" in the todo list
Then the active count should contain "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 that can be overridden with the @Timeout annotation.
<step> for each <element> in <elements>
@Timeout annotation.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"
And all todo items can be located by css ".todo-list .toggle"
When I navigate to "https://todomvc.com/examples/react/dist"
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 contain "0"
<step> for each data record
Executes a step for each record in a data table.
<step> for each data record
Where
<step>is the DSL step or StepDef to execute for each record- Each field in a record can be accessed in
<step>using the field's associated header name The following implicit bindings are available in
<step>:gwen.table.record.numberis the current record number (starting at 1)gwen.table.record.indexis the record index (starting at 0), since v2.30.1
Example
Feature Scenario: my scenario
Given I have the following active items
| Item |
| Walk the dog |
| Get the milk |
| Feed the cat |
@StepDef
@DataTable
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"
When I navigate to "https://todomvc.com/examples/react/dist"
And I enter Item in the todo field for each data record
Then the active count should contain "3"
<step> for each <entry> in <textRef> delimited by "<delimiter>"
Executes a step for each delimited text entry.
<step> for each <entry> in <textRef> 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)<textRef>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<textRef>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"
And my items is "Walk the dog, Feed the cat, Get the milk"
When I navigate to "https://todomvc.com/examples/react/dist"
And I enter item in the todo field for each item in my items delimited by ","
Then the active count should contain "3"
<step> for each <entry> in <arrayRef> array"
Executes a step for each text entry in a JSON array.
<step> for each <entry> in <arrayRef> array"
Where
<step>is the DSL step or StepDef to execute for each entry<entry>is the name that will be assigned to the current entry occurrence (entry is accessible in<step>by this name)<arrayRef>is the name of the binding containing the string repersentation of the JSON array- Can be the name of any binding that contains or resolves to a JSON array string, 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 the active count can be located by css ".todo-count"
And my items is
"""
[
"Walk the dog",
"Feed the cat",
"Get the milk"
]
"""
When I navigate to "https://todomvc.com/examples/react/dist"
And I enter item in the todo field for each item in my items array
Then the active count should contain "3"
Until/While
Since v3.48.0, the following implicit attributes are available to
<step>s:
gwen.iteration.number= current iteration starting at 1gwen.iteration.index= current iteration starting at 0
<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. The default delay and timeout can be overridden using the @Delay and @Timeout annotations.
<step> <until|while> <condition>
gwen.web.wait.seconds setting (or 1 second if not set). The default timeout period is 30 times the delay. The default delay and timeout can be overridden using the @Delay and @Timeout annotations.Where
<step>is the DSL step or StepDef to execute in each iteration<until|while>is one of:untilto repeat until the condition is satisfiedwhileto repeat while the condition is satisfied
<condition>is either:Since v3.54.0
- the name of any binding that will return
truewhen the condition is satisfied orfalsewhen it is not
- the name of any binding that will return
Or in prior versions
- the name of a binding containing a javascript function or expression that will return
truewhen the condition is satisfied orfalsewhen it is not - the name of a binding containing a
trueorfalsevalue literal, since v3.50.0
- the name of a binding containing a javascript function or expression that will return
The following implicit binding is available in
<step>:iteration number(orgwen.iteration.numbersince 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}"
With explicit delay and timeout since v3.73.0
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 @Delay('10s') @Timeout('1m') I click the next page link while topic not found
And I click topic link
Then the page title should contain "${topic}"
With no delay or timeout since v3.73.0
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 @Delay('0s') @Timeout('0s') 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> <element> is[ not] <state>
Repeatedly exectues a step until or while an element is in a given state using a 1 second delay interval and 1 minute timeout period. The default delay and timeout can be overridden using the @Delay and @Timeout annotations.
<step> <until|while> <element> is[ not] <state>
@Delay and @Timeout annotations.Where
<step>is the DSL step or StepDef to execute in each iteration<until|while>is one of:untilto repeat until the condition is satisfiedwhileto repeat while the condition is satisfied
<element>is the name of the element to check the state ofnotnegates the state if included<state>is one of:displayedto execute the step until or while the element is displayedhiddento execute the step until or while the element is not displayedcheckedortickedto execute the step until or while a checkbox is tickeduncheckedoruntickedto execute the step until or while a checkbox is not tickedenabledto execute the step until or while the element is enableddisabledto execute the step until or while the element is disabled
The following implicit binding is available in
<step>:iteration number(orgwen.iteration.numbersince 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"
When I navigate to "https://google.com"
And I enter "gwen interpreter" in the search field
And I click the next page link while the next page link is displayed
Then the next page link should not be displayed
With explicit delay and timeout since v3.73.0
Given the search field can be located by name "q"
And the next page link can be located by id "pnnext"
When I navigate to "https://google.com"
And I enter "gwen interpreter" in the search field
And @Delay('5s') @Timeout('40s') I click the next page link while the next page link is displayed
Then the next page link should not be displayed
With no delay or timeout since v3.73.0
Given the search field can be located by name "q"
And the next page link can be located by id "pnnext"
When I navigate to "https://google.com"
And I enter "gwen interpreter" in the search field
And @Delay('0s') @Timeout('0s') I click the next page link while the next page link is displayed
Then the next page link should not be displayed
<step> <until|while> <name> is[ not] defined
Repeatedly exectues a step until or while an attribute is defined (or not) using a 1 second delay interval and 1 minute timeout period. The default delay and timeout can be overridden using the @Delay and @Timeout annotations.
<step> <until|while> <name> is[ not] defined
@Delay and @Timeout annotations.Where
<step>is the DSL step or StepDef to execute in each iteration<until|while>is one of:untilto repeat until the attribute is defined (or not)whileto repeat while the attribute is defined (or not)
<name>is the name of the attribute to checknotinclude to execute step until or while attribute is not definedThe following implicit binding is available in
<step>:iteration number(orgwen.iteration.numbersince v2.52.0) is the current iteration number (starting at 1)
<step> <until|while> "<filepath>" file[ not] exists
Repeatedly exectues a step until or while a file exists (or not) using a 1 second delay interval and 1 minute timeout period. The default delay and timeout can be overridden using the @Delay and @Timeout annotations.
<step> <until|while> "<filepath>" file[ not] exists
@Delay and @Timeout annotations.Where
<step>is the DSL step or StepDef to execute in each iteration<until|while>is one of:untilto repeat until the attribute is defined (or not)whileto repeat while the attribute is defined (or not)
<filepath>the path to the file to checknotto wait until the file does not exist (negation)The following implicit binding is available in
<step>:iteration number(orgwen.iteration.numbersince v2.52.0) is the current iteration number (starting at 1)
<step> <until|while> "<filepath>" file does not exist
Repeatedly exectues a step until or while a file does not exist using a 1 second delay interval and 1 minute timeout period. The default delay and timeout can be overridden using the @Delay and @Timeout annotations.
<step> <until|while> "<filepath>" file does not exist
@Delay and @Timeout annotations.Where
<step>is the DSL step or StepDef to execute in each iteration<until|while>is one of:untilto repeat until the attribute is defined (or not)whileto repeat while the attribute is defined (or not)
<filepath>the path to the file to checkThe following implicit binding is available in
<step>:iteration number(orgwen.iteration.numbersince v2.52.0) is the current iteration number (starting at 1)
<step> <until|while> "<filepath>" file is[ not] empty
Repeatedly exectues a step until or while a file is empty (or not) using a 1 second delay interval and 1 minute timeout period. The default delay and timeout can be overridden using the @Delay and @Timeout annotations.
<step> <until|while> "<filepath>" file is[ not] empty
@Delay and @Timeout annotations.Where
<step>is the DSL step or StepDef to execute in each iteration<until|while>is one of:untilto repeat until the attribute is defined (or not)whileto repeat while the attribute is defined (or not)
<filepath>the path to the file to checknotto wait until the file is not empty (negation)The following implicit binding is available in
<step>:iteration number(orgwen.iteration.numbersince v2.52.0) is the current iteration number (starting at 1)
<step> <until|while> <filepathRef file>[ not] exists
Repeatedly exectues a step until or while a file exists (or not) using a 1 second delay interval and 1 minute timeout period. The default delay and timeout can be overridden using the @Delay and @Timeout annotations.
<step> <until|while> <filepathRef file>[ not] exists
@Delay and @Timeout annotations.Where
<step>is the DSL step or StepDef to execute in each iteration<until|while>is one of:untilto repeat until the attribute is defined (or not)whileto repeat while the attribute is defined (or not)
<filepathRef file>is the name of the binding containing the path of the file to checknotto wait until the file does not exist (negation)The following implicit binding is available in
<step>:iteration number(orgwen.iteration.numbersince v2.52.0) is the current iteration number (starting at 1)
<step> <until|while> <filepathRef file> does not exist
Repeatedly exectues a step until or while a file does not exist using a 1 second delay interval and 1 minute timeout period. The default delay and timeout can be overridden using the @Delay and @Timeout annotations.
<step> <until|while> <filepathRef file> does not exist
@Delay and @Timeout annotations.Where
<step>is the DSL step or StepDef to execute in each iteration<until|while>is one of:untilto repeat until the attribute is defined (or not)whileto repeat while the attribute is defined (or not)
<filepathRef file>is the name of the binding containing the path of the file to checkThe following implicit binding is available in
<step>:iteration number(orgwen.iteration.numbersince v2.52.0) is the current iteration number (starting at 1)
<step> <until|while> <filepathRef file> is[ not] empty
Repeatedly exectues a step until or while a file is empty (or not) using a 1 second delay interval and 1 minute timeout period. The default delay and timeout can be overridden using the @Delay and @Timeout annotations.
<step> <until|while> <filepathRef file> is[ not] empty
@Delay and @Timeout annotations.Where
<step>is the DSL step or StepDef to execute in each iteration<until|while>is one of:untilto repeat until the attribute is defined (or not)whileto repeat while the attribute is defined (or not)
<filepathRef file>is the name of the binding containing the path of the file to checknotto wait until the file is not empty (negation)The following implicit binding is available in
<step>:iteration number(orgwen.iteration.numbersince v2.52.0) is the current iteration number (starting at 1)
<step> <while|until> <name> is[ not] <blank|empty>
Repeatedly exectues a step until or while an element or attribute is bound to a blank or empty value (or not) using a 1 second delay interval and 1 minute timeout period. The default delay and timeout can be overridden using the @Delay and @Timeout annotations.
<step> <while|until> <name> is[ not] <blank|empty>
Where
<step>is the DSL step or StepDef to repeatedly execute<name>is the name of the element or attribute to checknotto negate the condition
Example
Given the state code can be located by name "state"
When I navigate to "https://example.com"
And I refresh the current page while the state code is blank
<step> <while|until> <name> is[ not] "<value>"
Repeatedly exectues a step until or while an element or attribute is equal to a value (or not) using a 1 second delay interval and 1 minute timeout period. The default delay and timeout can be overridden using the @Delay and @Timeout annotations.
<step> <while|until> <name> is[ not] "<value>"
Where
<step>is the DSL step or StepDef to repeatedly execute<name>is the name of the element or attribute to checknotto negate the conditionvalueis the given value
Example
Given the state code can be located by name "state"
When I navigate to "https://example.com?state=Victoria"
And I refresh the current page while the state code is not "VIC"
Trimming and ignoring case
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
<step> <while|until> <name> <match> "<expression>"`
Repeatedly exectues a step until or while an element or attribute matches an expression using a 1 second delay interval and 1 minute timeout period. The default delay and timeout can be overridden using the @Delay and @Timeout annotations.
<step> <while|until> <name> <match> "<expression>"`
Where
<step>is the DSL step or StepDef to repeatedly execute<name>is the name of the element or attribute to check<match>is the type of match to perform, one of:containsfor partial matchstarts withfor partial leading matchends withfor partial trailing matchmatches regexfor regex matchmatches xpathfor XML matchmatches json pathfor JSON match, since v1.4.0matches templatefor template match, since v2.16.0matches template filefor template file match, since v2.16.0
<expression>is the expression to match (can be in DocString position)
Example
Given the state code can be located by name "state"
When I navigate to "https://example.com?state=${the state code}"
And I refresh the current page until the state code matches regex "(VIC|NSW)"
Trimming and ignoring case
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
<step> <while|until> <name> does not <match> "<expression>"`
Repeatedly exectues a step until or while an element or attribute does not match an expression using a 1 second delay interval and 1 minute timeout period. The default delay and timeout can be overridden using the @Delay and @Timeout annotations.
<step> <while|until> <name> does not <match> "<expression>"`
Where
<step>is the DSL step or StepDef to repeatedly execute<name>is the name of the element or attribute to check<match>is the type of match to perform, one of:containfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatche regexfor regex matchmatche xpathfor XML matchmatche json pathfor JSON match, since v1.4.0matche templatefor template match, since v2.16.0matche template filefor template file match, since v2.16.0
<expression>is the expression to match (can be in DocString position)
Example
Given the state code can be located by name "state"
When I navigate to "https://example.com?state=${the state code}"
And I refresh the current page until the state code does not match regex "(VIC|NSW)"
Trimming and ignoring case
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
If
<step> if[ not] <condition>
Executes a step depending on whether or not a JS condition evaluates to true.
<step> if[ not] <condition>
Where
<step>is the DSL step or StepDef to potentially executenotnegates the condition if included (Since v3.4.0)<condition>is either:Since v3.54.0
- the name of any binding that will return
truewhen the condition is satisfied orfalsewhen it is not
- the name of any binding that will return
Or in prior versions
- the name of a binding containing a javascript function or expression that will return
truewhen the condition is satisfied orfalsewhen it is not - the name of a binding containing a
trueorfalsevalue literal, since v3.50.0
- the name of a binding containing a javascript function or expression that will return
- Since v3.14.1, the condition name cannot contain double qutoes
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 "automation" in the search field
And I click topic link if topic found
Then the page title should contain "${topic}" if topic found
<step> if <element> is[ not] <state>
Executes a step depending on whether or not an element is in a given state.
<step> if <element> is[ not] <state>
Where
<step>is the DSL step or StepDef to potentially execute<element>is the name of the element to check the state ofnotnegates the state if included<state>is one of:displayedto execute the step if the element is displayedhiddento execute the step if the element is not displayedcheckedortickedto execute the step if a checkbox is tickeduncheckedoruntickedto execute the step if a checkbox is not tickedenabledto execute the step if the element is enableddisabledto execute the step if the element is disabled
Example
Given the search field can be located by name "q"
And topic is "Automation"
And topic link can be located by partial link text "${topic}"
When I navigate to "https://google.com"
And I enter "automation" in the search field
And I click topic link if topic link is displayed
Then the page title should contain "${topic}"
<step> if <name> is[ not] defined
Executes a step depending on whether or not an attribute is bound in the global or current scope.
<step> if <name> is[ not] defined
Where
<step>is the DSL step or StepDef to potentially execute<name>is the name of the attribute to checknotinclude to execute step if attribute is not bound
Example
Given the CSV file: lookup/StateCodes.csv
Code,Name
ACT,Australian Capital Territory
NSW,New South Wales
NT,Northern Territory
QLD,Queensland
SA,South Australia
TAS,Tasmania
VIC,Victoria
WA,Western Australia
The following will bind "New South Wales" in the 2nd record to state name in the global scope
Given the state code is "UNKNOWN"
When I lookup Name in the "lookup/StateCodes.csv" file as state name where "'${data.record.Code}' == '${the state code}'"
Then unresolved is "true" if state name is not defined
<step> if <name> is[ not] <blank|empty>
Executes a step depending on whether or not an element or attribute is bound to a blank or empty value.
<step> if <name> is[ not] <blank|empty>
Where
<step>is the DSL step or StepDef to potentially execute<name>is the name of the element or attribute to checknotinclude to execute step if attribute is not blank
Example
Given the state code can be located by name "state"
When I navigate to "https://example.com" if the state code is blank
And I navigate to "https://example.com?state=${the state code}" if the state code is not blank
<step> if <name> is[ not] "<value>"
Executes a step depending on whether or not an element or attribute is equal to a value.
<step> if <name> is[ not] "<value>"
Where
<step>is the DSL step or StepDef to potentially execute<name>is the name of the element or attribute to checknotinclude to execute step if the attribute is not equal to the given valuevalueis the given value
Example
Given the state code can be located by name "state"
When I navigate to "https://example.com?state=Victoria" if the state code is "VIC"
And I navigate to "https://example.com?state=Other" if the state code is not "VIC"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
<step> if <name> <match> "<expression>"`
Executes a step depending on whether or not an element or attribute matches an expression.
<step> if <name> <match> "<expression>"`
Where
<step>is the DSL step or StepDef to potentially execute<name>is the name of the element or attribute to check<match>is the type of match to perform, one of:containsfor partial matchstarts withfor partial leading matchends withfor partial trailing matchmatches regexfor regex matchmatches xpathfor XML matchmatches json pathfor JSON match, since v1.4.0matches templatefor template match, since v2.16.0matches template filefor template file match, since v2.16.0
<expression>is the expression to match (can be in DocString position)
Example
Given the state code can be located by name "state"
When I navigate to "https://example.com?state=${the state code}" if the state code matches regex "(VIC|NSW)"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
<step> if <name> does not <match> "<expression>"`
Executes a step depending on whether or not an element or attribute does not match an expression.
<step> if <name> does not <match> "<expression>"`
Where
<step>is the DSL step or StepDef to potentially execute<name>is the name of the element or attribute to check<match>is the type of match to perform, one of:containfor partial matchstart withfor partial leading matchend withfor partial trailing matchmatche regexfor regex matchmatche xpathfor XML matchmatche json pathfor JSON match, since v1.4.0matche templatefor template match, since v2.16.0matche template filefor template file match, since v2.16.0
<expression>is the expression to match (can be in DocString position)
Example
Given the state code can be located by name "state"
When I navigate to "https://example.com?state=${the state code}" if the state code does not match regex "(QLD|NT|wA)"
Trimming and ignoring case (since v3.62.0)
- The
@Trimannotation can be used on step to trim strings when comparing - The
@IgnoreCaseannotation can be used on step to ignore case when comparing
<step> if "<filepath>" file[ not] exists
Executes a step if a file exists (or not).
<step> if "<filepath>" file[ not] exists
<step> if "<filepath>" file does not exist
Executes a step if a file does not exist.
<step> if "<filepath>" file does not exist
<step> if "<filepath>" file is[ not] empty
Executes a step if a file is empty (or not).
<step> if "<filepath>" file is[ not] empty
<step> if <filepathRef file>[ not] exists
Executes a step if a file exists (or not).
<step> if <filepathRef file>[ not] exists
Where
<step>is the DSL step or StepDef to potentially execute<filepathRef file>is the name of the binding containing the path of the filenotto execute step if file does not exist (negation)
Examples
Given my file is "path/to/filename.csv"
Then call step 1 if my file exists
And call step 2 if my file not exists
<step> if <filepathRef file> does not exist
Executes a step if a file does not exist.
<step> if <filepathRef file> does not exist
<step> if <filepathRef file> is[ not] empty
Executes a step if a file is empty (or not).
<step> if <filepathRef file> is[ not] empty
Where
<step>is the DSL step or StepDef to potentially execute<filepathRef file>is the name of the binding containing the path of the filenotto execute step if file is not empty (negation)
Examples
Given my file is "path/to/filename.csv"
Then call step 1 if my file is empty
And call step 2 if my file is not empty