Notice: WAML 2.0 is currently under development. Feel free to create a pull request in case of useful suggestions.
Documentation for the versions:
Refer to the changelog for recent notable changes and modifications.
# WAML 2
# Order Pizza
- open: www.mypizza.com/login
- enter:
selector: input[name=email]
input: alessandro@volta.it
- enter:
selector: input[name=password]
input: el3ctric
- click: button[type=submit]
- select:
selector: '${item}'
value: '2'
with_items:
- '#pizza-margarita.count'
- '#pizza-quattro-formaggi.count'
- '#pizza-broccoli.count'
- click:
selector: a
text: 'Order now!'
- ensure:
selector: h1.confirm
text: Thanks, your pizza will be there soon!
Web Automation Markup Language (WAML) is definition of action sequences which can be performed on web resources (e.g. regular web pages) within a context of a web browser to simulate user behavior. The WAML specification defines an application of YAML 1.2 which allows an expirienced user to create a human and machine readable sequence at one go, reuse sequences in any order, and perform context dependent actions.
The underlying format for WAML is YAML so that it inherits all its benefits such as hosting of multiple document within one stream.
The structure of WAML is limited to 3-tier hierarchy:
- Step
- Decorator
- Action
- Criterion
A set of steps is called Scenario.
# WAML 2
- open: radio.com
- click: button#play
A scenario is a (reusable) set of actions performed by a user, executed in the predefined order, and resulting in a particular state.
A WAML stream may contain multiple scenarios (separated by ---
, as specified in YAML 1.2). Every scenario must be
represented by a set of metadata as well as sequence of steps to execute.
# WAML 2
- open: www.vacation-planner.me
A step must contain exactly ona action and may contain multiple decorators. Within the step the interacting with web elements based on underlying criteria text place. Further, certain actions may modify the web context.
The action is a part of a step which performs operation on the web context. The actions can be classified as following:
- State validation actions
- State mutation actions
- Support actions
# WAML 2
- enter:
selector: input[name=email]
input: alessandro@volta.it
A criterion is a part of the action which describes a constraint applied on the web elements. Further, criteria of modifying actions perform may manipulations on the web context.
Every step must have at least one criteria which is represented as scalar (string, integer, etc.) value or a mapping.
The criteria can be classified as following:
- Element filter criteria
- Text
- Selector
- Value
- Parent
- Element
- State mutation criteria
- Input
- Url
# WAML 2
- open: www.vacation-planner.me
timeout: 10
A decorator adds an additional behavior on the top of a scenario or action. It does not affect the action's internal logic.
The decorators can be classified as following:
- Conditional decorators
- When
- Unless
- Failed when
- State decorators
- Loop decorator
# WAML 2
# Open non-responsive page
- define:
regularUrl: www.vacation-planner.com
mobileUrl: mobile.vacation-planner.com
- unless: ${isMobule}
open: ${regularUrl}
- when: ${isMobile}
open: ${mobileUrl}
Expressions apply to metadata, criterion, and decorator values. Their aim is to promote reusability and allow to utilize the result of arbitrary operations on context values.
Expression parser must support variable substitution. It also may support other features (e.g. filters).
WAML is based on JSON Schema that lives at waml-schema.org. WAML schema is available in YAML and JSON formats. A scenario within a WAML stream may define the preferred schema version by defining $schema
property, otherwise a default parser schema is used.
# WAML 2
# A full featured scenario
- open: www.example.com
This minimal example demonstrates the simplicity of WAML. The full list of supported metadata is depicted below.
Property | Description | Type |
---|---|---|
– | A scenario combines a sequence of tasks that must be executed together in a certain order. | array |
Using this properties, the following more comprehensive example can be created:
The steps property must be represented as a sequence of actions. Every step represents the smallest identifiable user action.
Property | Description | Type |
---|---|---|
– | A step represents the smallest identifiable user action. | One of: ensure-step-schema, open-step-schema, click-step-schema, enter-step-schema, execute-step-schema, select-step-schema, move-step-schema, define-step-schema, uri-step-schema, wait-step-schema, debug-step-schema, include-step-schema |
name: Fragment scenario
fragment: true
steps:
- open: www.example.com
name: Fragment consumer scenario
steps:
- include: 'Fragment scenario'
Fragment scenarios can not be executed independently and thus can be only be used in include
actions of other
scenarios or fragments. Fragments promote reusability and enable complex project structure.
# WAML 2
# Open demonstration scenario
- open: www.example.com
# WAML 2
# Open demonstration scenario 2
- unless: ${isMobile}
open:
url: www.example.com
- when: ${isMobile}
open:
url: m.example.com
Like for a real user, open
is often the very first action of a scenarios. It triggers the navigation to a particular URL inside the web browser.
The http://
scheme should be automatically added to the url
if no scheme is specified.
Property | Description | Type |
---|---|---|
open | The URL to which the navigation takes place as value or a complex open criteria. | One of: expression-schema, open-criteria-schema |
when | (Optional) If set, the step is only executed if the value evaluates to true. | One of: expression-schema, boolean |
unless | (Optional) If set, the step is only executed if the value evaluates to false. | One of: expression-schema, boolean |
failed_when | (Optional) Mark step as failed if condition is evaluated to true. | One of: expression-schema, boolean |
timeout | (Optional) Maximal time [s] to wait for the element which meets the given criteria. Default: 5 | One of: expression-schema, number |
with_items | (Optional) Items over which the step iteration (loop) takes place. The iterator is available within the step as item . |
|
Sequence of: expression-schema |
Property | Description | Type |
---|---|---|
url | The URL to which the navigation takes place. | expression-schema |
# WAML 2
# Ensure short notation
- open: www.example.com
- ensure: h1.greeting
# WAML 2
# Ensure scenario with additional constraints
- open: www.example.com
- timeout: 4
ensure:
selector: h1.greeting
value: 'Welcome to example.com!'
To verify the integrity of the page it may be reasonable to ensure the presence of a certain element. The action ensure
verifies, whether the particular element is present on the page.
The depicted simple scenario can be created using the shot-notation of ensure
action:
- Open a web page.
- Verify the presence of a header with a certain class.
Using the additional criteria not only the presence of the element can be ensured but also elements content and its appearance within a defined a time constraint.
Property | Description | Type |
---|---|---|
ensure | A CSS selector as value or a hash of conditionals. | One of: expression-schema, ensure-criteria-schema |
when | (Optional) If set, the step is only executed if the value evaluates to true. | One of: expression-schema, boolean |
unless | (Optional) If set, the step is only executed if the value evaluates to false. | One of: expression-schema, boolean |
failed_when | (Optional) Mark step as failed if condition is evaluated to true. | One of: expression-schema, boolean |
timeout | (Optional) Maximal time [s] to wait for the element which meets the given criteria. Default: 5 | One of: expression-schema, number |
with_items | (Optional) Items over which the step iteration (loop) takes place. The iterator is available within the step as item . |
|
Sequence of: expression-schema |
||
register | (Optional) Save output to a variable. | expression-schema |
Property | Description | Type |
---|---|---|
selector | CSS selector of element to select. | expression-schema |
text | (Optional) Select element which text represenation contains the given value. | expression-schema |
value | (Optional) Verify value attribute against this value. | One of: number, boolean, expression-schema |
absent | (Optional) If set to true, the element matching remaining criteria is expected to be absent. Default: false | boolean |
parent | (Optional) Reference to an element which has to be a parent of the given one. This must be areference saved with register before. |
string |
# WAML 2
# Move demonstration scenario
- open: www.example.com
- move: a.help
- ensure:
selector: .help-tooltip
text: 'Click here to get help.'
# WAML 2
# Move demonstration scenario
- open: www.example.com
- ensure: .help-container
register: help_container_element
- move:
selector: a.help
text: 'Need help?'
parent: help_container_element.value
- ensure: .help-tooltip
For hidden elements which appear only after the user has hovered a certain element the (mouse) move
action can be used.
The examples depicts the usage of the move
action.
Property | Description | Type |
---|---|---|
move | A CSS selector as value or a complex move criteria. | One of: expression-schema, move-criteria-schema |
when | (Optional) If set, the step is only executed if the value evaluates to true. | One of: expression-schema, boolean |
unless | (Optional) If set, the step is only executed if the value evaluates to false. | One of: expression-schema, boolean |
failed_when | (Optional) Mark step as failed if condition is evaluated to true. | One of: expression-schema, boolean |
timeout | (Optional) Maximal time [s] to wait for the element which meets the given criteria. Default: 5 | One of: expression-schema, number |
with_items | (Optional) Items over which the step iteration (loop) takes place. The iterator is available within the step as item . |
|
Sequence of: expression-schema |
||
register | (Optional) Save output to a variable. | expression-schema |
Property | Description | Type |
---|---|---|
selector | CSS selector of element to select. | expression-schema |
text | (Optional) Select element which text represenation contains the given value. | expression-schema |
parent | (Optional) Reference to an element which has to be a parent of the given one. This must be areference saved with register before. |
string |
# WAML 2
# Click demonstration scenario
- open: www.example.com
- click: a.sign-up
# WAML 2
# Click demonstration scenario 2
- open: www.example.com
- when: ${isDesktop}
click:
selector: a.sign-up
text: 'Join now for free!'
- when: ${isMobile}
click:
selector: a.sign-up
text: 'Join now!'
Every kind of clicks can be simulated with the click
action.
In the short notation example a click happens on an anchor element selected by CSS.
Also the text
criteria may be used to verify the wording of the target.
Property | Description | Type |
---|---|---|
click | A CSS selector as value or a mapping of criteria. | One of: expression-schema, click-criteria-schema |
when | (Optional) If set, the step is only executed if the value evaluates to true. | One of: expression-schema, boolean |
unless | (Optional) If set, the step is only executed if the value evaluates to false. | One of: expression-schema, boolean |
failed_when | (Optional) Mark step as failed if condition is evaluated to true. | One of: expression-schema, boolean |
timeout | (Optional) Maximal time [s] to wait for the element which meets the given criteria. Default: 5 | One of: expression-schema, number |
with_items | (Optional) Items over which the step iteration (loop) takes place. The iterator is available within the step as item . |
|
Sequence of: expression-schema |
||
register | (Optional) Save output to a variable. | expression-schema |
Property | Description | Type |
---|---|---|
selector | CSS selector of element to select. | expression-schema |
text | (Optional) Select element which text represenation contains the given value. | expression-schema |
parent | (Optional) Reference to an element which has to be a parent of the given one. This must be areference saved with register before. |
string |
# WAML 2
# Select demonstration scenario
- open: www.example.com
- select: '.actions option:first-child'
# WAML 2
# Select demonstration scenario 2
- open: www.example.com
- select:
selector: .title
text: 'PROF DR'
- select:
selector: .country
value: 'CH'
Short notation example of select
and a complex example.
Property | Description | Type |
---|---|---|
select | CSS selector of element to select or an object of select criteria. | One of: expression-schema, select-criteria-schema |
when | (Optional) If set, the step is only executed if the value evaluates to true. | One of: expression-schema, boolean |
unless | (Optional) If set, the step is only executed if the value evaluates to false. | One of: expression-schema, boolean |
failed_when | (Optional) Mark step as failed if condition is evaluated to true. | One of: expression-schema, boolean |
timeout | (Optional) Maximal time [s] to wait for the element which meets the given criteria. Default: 5 | One of: expression-schema, number |
with_items | (Optional) Items over which the step iteration (loop) takes place. The iterator is available within the step as item . |
|
Sequence of: expression-schema |
||
register | (Optional) Save output to a variable. | expression-schema |
Property | Description | Type |
---|---|---|
selector | CSS selector of element to select. | expression-schema |
text | (Optional) Select element which text represenation contains the given value. | expression-schema |
parent | (Optional) Reference to an element which has to be a parent of the given one. This must be areference saved with register before. |
string |
value | (Optional) Value attribute will be checked against this value. | expression-schema |
# WAML 2
# Full notation of 'enter'
- open: www.example.com
- enter:
selector: input.email
input: 'me@example.com'
- enter:
selector: input.password
input: 'secret'
- enter:
selector: input.easy-captcha
value: 1234
input: 3421
- click: button[type=submit]
Property | Description | Type |
---|---|---|
enter | Send a sequence of key strokes to an element. | One of: enter-criteria-schema |
when | (Optional) If set, the step is only executed if the value evaluates to true. | One of: expression-schema, boolean |
unless | (Optional) If set, the step is only executed if the value evaluates to false. | One of: expression-schema, boolean |
failed_when | (Optional) Mark step as failed if condition is evaluated to true. | One of: expression-schema, boolean |
timeout | (Optional) Maximal time [s] to wait for the element which meets the given criteria. Default: 5 | One of: expression-schema, number |
with_items | (Optional) Items over which the step iteration (loop) takes place. The iterator is available within the step as item . |
|
Sequence of: expression-schema |
||
register | (Optional) Save output to a variable. | expression-schema |
Property | Description | Type |
---|---|---|
selector | CSS selector of element to select. | expression-schema |
text | (Optional) Select element which text represenation contains the given value. | expression-schema |
parent | (Optional) Reference to an element which has to be a parent of the given one. This must be areference saved with register before. |
string |
value | (Optional) Value of element to select. | One of: expression-schema, number, boolean |
input | Value to set. | One of: expression-schema, number, boolean |
# WAML 2
# Wait 2.5 seconds demonstration scenario
- open: www.example.com
- wait: 2.5
# WAML 2
# Wait 5 seconds demonstration scenario 2
- open: www.example.com
- when: ${slowConnection}
wait:
time: 5
Short notation examples of wait
.
Property | Description | Type |
---|---|---|
wait | Time to wait in [s] or an object of wait criteria. | One of: wait-criteria-schema, expression-schema, number |
when | (Optional) If set, the step is only executed if the value evaluates to true. | One of: expression-schema, boolean |
unless | (Optional) If set, the step is only executed if the value evaluates to false. | One of: expression-schema, boolean |
failed_when | (Optional) Mark step as failed if condition is evaluated to true. | One of: expression-schema, boolean |
Property | Description | Type |
---|---|---|
time | Time to wait in [s]. | One of: expression-schema, number |
# WAML 2
# Include demonstration scenario
- include: 'Click demonstration scenario'
# WAML 2
# Include demonstration scenario
- when: ${isDesktop}
include:
scenario: 'Click demonstration scenario'
Short notation example of include
and a complex example.
Property | Description | Type |
---|---|---|
include | Scenario name to include or include criteria. | One of: include-criteria-schema, expression-schema |
when | (Optional) If set, the step is only executed if the value evaluates to true. | One of: expression-schema, boolean |
unless | (Optional) If set, the step is only executed if the value evaluates to false. | One of: expression-schema, boolean |
failed_when | (Optional) Mark step as failed if condition is evaluated to true. | One of: expression-schema, boolean |
timeout | (Optional) Maximal time [s] to wait for the element which meets the given criteria. Default: 5 | One of: expression-schema, number |
with_items | (Optional) Items over which the step iteration (loop) takes place. The iterator is available within the step as item . |
|
Sequence of: expression-schema |
Property | Description | Type |
---|---|---|
scenario | The name of the scenario to include. | expression-schema |
# WAML 2
# Short notation of 'execute'
- open: www.example.com
- execute: |
document.body.backgroundColor = 'red';
# WAML 2
# Full notation of 'execute'
- open: www.example.com
- when: ${ true }
execute:
async: true
script: |
var context = arguments[0];
var callback = arguments[1];
fetch('https://example.com/weather.json?city=' + context.city)
.then(function (response) {
return response.json()
})
.then(function (data) {
callback(data.rainProbability);
})
.catch(function (ex) {
callback()
});
The execute
action is used for client-side (browser) execution of a JavaScript code. This is useful for cases where you
need deeper intervention into your page which cannot be performed by other WAML commands.
The injected code is
executed synchronously which is sufficient for most cases. However, in particular situations you may want to
perform an asynchronous call to fetch additional data using XHR or to make some injections. In this case you can
trigger the execution of the injected script in asynchonous mode by setting async
criterion to true
.
In the asynchronous mode it is expected that the JavaScript snippet provided in the script
criterion is a
function which accepts three parameters: resolve
, reject
, and context
. During the execution the
of the time
Please consider that your must execute
either resolve()
for success cases or reject()
for error cases if the snippet execution is done, otherwise the
Please consider that asynchronous calls are wrapped in a function. The first argument of the function is the context containing all variables/objects containing in the current WAML scenario execution context. The second parameter is the callback function which must be called after the execution is perf
Property | Description | Type |
---|---|---|
execute | JavaScript code to execute in the browser context. | One of: expression-schema, execute-criteria-schema |
when | (Optional) If set, the step is only executed if the value evaluates to true. | One of: expression-schema, boolean |
unless | (Optional) If set, the step is only executed if the value evaluates to false. | One of: expression-schema, boolean |
failed_when | (Optional) Mark step as failed if condition is evaluated to true. | One of: expression-schema, boolean |
timeout | (Optional) Maximal time [s] to wait for the element which meets the given criteria. Default: 5 | One of: expression-schema, number |
with_items | (Optional) Items over which the step iteration (loop) takes place. The iterator is available within the step as item . |
|
Sequence of: expression-schema |
||
register | (Optional) Save output to a variable. | expression-schema |
Property | Description | Type |
---|---|---|
script | JavaScript code to execute in the browser context. | expression-schema |
async | (Optional) Define whether the script should be executed in async mode Default: false | One of: expression-schema, boolean |
# WAML 2
# Define demonstration scenario
- define:
language: 'en'
# WAML 2
# Define demonstration scenario 2
- when: ${isOldComputer}
define:
display_resolution: '1024x768'
isDesktop: true
1080p: false
width: 1024
An example of simple usage of define
as well as a more complex example.
Property | Description | Type |
---|---|---|
define | define-criteria-schema | |
when | (Optional) If set, the step is only executed if the value evaluates to true. | One of: expression-schema, boolean |
unless | (Optional) If set, the step is only executed if the value evaluates to false. | One of: expression-schema, boolean |
failed_when | (Optional) Mark step as failed if condition is evaluated to true. | One of: expression-schema, boolean |
with_items | (Optional) Items over which the step iteration (loop) takes place. The iterator is available within the step as item . |
|
Sequence of: expression-schema |
Property | Description | Type |
---|---|---|
^([a-zA-Z0-9_.])+$ | (Optional) Random key matching the given pattern with a value. | One of: expression-schema, boolean, number |
# WAML 2
# Debug scenario
- open: www.example.com
- debug: "hi ${there}"
# WAML 2
# Debug scenario
- open: www.example.com
- debug:
msg: "hi ${there}"
# pause: true
# verbosity: ${level}
An example of simple usage of debug
as well as a more complex example.
Property | Description | Type |
---|---|---|
debug | A message which should be interpolated. | One of: expression-schema, debug-criteria-schema |
when | (Optional) If set, the step is only executed if the value evaluates to true. | One of: expression-schema, boolean |
unless | (Optional) If set, the step is only executed if the value evaluates to false. | One of: expression-schema, boolean |
failed_when | (Optional) Mark step as failed if condition is evaluated to true. | One of: expression-schema, boolean |
with_items | (Optional) Items over which the step iteration (loop) takes place. The iterator is available within the step as item . |
|
Sequence of: expression-schema |
Property | Description | Type |
---|---|---|
msg | (Optional) A message which should be interpolated. | expression-schema |
pause | (Optional) Make a pause until keypress when running in a CLI mode. | One of: expression-schema, boolean |
verbosity | (Optional) Level of verbosity. | One of: expression-schema, number |
# WAML 2
# Uri scenario
- uri: "http://example.com/resources.zip"
# WAML 2
# Uri scenario
- uri:
url: "http://example.com/resources.zip"
body: foo
dest: /tmp/bar.zip
headers:
X-Debug: foo-bar
method: POST
password: secret
user: user
src: /tmp/foo.txt
body_format: raw
status_code: 200
An example of simple usage of uri
as well as a more complex example.
Property | Description | Type |
---|---|---|
uri | URL of the resource. | One of: expression-schema, uri-criteria-schema |
when | (Optional) If set, the step is only executed if the value evaluates to true. | One of: expression-schema, boolean |
unless | (Optional) If set, the step is only executed if the value evaluates to false. | One of: expression-schema, boolean |
failed_when | (Optional) Mark step as failed if condition is evaluated to true. | One of: expression-schema, boolean |
timeout | (Optional) Maximal time [s] to wait for the element which meets the given criteria. Default: 5 | One of: expression-schema, number |
with_items | (Optional) Items over which the step iteration (loop) takes place. The iterator is available within the step as item . |
|
Sequence of: expression-schema |
||
register | (Optional) Save output to a variable. | expression-schema |
Property | Description | Type |
---|---|---|
url | URL of the resource. | expression-schema |
method | (Optional) Method to execute (e.g. GET). | expression-schema |
body | (Optional) Content to sent alongside with the requiest. | expression-schema |
dest | (Optional) Path where to save the response. | expression-schema |
user | (Optional) User for the basic authentication. | expression-schema |
password | (Optional) Password for the basic authentication. | expression-schema |
src | (Optional) File to upload. | expression-schema |
body_format | (Optional) Format in which the source should be transmitted (e.g. "raw"). | expression-schema |
status_code | (Optional) Expected status code. | One of: expression-schema, number |
headers | (Optional) Headers to be sent alongside with the request. | object |
Property | Description | Type |
---|---|---|
– | An expression is a evaluable statement that can be utilized on certain properties. | string |
Property | Description | Type |
---|---|---|
when | (Optional) If set, the step is only executed if the value evaluates to true. | One of: expression-schema, boolean |
unless | (Optional) If set, the step is only executed if the value evaluates to false. | One of: expression-schema, boolean |
failed_when | (Optional) Mark step as failed if condition is evaluated to true. | One of: expression-schema, boolean |
Property | Description | Type |
---|---|---|
register | (Optional) Save output to a variable. | expression-schema |
Property | Description | Type |
---|---|---|
timeout | (Optional) Maximal time [s] to wait for the element which meets the given criteria. Default: 5 | One of: expression-schema, number |
# WAML 2
- open: www.example.com/newsletter
- enter:
selector: 'input[type=email]'
input: 'foo@example.com'
- click: ${item}
with_items:
- '#accept-terms'
- '#accept-marketing-emails'
- '#sign-up'
with_items
is a loop decorator which can be used to iterate over a list of elements.
Property | Description | Type |
---|---|---|
with_items | (Optional) Items over which the step iteration (loop) takes place. The iterator is available within the step as item . |
|
Sequence of: expression-schema |
A single WAML file may contain multiple scenarios. Therefore, the capability of YAML to store multiple documents by splitting them with ---
is used.
You are always welcome to ask questions, provide feedback, or contribute to WAML.
MIT