GitHub - automate-website/waml: Web Automation Markup Language

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:

2.0
draft-02

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
- Ensure
State mutation actions
- Open
- Click
- Enter
- Select
- Move
- Define
- Uri
Support actions
- Wait
- Debug
- Include
- Alert
- Execute
- Export

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
- Register
- Timeout
Loop decorator
- With items

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

License

automate-website/waml

Sign In Required

Launching GitHub Desktop

Launching GitHub Desktop

Launching Xcode

Launching Visual Studio Code

Latest commit

Git stats

Files

README.md

WAML 2.0

Abstract

Overview

Syntax

Scenario

Step

Action

Criterion

Decorator

Expression

Schema

Scenario Schema

Step Schema

Fragment Scenarios (TBD)

Actions and Criteria

Open

Open Step Schema

Open Criteria Schema

Ensure

Ensure Step Schema

Ensure Criteria Schema

Move

Move Step Schema

Move Criteria Schema

Click

Click Step Schema

Click Criteria Schema

Select

Select Step Schema

Select Criteria Schema

Enter

Enter Step Schema

Enter Criteria Schema

Wait

Wait Step Schema

Wait Criteria Schema

Include

Include Step Schema

Include Criteria Schema

Execute

Execute Step Schema

Execute Criteria Schema

Define

Define Step Schema

Define Criteria Schema

Debug

Debug Step Schema

Debug Criteria Schema

Uri

Uri Step Schema

Uri Criteria Schema

Expressions

Expression Schema

Decorators

Conditional Decorators

Register Decorator

Timeout Decorator

With Items

Management of Multiple Scenarios

Conclusion

Feedback

License

About

Resources

License

Stars

Watchers

Forks

Releases

Packages