piri-piri

piri-piri is a browser orchestration to enable decentralized browser applications tests. Ah and it is hot :)

Why does it exist

There are a panoply of excellent browser testing frameworks and services available today, however their focus is on testing browser implementations (CSS, HTML and JavaScript) and user interactions of the apps their are testing (clicks, mouse movements, what the user sees).

When it comes to testing to test a decentralized browser app or library, the focus stops being how a browser implements a specific behaviour, but how the decentralized network handles node joins and leaves and if nodes are effectively communicating between each other. In this scenario, we have several events that the server never sees or that the server never instructs the clients to do, so we need to create a new way to coordinate the browser joins and leaves and also how they interact between each other remotely and this is were piri-piri comes into play.

The specific set of problems piri-piri tries to solve:

• browser times X, where 1<=X<=virtually unlimited - Most browser testing frameworks only let you launch a couple of browsers at a time, piri-piri aims to launch several browsers and/or tabs to load a webpage, in a local or distributed fashion.

• instruct browsers on demand - Since there is a ton of stuff happening on browser decentralized apps, we can't just write a script to test and listen to events that happens in a single browser, there are triggers coming from all of them.

• gather information and evaluate the state as a whole - collect the events and data generated by each browser and assess if the order was correct with pseudo external consistency

**why piri-piri? Well, to be honest, since I got to learn about SauceLabs in 2012 (during LXJS over some Nachos and Tabasco Hot Sauce), browser testing for me was always connected to spicy and sauce, so that inspired me to pick the one that is very famous on the portuguese cousine, that is, piri-piri :)

How to use it (API)

const pp = require('piri-piri')

Starting piri-piri

piri-piri needs to get initialized in order to create a WebSockets server which will be used as the bridge to transfer messages between your Node.js process where tests and assertions are being run and the browsers that get instantiated. To start it, do:

pp.start((err) => {
  done()
})

Launching an instance

In fact, what will get launched are headless electron processes.

pp.browser.spawn(<scriptPath>, <quantity>, (err) => {
  if (err) { }
  // ..
})

scriptPath is the path to the script that you want to run in the browser

How should your script to run on the browser look like

const ppc = require('../../src').client
 
module.exports = function (args) {
  ppc.connect((err, socket) => { // do this when you want to tell piri-piri that your app is ready
    if (err) {
      return console.log(err)
    }
    socket.on('exit', ppc.exit)
  })
}

Instruct a comamnd, a 'sum function' example

browser app

const ppc = require('../../src').client
 
module.exports = function (args) {
  ppc.handle('sum', (arr) => {
    var sum = Number(arr[0] + arr[1])
    ppc.send(sum)
  })
 
  ppc.connect((err) => {
    if (err) {
      return console.log(err)
    }
  })
}

tests side

pp.browser.spawn('./tests/scripts/method.js', 1, (err) => {
  if (err) { }
  var id = Object.keys(pp.clients)[0] // should be 0, electron is not being properly closed
  pp.browser.send(id, 'sum', 2, 2)
  setTimeout(() => {
    console.log(pp.clients[id].msgs[0]) // the 
    pp.browser.send(id, 'exit')
  }, 500)
})

Initial Development

The initial development for this project was supported by INESC-ID, during the development of David Dias' M.Sc