Designed to serve as both a quick orientation and field reference.

Run some tests

Runner files are very easy to run:

npm run-script runner path/to/file/config/file

To run the example.js runner file (in the runners/configuration-files/examples folder) (in your Terminal, in the root of the repo):

npm run-script runner runners/configuration-files/examples/example.js

Runner config information here.

Mocha

We use Mocha as a testing framework, which means your code will be structured in 'suites' and 'tests'.

Suites

A 'suite' (we use this as a step) uses a describe block, which accepts a label and an anonymous function to execute.

Arrow functions are discouraged in Mocha, but will mostly be fine if you prefer. The examples and documentation won't use them.

If your suite title starts with STEP {N} as below, the tool will generate a new proxy step.

describe('STEP 1 - Visit the homepage', function () {
  // tests will go here
})

describe('Step 8: Complete the purchase', function () {
  // tests will go here
})

The steps will be numbered sequentially, starting from 1 (the actual number you use is disregarded). The above example will result in step1 and step2, even though STEP 1 and Step 8 were provided as user input.

Tests

A 'test' (we use this for navigation actions, or for groups of assertions) uses an it block, which also accepts a label and an anonymous function to execute.

Often, these start with 'should'. Arrow functions are fine for most cases, but there are times that you need to use the standard function notation.

It's always safest to use the standard notation.

it('should navigate to the page', async function () {
  // navigation commands here
})

Tests only work inside suites:

describe('STEP 1: Visit the homepage', function () {
  it('should navigate to the page', async function () {
    // navigation commands here
  })

  it('should see the consent banner', async function () {
    // assertions about banner visibility here
  })
})

Chai

Basic Assertions

Examples use chai's 'expect' syntax, there are others available.

There are many other building blocks available in Chai, full docs here.

// passes
chai.expect(1).to.equal(1)

// passes
chai.expect(1 + 2).to.equal(3)

// passes
chai.expect(1 + 2).to.be.a('number').that.is.greaterThan(2)

// passes
chai.expect('1' + '2').to.equal('12')

Object / Array Assertions

Thanks to the Chai plugins we're using, you can also do things like check only specific object keys (ignoring timestamps and randoms, for instance):

// a complex object with timestamps
let myObject = {
  'importantInfo' : {
    'value1': 'a very important string',
    'value2': 'an even more important string',
    'timestamp' : 1605267873919
  },
  'alsoImportantInfo' : 49,
  'unimportantInfo' : 'just some junk',
  'timestamp' : 1605267873919
}

let expectedObject = {
  'importantInfo' : {
    'value1': 'a very important string',
    'value2': 'an even more important string',
  },
  'alsoImportantInfo' : 49
}

// passes, because it ignores any extra parameters
chai.expect(myObject).to.be.like(expectedObject)

let myArray = []
myArray.push({
  'notTheOneWeNeed' : true
})
myArray.push(myObject)

// can also make sure that a matching object exists in the array (can be slow on large arrays of complex objects)
chai.expect(myArray).to.include.something.like(expectedObject)

Webdriver.io

All of these commands must be run inside a test (it block). You should always use an async function for your it callback, so you can use await for browser functions.

When in doubt, it's fine to use await (awaiting synchronous functions is fine, but failing to await async function is not).

Selectors, version numbers and similar would generally be put in a helper file, but are inline in these examples for readability.

Full documentation here.

Go to a page

await browser.url('https://google.com')

Go to a page and wait for all traffic/scripts

await browser.url('https://google.com')
await browser.waitForTraffic()

Verify that an element is displayed

const banner = await $('.uc-banner-content')
chai.expect(await banner.isDisplayed()).to.equal(true)

Click on a button using an ID selector

const incrementButton = await $('#increment-button')
await incrementButton.click()
await browser.waitForTraffic() // wait for any network calls to complete before moving on

Set / get cookies

You must have already navigated to a page on the domain you'd like to set the cookie on to use this command successfully.

// uses the global 'traceId' provided by the testing suite to set and confirm a Trace cookie.
await browser.setCookies({ name: 'trace_id', value: global.traceId || '' })
const cookie = await browser.getCookieByName('trace_id')
chai.expect(cookie.value).to.equal(global.traceId)

Execute a script / get a value from the DOM

You must have already navigated to a page.

// the current version of the Usercentrics integration running
const integrationVersion = await browser.execute(function () {
  return window.tealiumCmpIntegration && window.tealiumCmpIntegration.version
})
// node.js context - client and console are available
reporterHelper.logMessage(integrationVersion)
chai.expect(integrationVersion).to.equal('0.12-beta')

Tutorial: 4 - Cheatsheet

4 - Cheatsheet