Within and Once Logic

Within

Many Cycle Steps have a version that includes the modifier: within <NUMBER> seconds. This modifier enables you to configure a specific wait time as part of a given Step before failing the Step.

For a simple use case, take the following example:

    Given I press enter
    And I wait 10 seconds
    Then I execute scenario "Next Scenario"

The above example contains the Step And I wait 10 seconds with the intention that in 10 seconds or less, any work being executed as part of the I press enter Step would be finished. Although this approach may work, utilizing a validation Step that has a within modifier can ensure more consistent results.

    Given I press enter
    When I see image "Image:my_image.png" within 10 seconds
    Then I execute scenario "Next Scenario"

In the second example, the Then I execute scenario "Next Scenario" Step will not begin until the expected image has been found, or if 10 seconds has elapsed, the Scenario will fail.

The Terminal Emulation family of Steps is subject to a more broadly applied within setting which is found in the Execution Settings.

Once

For Steps that DO NOT have the option of an explicit within** modifier, the Once keyword offers a similar but less graceful time cutoff. A Step that fails due to the timeout of the Once keyword does not include details about what the Step was doing when the time expired; no screenshots or other representation of state is captured.

You can set a wait time for the Once keyword in Execution Settings. The default wait time is 120 seconds. If the Step Once I see image "Image:my_image.png" does not pass within 120 seconds, it will automatically fail.

Note: Once should not be used when there is also a within, either explicitly modifying the Step or as a default in the case of terminal Steps. For Steps where a within modifier is available, this method is considered to be the best practice.