n1k0/casperjs — pull request #264 by starlocke (2012-11-01 21:04:02+00:00)
Title: Introducing Casper.blockStep

There exists circumstances where the next CasperJS step executes too early, causing false positives for failures in subsequent testing.

This commit introduces ```Casper.blockStep()```, also integrated into ```click()``` and ```clickLabel()```. Developers will now be able to give CasperJS a hint about the nature of a click, and expect CasperJS to block execution of its next step until some not-yet-started behaviour actually starts and completes (today, we're concerned about ```loadInProgress``` and ```navigtationRequested``` -- ```pendingWait``` exists, but I can't think of why I'd want to invoke ```blockStep``` using that reason).

It is relatively easy to maintain if new reasons for blocking the next step are created in the future; just add a new ```case``` for ```switch``` within ```blockStep()```. It is also possible to directly call ```blockStep()```, but a developer would typically be better just directly setting ```Casper.navigationRequested```, or ```Casper.loadInProgress```, or ```Casper.pendingWait```.

The idea of introducing blockStep() tied into click() and clickLabel() is so that we express the whole thing as a single statement.

This usage is probably the generalized version:

Casper.click("#that_button", "loadInProgress");

This usage is probably more specifically looking at navigation of the ```_top``` frame (```isMainFrame``` in CasperJS code):

Casper.click("#that_button", "navigationRequested");