NAV Navbar
yaml
  • Introduction
  • Unravel Language
  • Element Identification
  • Introduction

    Installation

    npm i -g @unravel/unravel-cli
    

    Install the Unravel CLI

    Unravel requires Node.js (version 8 or higher) and Google Chrome (version 60 or higher) to be installed locally. Install the Unravel CLI from NPM.

    Authentication

    export UNRAVEL_KEY=myApiKey
    
    unravel --key myApiKey
    

    Set your API key as an environmental variable or pass it with the -key flag. Get your API key at our developer portal or sign up for a free Unravel account.

    Test Format

    definition: |
      load url http://the-internet.unravel.io/login
      set "tomsmith" for "username"
      set "SuperSecretPassword!" for "password"
      click "login"
      assert "you logged into a secure area"
    

    This is an example Unravel test. Unravel tests are YAML files, and at a bare minimum consist of a definition with at least one "load url" command.

    You can download this test here.

    Running a test

    $ unravel --key $myApiKey login-success.yaml
    

    Run a test

    Unravel tests are run from the terminal.

    By default, Unravel launches a local Chrome instance (with a fresh profile so it won't affect your own Chrome settings), and runs the test file specified.

    Unravel Language

    The following are the commands that you can use in Unravel tests. Unravel commands should be written one to a line and are case-insensitive.

    Loading Pages/URLs

    Load URL https://www.example.com

    This command attempts to load the page or resource at the specified URL. All Unravel tests must begin with loading a URL.

    Smart clicking

    Click "Login" button

    This command picks the best candidate button and clicks it. Unravel uses contextual clues and fuzzy matching to find and click the most likely candidate button.

    The element clicked can be a button or link (or other clickable element, eg an element with an “ng-click” attribute in Angular apps).

    Explicit clicking

    Click "Login" button where text is similar to "sign in"

    If when writing the test, Unravel does not automatically choose the correct button, link, or element to click, you can use the above syntax to override the initial selection.

    Filling forms

    Smart form filling

    Fill "registration" form

    This command attempts to fill the named form. Each field is classified and filled with either explicit values from the data profile or with default values.

    The string ("registration" in this case) is used to identify the form on the page - it should be present within the form.

    Smart form field filling

    Set "172-D-1" for "registration number"

    This command attempts to find an individual form field and fill it with either an explicit value from the data profile or with the default value. The "hint" provided must be identical to the key in the data profile.

    Set "registration number"

    A form field can be a text box, text area, checkbox, radio button, etc.

    Explicit form field filling

    ```Set "172-D-1" for "registration number" where XPATH is "//*[@tooltip='regNum']"

    If when writing the test, Unravel does not automatically choose the correct form field to fill, you can use the above syntax to override the initial selection. A form field can be a text box, text area, checkbox, radio button, etc.

    Hovering

    Smart hovering

    Hover over "button"

    Moves the mouse cursor over the specified element.

    Explicit hovering

    Hover over element where text is similar to "menu"

    If when writing the test, Unravel does not automatically choose the correct element to hover over, you can use the above syntax to override the initial selection.

    Waiting

    Wait for n seconds
    Wait for 10 seconds
    Wait for 1 second
    

    Waits for the specified number of seconds. This command cannot fail.

    Key Pressing

    Press Return
    Press Tab
    Press Up arrow
    

    This command presses a keyboard key. The available keys are: - Return / Enter - Tab - Up arrow - Down arrow - Left arrow - Right arrow

    Assertions

    The following commands are the assertions that you can use in Unravel tests.

    Unravel offer two kinds of assertions: - Find - Assert

    When a Find command fails, it does not halt the test. When an Assert command fails, it does halt the test.

    Smart element assertion

    Find "download" button
    Assert "download" button
    

    This command attempts to find an individual element on the page. The element must be visible to be found.

    Explicit element assertion

    Assert "download" button where text contains "click here"
    Find "download" button where text contains "click here"
    

    If when writing the test, Unravel does not automatically choose the correct element for the assertion, you can use the above syntax to override the initial selection.

    Negative Assertions

    Find no "download" button
    Assert no "download" button
    Find no "download" button where text contains "click here"
    

    This command ensures that an individual element is not visible on the page.

    Page Metadata

    URL

    Find URL is "https://www.example.com"
    Find URL contains "example.com"
    Find URL starts with "https://"
    Find URL ends with ".com"
    

    This command ensures that the URL is equal to, contains, starts with, or ends with the given string.

    Page Title

    Find page title is "Example.com Website"
    Find page title contains "ample"
    Find page title starts with "example.com"
    Find page title ends with "Website"
    Find page title is similar to "example.com"
    

    This command ensures that the page title is equal to, contains, starts with, ends with, or is similar to the given string.

    Cookies

    Find cookie "cookie"
    Assert cookie "cookie"
    

    This command ensures that a cookie with the given name exists.

    Find no cookie "cookie"
    Assert no cookie "cookie"
    

    This command ensures that the given cookie is not set.

    Find cookie "cookie" value is "value"
    Assert cookie "cookie" value is "value"
    

    This command ensures that a cookie with the given name exists, and has the correct value.

    Element Identification

    Unravel has several ways to let you identify elements that you want to interact with, based on text or XPATH.

    By text

    Exact match

    element where text is
    
    element where text is "click me"
    

    This identifies an element by its text. The text must be an exact match (ignoring case) with the element to be identified.

    Contains

    element where text contains
    
    element where text contains "test"
    

    This identifies an element by a substring of its text (ignoring case).

    Starts with

    element where text starts with
    
    element where text starts with "start"
    

    This identifies an element by the beginning of its text (ignoring case).

    Ends with

    element where text ends with
    
    element where text ends with "ending."
    

    This identifies an element by the end of its text (ignoring case).

    Similar to

    element where text is similar to
    
    element where text is similar to "neighbors"
    

    This identifies the element whose text is most similar to the given text (ignoring case).

    By XPATH

    element where XPATH is
    
    element where XPATH is "/html/body/div[1]/img[1]"
    element where XPATH is "//*[@tooltip='help']"
    

    An element can be identified by its XPATH.