autopilot.matchers.Eventually

class autopilot.matchers.Eventually(matcher, **kwargs)

Asserts that a value will eventually equal a given Matcher object.

This matcher wraps another testtools matcher object. It makes that other matcher work with a timeout. This is necessary for several reasons:

Since most actions in a GUI applicaton take some time to complete, the test may need to wait for the application to enter the expected state.
Since the test is running in a separate process to the application under test, test authors cannot make any assumptions about when the application under test will recieve CPU time to update to the expected state.

There are two main ways of using the Eventually matcher:

Attributes from the application:

self.assertThat(window.maximized, Eventually(Equals(True)))

Here, window is an object generated by autopilot from the applications state. This pattern of usage will cover 90% (or more) of the assertions in an autopilot test. Note that any matcher can be used - either from testtools or any custom matcher that implements the matcher API:

self.assertThat(window.height, Eventually(GreaterThan(200)))

Callable Objects:

self.assertThat(
autopilot.platform.model, Eventually(Equals("Galaxy Nexus")))

In this example we’re using the autopilot.platform.model function as a callable. In this form, Eventually matches against the return value of the callable.

This can also be used to use a regular python property inside an Eventually matcher:

self.assertThat(lambda: self.mouse.x, Eventually(LessThan(10)))

Note

Using this form generally makes your tests less readable, and should be used with great care. It also relies the test author to have knowledge about the implementation of the object being matched against. In this example, if self.mouse.x were ever to change to be a regular python attribute, this test would likely break.

Timeout

By default timeout period is ten seconds. This can be altered by passing the timeout keyword:

self.assertThat(foo.bar, Eventually(Equals(123), timeout=30))

Warning

The Eventually matcher does not work with any other matcher that expects a callable argument (such as testtools’ ‘Raises’ matcher)