Journey Scripting > Tutorials > Getting Started

Getting Started

To run User Journey tests, our monitoring system follows journey 'scripts' that are required to be written in a simple, but very particular way. They are written using JSON - a minimal, readable format for structuring data. This ensures that our journey system receives consistently recognisable journey instructions.

If JSON is new to you, please read our simple JSON explanation: Lets Talk About JSON.

Contents

Basic Structure

We require a journey to contain 'steps', which in turn contain 'actions'. A 'step' corresponds to a single page in your website and 'actions' are instructions that can be undertaken on that page (see example below).

During a user journey test we will record the elements (e.g. fonts, images, CSS files and JS files) requested by each page we visit. We use steps as a way of identifying when to stop and start recording, so we are able to track the elements loaded by each page. For this reason, we strongly recommend that each step starts with a Click action that initiates the website to navigate to a new page. This is to ensure that the elements recorded are stored in the correct HTTP Archive file.

Step 1
 -> Comment
 -> Actions
    -> Action 1
    -> Action 2
    -> Action 3
Step 2
 -> Comment
 -> Actions
    -> Action 1
    -> Action 2
    -> Action 3
Step 3
 -> Comment
 -> Actions
    -> Action 1
    -> Action 2
    -> Action 3
    -> Action 4

Common Actions

  • Click - clicks on any HTML element as specified.
  • Capture - takes a screenshot of whatever is currently visible.
  • Wait - a pause, in milliseconds, usually to allow elements to load such as markup, images, or AJAX.
  • Assert - checks something exists on the page. E.g. looking for an image to check a page has fully loaded.

Given this, the above basic structure example can be transformed into this:

Step 1:
 -> Comment: "Visit the Home page"
 -> Actions:
    -> Wait: "Wait 3000ms for the page to load"
    -> Capture: "Take a screenshot of the Home page"
    -> Assert: "Check the banner image exists"
Step 2:
 -> Comment: "Visit the Pricing page"
 -> Actions:
    -> Click: "Click on 'pricing' in the main menu"
    -> Wait: "Wait 2000ms for the page to load"
    -> Capture: "Take a screenshot of the Pricing page"
Step 3:
 -> Comment: "Visit the Contact page"
 -> Actions:
    -> Click: "Click on 'contact' in the main menu"
    -> Wait: "Wait 2500ms for the page to load"
    -> Capture: "Take a screenshot of the Contact page"
    -> Assert: "Check the Contact Form exists"

Final JSON Script

Finally, the example can be translated into the JSON instructions the user journey system expects.

This means that the basic structure would be this:

[
    {
        Step 1,
        Actions:[
            Action 1,
            Action 2,
            Action 3
        ]
    },
    {
        Step 2,
        Actions:[
            Action 1,
            Action 2,
            Action 3
        ]
    },
    {
        Step 3,
        Actions:[
            Action 1,
            Action 2,
            Action 3,
            Action 4
        ]
    }
]

Which can be translated into this:

[
    {
        "Comment":"Visit the Home page",
        "Actions":[
            {
                "Type":"Wait",
                "Time":3000
            },
            {
                "Type":"Capture",
                "Comment":"Take a screenshot of the Home page"
            },
            {
                "Type":"Assert",
                "Comment":"Check the banner image exists",
                "Selector":".header img[src='banner.jpg']"
            }
        ]
    },
    {
        "Comment":"Visit the Pricing page",
        "Actions":[
            {
                "Type":"Click",
                "Selector":"ul.menu a.pricing"
            },
            {
                "Type":"Wait",
                "Time":2000
            },
            {
                "Type":"Capture",
                "Comment":"Take a screenshot of the Pricing page"
            }
        ]
    },
    {
        "Comment":"Visit the Contact page",
        "Actions":[
            {
                "Type":"Click",
                "Selector":"ul.menu a.contact"
            },
            {
                "Type":"Wait",
                "Time":2500
            },
            {
                "Type":"Capture",
                "Comment":"Take a screenshot of the Contact page"
            },
            {
                "Type":"Assert",
                "Comment":"Check the Contact Form exists",
                "Selector":".wrapper .contact-form form"
            }
        ]
    }
]

Pointers

  1. Keep your journeys simple and short, with precise steps.
  2. Each step should correspond to visiting and interacting with a single page.
  3. Use the wait action frequently to allow content to load (it will probably take longer than you think!)
  4. Changes to your site markup may "break" your Click and Assert selectors, causing your Journey to fail.

Using Asserts

Assert actions require a Javascript library (jQuery, MooTools) to be installed on your website/app. This is because the action use the library's accessor to evaluate selectors on the page.

By default, we use $. So an example action that looks like this...

{
    "Type":"Assert",
    "Comment":"Ensure a particular class exists",
    "Selector":"#myID myClass"
}

...would translate this: $("#myID .myClass");

When writing your Journey you can override the default accessor ($), with whatever your site uses. For example, "$$", "jQuery" or "jQ".

Notes

Whenever a journey fails, a Capture is taken automatically to show you what was on the page at the time.

Selenium logs and Browser errors are also captured and logged at all times.