Add beforeCapture JavaScript hook

[ChrisBAshton]

Allows the tester to run arbitrary JavaScript on the page before the screenshot is captured. This allows us to regression-test interactive content.

Usage

snap_file: "javascript/casper.js"
before_capture: 'javascript/setHeaders--stage.js' # this JS is run for every path

paths:
  clickable_starwars__panel_open:
    path:           /news/entertainment-arts-some-id
    selector:       '.ns-panel'
    before_capture: 'javascript/clickable_guide__open_panel.js' # this JS is run only for this path
  clickable_starwars:
    path:     /news/entertainment-arts-some-id
    selector: '.ns-panel'

The global JS will be evaluated before the local JS.

Justification

Some regression tests might incorrectly pass because inconsistencies are not noticeable until some action has been performed (false negative).

Take the In-Depth Toolkit's Clickable Guides, which open panels of informative content when labels are clicked. We had a case recently where the panel text had peculiar margins (inherited from the styling on the host page) but passed regression tests because only the "landing" view was compared.

With this PR, we are able to run JavaScript which clicks on a label and opens a panel: we then take the screenshot and thus are able to regression test content in a particular state.

Before merging

Should probably have some tests in place (though I can't see any tests for using CasperJS to take screenshots of page components - this should probably be added first). The README probably needs updating too - it needs updating anyway to reflect the CasperJS options.

In working this new code into the example configuration, I've cut the default config down to one language (the clickable guide is only on /news). Unfortunately there doesn't seem to be any clickable element on the Russian/Arabic homepages which doesn't take you to a new URL (so it's hard to exhibit the beforeCapture functionality)! Perhaps we can put together a better example configuration which shows off more of Wraith's functionality. In summary, we need:

• tests for beforeCapture functionality
• updated README
• better example config

But I don't want to do all that if this feature can't be merged for some reason, so let me know! :)

[ChrisBAshton]

NB: this is also pretty useful for sending custom headers with each request! Example code:

module.exports = function (casper) {
    // load the page with the correct header overrides
    casper.open(casper.page.url, {
        method: 'get',
        headers: {
            "data_override":      "https://some-data-override-service.bbc.co.uk"
        }
    });
}

(A better way of sending additional headers should be baked into Wraith, but this is a halfway decent hack for the time being. Having the beforeCapture hook gives a lot of freedom.)

[ChrisBAshton]

Updated docs: http://bbc-news.github.io/wraith/index.html#beforeCapturehooks

Also pushed to Rubygems.