How to wait on pages being loaded

Waiting on document.ready is almost never enough thanks to everyone writing literally everything in javascript these days. WebDriver itself actually waits for DomContentLoaded to fire, but that means you have a blank page (yay!) under things like AngularJS, or anything with RequireJS, etc.

What you in-practice have to wait for is either:

1. A global semaphore used by the system under test's JS library(s)

2. An element on the page that you know is present only when everything is done processing.

3. setting up a mutation observer which will return only when the DOM stops mutating after some timeout. This has the drawback of possibly never terminating on buggy pages, so it will have to be watchdogged.

This means there is unfortunately no "one size fits all" solution for waiting on pages to be done loading. Our module to wait for this stuff at my employer has 33 separate conditions depending on what page you might be on, for example.

For a built in waiter loop, Selenium::Waiter is shipped to help with this, but it is quite crude and cannot possibly accommodate all situations. To implement 2) and 3) you will have to use execute_async_script() based on the particular JS events you need to wait on.