WAML (draft-0.2)
Notice: WAML is currently in a very early draft version. Feel free to create a pull request in case of useful suggestions.
Refer to the changelog for recent notable changes and modifications.
Abstract
# Example of login process automation
name: Sign in
steps:
- open: 'https://example.com/login'
- enter:
selector: input[name=email]
input: username@example.com
- enter:
selector: input[name=password]
input: s3cr3t
- click: button[type=submit]
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.
Terminology
The underlying format for WAML is YAML so that it inherits all its benefits such as hosting of multiple document within one stream. A WAML stream may contain multiple scenarios. Every scenario must be represented by a set of metadata as well as sequence of actions to execute. Every action must have at least one criteria which is represented as scalar (string, integer, etc.) value or a mapping.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
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
name: Name of the scenario
steps:
- open: www.example.com
A very basic scenario must contain a name
and steps
property. The list of actions may be empty, however, it is reasonable to have at least one action.
Minimal Example
name: full-featured-scenario
description: A full featured scenario
fragment: false
precendence: 100
timeout: 5
if: ${ true }
steps:
- open: www.example.com
This minimal example demonstrates the simplicity of WAML. The full list of supported metadata is depicted below.
Property | Description | Type |
---|---|---|
name | Unique name that is used to reference a certain scenario. | string |
description | (Optional) Short summary of the overall scenario purpose. | string |
fragment | (Optional) Defines if a scenario is a fragment or may be executed stand-alone. Default: false | boolean |
precendence | (Optional) Defines the particular priority of the scenario during execution of independent scenarios. Default: -1 | integer |
timeout | (Optional) Maximal time [s] to wait for conditions to be true. Default: 5 | One of: expression-schema, integer |
steps | Sequence of actions. | Sequence of: step-schema |
if | (Optional) If set, the scenario is only executed if the value evaluates to true | One of: expression-schema, boolean |
unless | (Optional) If set, the scenario is only executed if the value evaluates to false | One of: expression-schema, boolean |
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: open-step-schema, include-step-schema, store-step-schema, ensure-step-schema, click-step-schema, select-step-schema, enter-step-schema, move-step-schema, wait-step-schema |
Fragment Scenarios
name: fragment-scenario
fragment: true
steps:
- open: www.example.com
Fragment scenarios can not be executed independently but can only be used in include
actions of other scenarios or fragments.
Actions and Criteria
Open
# Short notation
name: Open demonstration scenario
steps:
- open: www.example.com
# Full notation
name: 'Open demonstration scenario 2'
steps:
- open:
url: www.example.com
unless: ${isMobile}
- open:
url: m.example.com
if: ${isMobile}
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 |
Open Criteria Schema
Property | Description | Type |
---|---|---|
url | The URL to which the navigation takes place. | expression-schema |
if | (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 |
Ensure
# Short notation of 'ensure'
name: Ensure demonstation scenario
steps:
- open: www.example.com
- ensure: h1.greeting
# Full notation
name: Ensure scenario with additional contstraints
steps:
- open: www.example.com
- ensure:
selector: h1.greeting
timeout: 400
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 |
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 |
timeout | (Optional) Maximal time [s] to wait for the element which meets the given criteria. | One of: number, 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) Presence of the parent element according given creteria. | One of: expression-schema, parent-criteria-schema |
if | (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 |
Move
# Short notation
name: Move demonstation scenario
steps:
- open: www.example.com
- move: a.help
- ensure:
selector: .help-tooltip
text: 'Click here to get help.'
# Full notation
name: Move demonstation scenario
steps:
- open: www.example.com
- move:
selector: a.help
text: 'Need help?'
parent:
selector: .help-container
- 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 |
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 |
timeout | (Optional) Maximal time [s] to wait for the element which meets the given criteria. | One of: number, expression-schema |
parent | (Optional) Presence of the parent element according given creteria. | One of: expression-schema, parent-criteria-schema |
if | (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 |
Click
name: Click demonstration scenario
steps:
- open: www.example.com
- click: a.sign-up
name: Click demonstration scenario 2
steps:
- open: www.example.com
- click:
selector: a.sign-up
text: 'Join now for free!'
if: ${isDesktop}
- click:
selector: a.sign-up
text: 'Join now!'
if: ${isMobile}
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 |
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 |
timeout | (Optional) Maximal time [s] to wait for the element which meets the given criteria. | One of: number, expression-schema |
parent | (Optional) Presence of the parent element according given creteria. | One of: expression-schema, parent-criteria-schema |
if | (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 |
Select
# Short notation
name: Select demonstration scenario
steps:
- open: www.example.com
- select: '.actions option:first-child'
# Full notation of 'select'
name: 'Select demonstration scenario 2'
steps:
- 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 |
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 |
timeout | (Optional) Maximal time [s] to wait for the element which meets the given criteria. | One of: expression-schema, number |
parent | (Optional) Presence of the parent element according given creteria. | One of: expression-schema, parent-criteria-schema |
value | (Optional) Value attribute will be checked against this value. | One of: expression-schema, number, boolean |
if | (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 |
Enter
# Full notation of 'enter'
name: Enter demonstration scenario
steps:
- 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 |
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 |
timeout | (Optional) Maximal time [s] to wait for the element which meets the given criteria. | One of: expression-schema, number |
parent | (Optional) Presence of the parent element according given creteria. | One of: expression-schema, parent-criteria-schema |
value | (Optional) Value of element to select. | One of: expression-schema, number, boolean |
input | Value to set. | One of: expression-schema, number, boolean |
if | (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 |
Wait
# Short notation of 'wait'
name: Wait 2.5 seconds demonstration scenario
steps:
- open: www.example.com
- wait: 2.5
# Full notation of 'wait'
name: 'Wait 5 seconds demonstration scenario 2'
steps:
- open: www.example.com
- wait:
time: 5
if: ${slowConnection}
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 |
Wait Criteria Schema
Property | Description | Type |
---|---|---|
time | Time to wait in [s]. | One of: expression-schema, number |
if | (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 |
Include
name: Include demonstation scenario
steps:
- include: 'Click demonstration scenario'
name: Include demonstation scenario
steps:
- include:
scenario: 'Click demonstration scenario'
if: ${isDesktop}
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 |
Include Criteria Schema
Property | Description | Type |
---|---|---|
scenario | The name of the scenario to include. | expression-schema |
if | (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 |
Store
name: Store demonstration scenario
steps:
- store:
language: 'en'
name: Store demonstration scenario 2
steps:
- store:
display_resolution: '1024x768'
isDesktop: true
1080p: false
width: 1024
if: ${isOldComputer}
An example of simple usage of store
as well as a more complex example.
Store Step Schema
Property | Description | Type |
---|---|---|
store | A mapping of variables to be defined in the execution context. | object |
Store Criteria Schema
Property | Description | Type |
---|---|---|
if | (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 |
^([a-zA-Z0-9_.])+$ | (Optional) Random key matching the given pattern with a value. | One of: expression-schema, boolean, number |
Expressions
Expression Schema
Property | Description | Type |
---|---|---|
– | An expression is a evaluable statement that can be utilized on certain properties. | string |
Shared Criteria
Parent 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 |
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.