@bigtest/convergence

Returns a new convergence instance with an additional assertion. This assertion is run repeatedly to ensure it passes throughout the timeout. If the assertion fails at any point during the timeout, the convergence will fail.

// would converge after `foo` remains `'foo'` for at least 100ms
new Convergence(100).always(() => foo === 'foo')

When an always assertion is encountered at the end of a convergence, the timeout defaults to the remaining time for the current running instance; minumum 20ms. When not at the ned of a convergence, it defaults to one-tenth of the total timeout.

let convergeFooThenBar = new Convergence(1000)
// would continue after `foo` remains `'foo'` for at least 100ms
  .always(() => foo === 'foo')
// then have any time remaining to converge on `foo` being `'bar'`
  .when(() => foo === 'bar')

Given a timeout, it is capped at the remaining timeout for the current running instance.

let convergeFooThenBar = new Convergence(100)
// would continue after `foo` remains `'foo'` for at least 50ms
  .always(() => foo === 'foo', 50)
// then have 50ms remaining to converge on `foo` being `'bar'`
  .when(() => foo === 'bar')
// and a maximum of ~50ms to converge on it remaining `bar`
  .always(() => foo === 'bar', 100)

Appends another convergence’s queue to this convergence’s queue to allow composing different convergences together.

// would converge when `foo` equals `'bar'`
let convergeBar = new Convergence().when(() => foo === 'bar')

// would converge when `foo` equals `'baz'`
let convergeBaz = new Convergence().when(() => foo === 'baz')

// would converge when `foo` equals `'bar'` and then `'baz'`
let convergeBarBaz = convergeBar.append(convergeBaz)

Returns a new convergence instance with a callback added to its queue. When a running convergence instance encounters a callback, it will be invoked with the value returned from the last function in the queue. The resulting return value will also be provided to the following function in the queue. If the return value is undefined, the previous return value will be retained.

new Convergence()
  // continues after finding a random even number
  .when(() => {
    let n = Math.ceil(Math.random() * 100)
    return !(n % 2) && n
  })
  // multiplies the even number by another random number
  .do((even) => {
    return even * Math.ceil(Math.random() * 100)
  })
  // does not return, the previous value will be retained
  .do((rand) => {
    console.log('even number times random number = ', rand);
  })
  // asserts that any number times an even number is even
  .always((rand) => {
    let rand = Math.ceil(Math.random() * 100);
    return !(rand % 2)
  }, 100)

When a promise is returned from a callback, the convergence will wait for the promise to resolve before continuing.

new Convergence()
  .when(() => foo === 'bar')
  .do(() => doSomethingAsync())
  .do((baz) => console.log('resolved with', baz))

Returning other convergences from a callback is also supported. The returned convergence will be run with the current remaining timeout. This is useful when computing convergences after converging on another state.

new Convergence()
  // continue when `num` is less than 100
  .when(() => num < 100)
  .do(() => {
    // if odd, wait until it is even
    if (num % 2) {
      return new Convergence()
        .when(() => !(num % 2) && num)
    } else {
      return num;
    }
  })

Runs the current convergence instance, returning a promise that will resolve after all assertions have converged, or reject when any of them fail.

let convergence = new Convergence().when(() => foo === 'bar');

// will converge within the timeout or fail afterwards
convegence.timeout(100).run()
  .then(() => console.log('foo is bar!'))
  .catch(() => console.log('foo is not bar'))

When an assertion fails and the convergence rejects, it is rejected with the last error thrown from the assertion.

let convergence = new Convergence().when(() => {
  expect(foo).to.equal('bar')
})

// will fail after 100ms if `foo` does not equal `'bar'`
convegence.timeout(100).run()
  .catch((e) => console.error(e)) // expected '' to equal 'bar'

When the convergence is successful and the promise resolves, it will resolve with a stats object containing useful information about how the convergence and it’s assertions ran.

let convergence = new Convergence()
  .when(() => foo === 'bar')
  .always(() => foo === 'bar')

convergence.run().then((stats) => {
  stats.start   // timestamp of the convergence start time
  stats.end     // timestamp of the convergence end time
  stats.elapsed // amount of milliseconds the convergence took
  stats.timeout // the timeout this convergence used
  stats.runs    // total times this convergence ran an assertion
  stats.value   // last returned value from the queue
  stats.queue   // array of other stats for each assertion
})

By being thennable we can enable the usage of async/await syntax with convergences. This allows us to naturally chain convergences without calling #run().

async function click(selector) {
  // will resolve when the element exists and gets clicked
  await new Convergence()
    .when(() => {
      let $node = document.querySelector('.element')
      return !!$node && $node
    })
    .do(($node) => {
      $node.click()
    })
}

The convergence thennable method immediately invokes #run() and resolves with the last returned value from the convergence’s queue. This allows us to await for values from a convergence.

let find = (selector) => new Convergence().when(() => {
  let $node = document.querySelector('.element')
  return !!$node && $node
})

async function fill(selector, value) {
  let $node = await find(selector)
  $node.value = value
}

Returns a new convergence instance with the given timeout, inheriting the current instance’s assertions. If no timeout is given, returns the current timeout for this instance.

let quick = new Convergence(100)
let long = quick.timeout(5000)

quick.timeout() // => 100
long.timeout() // => 5000

Returns a new convergence instance with an additional assertion. This assertion is run repeatedly until it passes within the timeout. If the assertion does not pass within the timeout, the convergence will fail.

// would converge when `foo` equals `'bar'`
let convergeFoo = new Convergence().when(() => foo === 'bar')

// would converge when `foo` equals `'bar'` and then `'baz'`
let convergeFooBar = convergeFoo.when(() => foo === 'baz')