The short version:
Please stop using wait_for in Gaia tests and start using Wait and expected. See examples towards the end of this e-mail for how to construct a few of our more common waits in this way. The exception at the moment is wait_for_element_not_displayed as we don't have a good alternative when the element has not previously been found. Any new pull requests that include use of these wait_for methods will get r- however you may also be shown a cute picture of a cat, so please don't feel too bad about it! :)

The (slightly) long(er) version:
Our wait_for methods have done us well, and it's easy to forget that they pre-date the excellent wait and expected condition helpers that are now available in Marionette. It's now time to let them go, and to migrate our tests to directly use the classes offered in the Marionette client. I've started this migration in bug 1074117 on a per app object basis. The plan is that the final patch will remove these methods from our base test and page classes. If you need a little bit more convincing, check the examples below to see how clean and easy the new classes are to use. In addition, this should reduce the number of times we ask Marionette to find elements for us - see the bug mentioned above for more details.

Examples:

Imports (use as needed):
from marionette import expected
from marionette import Wait

Waiting for an element to be present:
element = Wait(self.marionette).until(expected.element_present(by, locator))

Waiting for an element to be displayed (retain element for later use):
element = Wait(self.marionette).until(expected.element_present(by, locator))
Wait(self.marionette).until(expected.element_displayed(element))

Waiting for an element to be displayed (concise):
Wait(self.marionette).until(expected.element_displayed(by, locator))

Waiting for a condition to be true:
Wait(self.marionette).until(lambda m: condition)

Waiting for a condition involving an element to be true:
element = self.marionette.find_element(by, locator)
Wait(self.marionette).until(lambda m: element.condition)

Specifying a timeout:
Wait(self.marionette, timeout=60).until(...)

Specifying a failure message:
Wait(self.marionette).until(condition, message='Oh no, we failed!')

Further documentation on explicit waits and expected conditions can be found here: http://marionette-client.readthedocs.org/en/latest/reference.html#wait.