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, that method is considered to be the best practice.