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:

1. Open a web page.
2. 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.