More control over tab.run() / tab.wait() / tab.waitForNewPage behaviour #31

// Current situation:
await tab.wait(async () => {
    await wait.documentComplete()
              .selectorAll('.gallery > img')
              .count(10, Infinity)
              .isDisplayed()
    link = await wait.selector('a[href].nextPage')
})

// this will error because the script is aborted by the page navigation
await tab.run(async () => {
    await interact.click(link)
});

// This is the correct version:
await tab.waitForNewPage(async () => {
    await interact.click(link)
});

await tab.wait(async () => {
    await wait.documentComplete()
              .selectorAll('.gallery > img')
              .count(10, Infinity)
              .isDisplayed()
    const link = await wait.selector('a[href].nextPage')

    // triggers the same behaviour as tab.waitForNewPage()
    await this.expectNewPage() 
    await interact.click(link)
})

// full usage example
await tab.wait(async () => {
    // .result(): sets the result of the outer promise. Also, the .wait() callback body 
    // will not repeat for the next page. However the outer promise will still wait
   // until the callback body completes, or the page navigates away
    await this.result(123)
    // .reject(): same as result() but rejects instead of resolve 
              .error(Error('foo'))
    // triggers the same behaviour as tab.waitForNewPage() and it also 
    // implies .result(undefined) if no result had been set
              .expectNewPage()

    // the `runMetadata` global can then be renamed to `this.meta`
    console.log(new Date(this.meta.waitBeginTime));
})