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.
@Eager
immediately evaluates the<expression>
and binds the result to<name>
@Lazy
evaluates 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.
@Eager
immediately evaluates the<expression>
and binds the result to<name>
@Lazy
evaluates 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.
@Eager
immediately evaluates the<expression>
and binds the result to<name>
@Lazy
evaluates 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 @Masked
masks 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:text
to capture the text nodenode
to capture a single nodenodeset
to capture multiple nodes
<xmlRef>
is the name of the binding containing the XML source- Can be the name of any binding that contains or resolves to XML text, including a web element in which case the text in the element will be dynamically retrieved and used.
<expression>
is the XPath selector expression
Optionally accepts the @Eager
, @Lazy
or @Masked
annotations.
@Eager
immediately evaluates the<expression>
and binds the result to<name>
@Lazy
evaluates 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 @Masked
masks 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:text
to capture the text nodenode
to capture a single nodenodeset
to capture multiple nodes
<sourceRef>
is the name of the binding containing the XML source- Can be the name of any binding that contains or resolves to XML text, including a web element in which case the text in the element will be dynamically retrieved and used.
<expression>
is the XPath selector expression
Optionally accepts the @Eager
, @Lazy
or @Masked
annotations.
@Eager
immediately evaluates the<expression>
and binds the result to<name>
@Lazy
evaluates 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 @Masked
masks 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
(orjs
since 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
return
prefix 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.
@Eager
immediately evaluates the<expression>
and binds the result to<name>
@Lazy
evaluates 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 @Masked
masks 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.
@Eager
immediately evaluates the<expression>
and binds the result to<name>
@Lazy
evaluates 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 @Masked
masks 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.
@Eager
immediately evaluates the<expression>
and binds the result to<name>
@Lazy
evaluates 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 @Masked
masks 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.
@Eager
immediately applies the function to the element and binds the result to<name>
@Lazy
applies 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 @Masked
masks 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.
@Eager
immediately evaluates the<expression>
and binds the result to<name>
@Lazy
evaluates 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 @Masked
masks 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.
@Eager
immediately evaluates the<expression>
and binds the result to<name>
@Lazy
evaluates 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 @Masked
masks 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.
@Eager
immediately evaluates the<expression>
and binds the result to<name>
@Lazy
evaluates 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 @Masked
masks 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:id
for selecting by id attributename
for selecting by name attributetag name
(ortag
since v2.46.0) for selecting by tag namecss selector
(orcss
since v2.46.0) for selecting by css expressionclass name
(orclass
since v2.46.0) for selecting by class attributexpath
for selecting by XPathlink text
for selecting by link textpartial link text
for selecting by partial link textjavascript
(orjs
since v2.46.0) for selecting by JavaScript
<expression>
is the selector expression
Example
Given the todo field can be located by class "new-todo"
When I enter "Walk the dog" in the todo field
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:id
for selecting by id attributename
for selecting by name attributetag name
(ortag
since v2.46.0) for selecting by tag namecss selector
(orcss
since v2.46.0) for selecting by css expressionclass name
(orclass
since v2.46.0) for selecting by class attributexpath
for selecting by XPathlink text
for selecting by link textpartial link text
for selecting by partial link textjavascript
(orjs
since v2.46.0) for selecting by JavaScript
<expression>
is the selector expression<index>
is the index of the element to select in list returned by<expression>
Example
Given the first item can be located by css ".todo-list label" at index 0
Then the first item should contain "Walk the dog"
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:id
for selecting by id attributename
for selecting by name attributetag name
(ortag
since v2.46.0) for selecting by tag namecss selector
(orcss
since v2.46.0) for selecting by css expressionclass name
(orclass
since v2.46.0) for selecting by class attributexpath
for selecting by XPathlink text
for selecting by link textpartial link text
for selecting by partial link textjavascript
(orjs
since v2.46.0) for selecting by JavaScript
<expression>
is the selector expression<index>
is the index of the element to select in list returned by<expression>
<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:id
for selecting by id attributename
for selecting by name attributetag name
(ortag
since v2.46.0) for selecting by tag namecss selector
(orcss
since v2.46.0) for selecting by css expressionclass name
(orclass
since v2.46.0) for selecting by class attributexpath
for selecting by XPathlink text
for selecting by link textpartial link text
for selecting by partial link textjavascript
(orjs
since 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:id
for selecting by id attributename
for selecting by name attributetag name
(ortag
since v2.46.0) for selecting by tag namecss selector
(orcss
since v2.46.0) for selecting by css expressionclass name
(orclass
since v2.46.0) for selecting by class attributexpath
for selecting by XPathlink text
for selecting by link textpartial link text
for selecting by partial link textjavascript
(orjs
since v2.46.0) for selecting by JavaScript
<expression n>
is the nth selector expression<index>
is the index of the element to select in list returned by<expression n>
Example
Given the second item can be located at index 1 by
| 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:id
for selecting by id attributename
for selecting by name attributetag name
(ortag
since v2.46.0) for selecting by tag namecss selector
(orcss
since v2.46.0) for selecting by css expressionclass name
(orclass
since v2.46.0) for selecting by class attributexpath
for selecting by XPathlink text
for selecting by link textpartial link text
for selecting by partial link textjavascript
(orjs
since v2.46.0) for selecting by JavaScript
<expression>
is the selector expression<relativeTo>
is one ofin
to select element contained in<otherElement>
Or since v3.0.0
above
to select element above<otherElement>
below
to select element below<otherElement>
to left of
to select element to the left of<otherElement>
to right of
to select element to the right of<otherElement>
near
to select element near<otherElement>
near and within <noOfPixels> pixel[s] of
to 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
,on
orin
<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
return
prefix 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:text
to capture the text nodenode
to capture a single nodenodeset
to capture multiple nodes
<xmlRef>
is the name of the binding containing the XML text- Can be the name of any binding that contains or resolves to an XML text value, including a web element in which case the text in the element will be dynamically retrieved and used.
<expression>
is the XPath selector expression<name>
is the name to bind the captured value to
Example
Given the xml is "<result><status>passed</status></result>"
When I capture the text in the xml by xpath "//result/status" as the status
Then the status should be "passed"
I capture the <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:text
to capture the text nodenode
to capture a single nodenodeset
to capture multiple nodes
<element>
is the name of the element containing the XML content<expression>
is the XPath selector expression<name>
is the name to bind the captured value to
Example
# assuming a web element contains xml: <result><status>passed</status></result>
Given the xml web element can be located by id "xml"
When I capture the text in the xml web element by xpath "//result/status" as the status
Then the status should be "passed"
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
@Trim
annotation can be used on step to trim strings when comparing - The
@IgnoreCase
annotation 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
@Trim
annotation can be used on step to trim strings when comparing - The
@IgnoreCase
annotation 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
@Trim
annotation can be used on step to trim strings when comparing - The
@IgnoreCase
annotation 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
@Trim
annotation can be used on step to trim strings when comparing - The
@IgnoreCase
annotation 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>
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:text
to captured the displayed text of the selectionvalue
to captured the option value of the selection
Example
Given the age dropdown can be located by id "challenger_age"
When I navigate to "https://challengers.flood.io/step/2"
And I capture the age dropdown text
I capture <dropdown> <text|value> as <name>
Captures the selected text or value of a dropdown element and binds it to the given name in the global scope.
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:text
to captured the displayed text of the selectionvalue
to captured the option value of the selection
Example
Given the age dropdown can be located by id "challenger_age"
When I navigate to "https://challengers.flood.io/step/2"
And I capture the age dropdown text my age
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 returntrue
when a match is found for a record orfalse
otherwise (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 returntrue
when a match is found for a record orfalse
otherwise (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 returntrue
when a match is found for a record orfalse
otherwise (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 returntrue
when a match is found for a record orfalse
otherwise (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