WAML 2.0
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.
Abstract
# 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.
Overview
Syntax
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.
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.
Step
# 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.
Action
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
Criterion
# 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
Decorator
# 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
Expression
# 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).
Schema
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.
Scenario Schema
# 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:
Step Schema
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 |
Fragment Scenarios (TBD)
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.
Actions and Criteria
Open
# 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.
Open Step Schema
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 |
Open Criteria Schema
Property | Description | Type |
---|---|---|
url | The URL to which the navigation takes place. | expression-schema |
Ensure
# 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.
Ensure Step Schema
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 |
Ensure Criteria 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 |
Move
# 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.
Move Step Schema
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 |
Move Criteria 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 |
Click
# 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.
Click Step Schema
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 |
Click Criteria 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 |
Select
# 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.
Select Step Schema
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 |
Select Criteria 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 |
Enter
# 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]
Enter Step Schema
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 |
Enter Criteria 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 |
Wait
# 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
.
Wait Step Schema
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 |
Wait Criteria Schema
Property | Description | Type |
---|---|---|
time | Time to wait in [s]. | One of: expression-schema, number |
Include
# 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.
Include Step Schema
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 |
Include Criteria Schema
Property | Description | Type |
---|---|---|
scenario | The name of the scenario to include. | expression-schema |
Execute
# 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
Execute Step Schema
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 |
Execute Criteria 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 |
Define
# 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.
Define Step Schema
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 |
Define Criteria Schema
Property | Description | Type |
---|---|---|
^([a-zA-Z0-9_.])+$ | (Optional) Random key matching the given pattern with a value. | One of: expression-schema, boolean, number |
Debug
# 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.
Debug Step Schema
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 |
Debug Criteria 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 |
Uri
# 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.
Uri Step Schema
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 |
Uri Criteria 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 |
Expressions
Expression Schema
Property | Description | Type |
---|---|---|
– | An expression is a evaluable statement that can be utilized on certain properties. | string |
Decorators
Conditional Decorators
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 |
Register Decorator
Property | Description | Type |
---|---|---|
register | (Optional) Save output to a variable. | expression-schema |
Timeout Decorator
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 |
With Items
# 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 |
Management of Multiple Scenarios
A single WAML file may contain multiple scenarios. Therefore, the capability of YAML to store multiple documents by splitting them with ---
is used.
Conclusion
Feedback
You are always welcome to ask questions, provide feedback, or contribute to WAML.
License
MIT