Scripting guide (with examples)

Setting a timeout for the entire script

As a fail safe, each script has a default timeout of 60 seconds. (note that a lot of commands such as navigate and wait also have their own timeouts)

'Openrunner-Script: v1';
'Openrunner-Script-Timeout: 120s';

Logging

The normal javascript logging functions can be used to help debug your script. You can find these messages in "Tools" -> "Web Developer" -> "Browser Console" (⌘⇧J).

'Openrunner-Script: v1';
console.log('Hello!');

Transactions

A transaction block is used in a script to record a single "stopwatch" measurement. After a script run, each transaction reports a start time and a duration. The script commands that are placed within a transaction block effect the duration of that transaction. A transaction might also report an error (when one of the script commands fails).

Each transaction must be assigned an unique identification string (for example, these unique ID's could be used to store all of the measurements in a database). This ID should usually not be changed if you update your script, unless the body of your transaction has been changed so much that it could be considered a different kind of measurement. Instead, a title may optionally be set and continuously modified. Reporting tools that integrate with Openrunner should use the id to store measurements in their databases and use the title to represent the transaction to the end-user.

'Openrunner-Script: v1';
const tabs = await include('tabs');
await include('wait');
const tab = await tabs.create();

// In this example, "HomePage" is the transaction ID
await transaction('HomePage', async t => {
    t.title = '00 Open the home page';
    await tab.navigate('http://computest.nl/', {timeout: '10s'});
    await tab.wait(async () => {
        await wait.documentComplete()
                  .selector('#layerslider_1 p.slider-text')
                  .isDisplayed();
    });
});

Tabs

The "tabs" module is used to create new tabs, to navigate them to an URL, to run scripts within the tab and to wait until the content of a tab has reached a certain condition.

'Openrunner-Script: v1';
const tabs = await include('tabs');
await include('wait');

// Create a new tab (another tab may be created by calling this function a 
// second time)
const tab = await tabs.create();

// Navigate the tab to the given URL, as if a user entered something in the 
// address bar. This function will wait until the HTML begins to load, if 
// this takes longer than 10 seconds, an error is thrown. (the default 
// timeout is 30s) 
await tab.navigate('http://computest.nl/', {timeout: '10s'});

// Run the given function within the content of the tab and wait until the 
// function is done. Note: if the tab navigates to a new page before the 
// function is done, an error will be thrown
await tab.run(async () => {
    console.log('The url is:', document.location.href)
});

// Run the given function within the content of the tab and wait until the
// function is done. However if the tab navigates to a new page before the
// function is done, execute the function again on the new page.
// `tab.wait()` (instead of `tab.run()`) is recommended when you are 
// waiting for a DOM element to be present because any redirects performed
// by the web page will be handled transparently
await tab.wait(async () => {
    await wait.selector('.cookieConsentButton');
});

// Run the given function within the content of the tab and wait until the 
// tab has navigated to a different page.
// This function is useful if you are clicking on a regular link and you 
// would like to wait until the next page is starting to load
await tab.waitForNewPage(async () => {
    const button = await wait.selector('.cookieConsentButton');
    button.click();
});

// It is also possible to pass data to your function:
await tab.run(async ({foo}) => {
    console.log('foo is:', foo);
}, {foo: 'bar baz'});

// Or, to return data from your function:
const bodyClass = await tab.run(async () => {
    return document.body.className;
});
console.log('body class is', bodyClass);

Assertions

The chaijs library is included to perform assertions with. The expect and assert styles are available. A few useful plugins are also included: chai-subset, chai-arrays, chai-dom.

'Openrunner-Script: v1';
const tabs = await include('tabs');
await include('wait');
const assert = await include('assert'); // http://chaijs.com/api/assert/

assert.deepEqual({foo: 123}, {foo: 123});

const tab = await tabs.create();
await tab.navigate('http://computest.nl/', {timeout: '10s'});
await tab.wait(async () => {
    await wait.documentComplete();
    assert.include(document.body.textContent, 'performance');
});

'Openrunner-Script: v1';
const tabs = await include('tabs');
await include('wait');
const expect = await include('expect'); // http://chaijs.com/api/bdd/

expect({foo: 123}).to.deep.equal({foo: 123});

const tab = await tabs.create();
await tab.navigate('http://computest.nl/', {timeout: '10s'});
await tab.wait(async () => {
    await wait.documentComplete();
    expect(document.body.textContent).to.include('performance');
});