csit/libraries/WaitUtils.robot

   1 *** Settings ***
   2 Documentation     Robot keyword library (Resource) with several Keywords for monitoring and waiting.
   3 ...
   4 ...               Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved.
   5 ...
   6 ...               This program and the accompanying materials are made available under the
   7 ...               terms of the Eclipse Public License v1.0 which accompanies this distribution,
   8 ...               and is available at http://www.eclipse.org/legal/epl-v10.html
   9 ...
  10 ...
  11 ...               BuiltIn.Wait_Until_Keyword_Succeeds is useful in avoiding unnecessary sleeps.
  12 ...               But several usage cases need slightly different logic, here are Keywords for that.
  13 ...
  14 ...               This library uses ScalarClosures for plugging in specific Keywords.
  15 ...               Storing private state in suite variables is easy, but it can lead to hard-to-debug issues,
  16 ...               so this library tries to support explicit state passing.
  17 ...               Unfortunately, failing limits type of message to return,
  18 ...               so implementation of some Keywords looks quite convoluted.
  19 ...
  20 ...               Particular closures are to be given by caller:
  21 ...               Stateless Assertor: Take no arguments. Return comment or Fail with message.
  22 ...               Stateful Assertor: Take single ${state} argument. Return new state and comment, or Fail with message.
  23 ...               (Stateless) Getter: Take no argument. Return single scalar data, or Fail with message.
  24 ...               Stateless Validator: Take single ${data} argument. Return comment, or Fail with message.
  25 ...               (Unsafe) Stateful Validator: Take ${state} and ${data} arguments. Return new state and comment, or Fail with message.
  26 ...               Safe Stateful Validator: Take ${state} and ${data} arguments. Return new state, validation status and comment/message.
  27 ...               TODO: Create a dummy closure for each type to be used as default value?
  28 ...
  29 ...               TODO: Figure out a way to merge this with FaitForFailure.robot
  30 ...               TODO: Add Keywords that are Safe (return state, success and message)
  31 ...               so that callers do not need to refresh state explicitly.
  32 Library           DateTime
  33 Library           String
  34 Resource          ${CURDIR}/ScalarClosures.robot
  35
  36 *** Keywords ***
  37 WU_Setup
  38     [Documentation]    Call dependency setup. Perhaps needed.
  39     ScalarClosures.SC_Setup
  40
  41 Limiting_Stability_Safe_Stateful_Validator_As_Keyword
  42     [Arguments]    ${old_state}    ${data}    ${valid_minimum}=-1
  43     [Documentation]    Report failure if minimum not reached or data value changed from last time. Useful to become validator.
  44     ${new_state} =    BuiltIn.Set_Variable    ${data}
  45     BuiltIn.Return_From_Keyword_If    ${data} < ${valid_minimum}    ${new_state}    FAIL    Minimum not reached.
  46     BuiltIn.Return_From_Keyword_If    ${data} != ${old_state}    ${new_state}    FAIL    Data value has changed.
  47     [Return]    ${new_state}    PASS    Validated stable: ${data}
  48
  49 Create_Limiting_Stability_Safe_Stateful_Validator_From_Value_To_Overcome
  50     [Arguments]    ${maximum_invalid}=-1
  51     [Documentation]    Helper function to use if maximum invalid value (instead of minimum valid) is known.
  52     ${valid_minimum} =    BuiltIn.Evaluate    str(int(${maximum_invalid}) + 1)
  53     ${validator} =    ScalarClosures.Closure_From_Keyword_And_Arguments    WaitUtils.Limiting_Stability_Safe_Stateful_Validator_As_Keyword    state_holder    data_holder    valid_minimum=${valid_minimum}
  54     [Return]    ${validator}
  55
  56 Excluding_Stability_Safe_Stateful_Validator_As_Keyword
  57     [Arguments]    ${old_state}    ${data}    ${excluded_value}=-1
  58     [Documentation]    Report failure if got the excluded value or if data value changed from last time. Useful to become validator.
  59     ${new_state} =    BuiltIn.Set_Variable    ${data}
  60     BuiltIn.Return_From_Keyword_If    ${data} == ${excluded_value}    ${new_state}    FAIL    Got the excluded value.
  61     BuiltIn.Return_From_Keyword_If    ${data} != ${old_state}    ${new_state}    FAIL    Data value has changed.
  62     [Return]    ${new_state}    PASS    Validated stable: ${data}
  63
  64 WaitUtils__Check_Sanity_And_Compute_Derived_Times
  65     [Arguments]    ${timeout}=60s    ${period}=1s    ${count}=1
  66     [Documentation]    Common checks for argument values. Return times in seconds and deadline date implied by timeout time.
  67     # Sanity check ${count}.
  68     BuiltIn.Run_Keyword_If    int(${count}) < 1    BuiltIn.Fail    \${count} is ${count} and not at least 1.
  69     # Sanity check ${period}.
  70     ${period_in_seconds} =    DateTime.Convert_Time    ${period}    result_format=number
  71     BuiltIn.Run_Keyword_If    ${period_in_seconds} <= 0.0    BuiltIn.Fail    \${period} ${period} has to be positive.
  72     # Figure out deadline.
  73     ${date_now} =    DateTime.Get_Current_Date
  74     ${timeout_in_seconds} =    DateTime.Convert_Time    ${timeout}    result_format=number
  75     # In the following line, arguments have to be in order which is opposite to what name suggests.
  76     ${date_deadline} =    DateTime.Add_Time_To_Date    ${date_now}    ${timeout_in_seconds}
  77     [Return]    ${timeout_in_seconds}    ${period_in_seconds}    ${date_deadline}
  78
  79 WaitUtils__Is_Deadline_Reachable
  80     [Arguments]    ${date_deadline}=0    ${period_in_seconds}=1    ${sleeps_left}=1    ${message}=No attempt made.
  81     [Documentation]    Compute time to be wasted in sleeps, compare to deadline. Fail with message when needed.
  82     # FIXME: Sensible default for deadline?
  83     ${date_now} =    DateTime.Get_Current_Date
  84     ${time_deadline} =    DateTime.Subtract_Date_From_Date    ${date_deadline}    ${date_now}    result_format=number
  85     ${time_minimal} =    BuiltIn.Evaluate    int(${sleeps_left}) * ${period_in_seconds}
  86     BuiltIn.Run_Keyword_If    ${time_minimal} >= ${time_deadline}    BuiltIn.Fail    Not possible to succeed within the deadline. ${message}
  87
  88 Stateless_Assert_Closure_Has_To_Succeed_Consecutively_By_Deadline
  89     [Arguments]    ${date_deadline}=0    ${period_in_seconds}=1    ${count}=1    ${assertor}=${ScalarClosures__fail}
  90     [Documentation]    Pass only if ${assertor} passes ${count} times in a row with ${period_in_seconds} between attempts; less standard arguments.
  91     ${result} =    BuiltIn.Set_Variable    No result yet.
  92     # Do we have enough time to succeed?
  93     ${sleeps} =    BuiltIn.Evaluate    ${count} - 1
  94     WaitUtils__Is_Deadline_Reachable    date_deadline=${date_deadline}    period_in_seconds=${period_in_seconds}    sleeps_left=${sleeps}    message=Last result: ${result}
  95     # Entering the main loop.
  96     : FOR    ${sleeps_left}    IN RANGE    ${count}-1    -1    -1    # If count is 3, for will go through 2, 1, and 0.
  97     \    # Run the assertor and collect the garbage.
  98     \    ${result} =    ScalarClosures.Run_Keyword_And_Collect_Garbage    ScalarClosures.Run_Closure_As_Is    ${assertor}
  99     \    # We have not failed yet. Was this the final try?
 100     \    BuiltIn.Return_From_Keyword_If    ${sleeps_left} <= 0    ${result}
 101     \    # Is there enough time left?
 102     \    WaitUtils__Is_Deadline_Reachable    date_deadline=${date_deadline}    period_in_seconds=${period_in_seconds}    sleeps_left=${sleeps_left}    message=Last result: ${result}
 103     \    # We will do next try, byt we have to sleep before.
 104     \    BuiltIn.Sleep    ${period_in_seconds} s
 105     BuiltIn.Fail    Logic error, we should have returned before.
 106
 107 Stateless_Assert_Closure_Has_To_Succeed_Consecutively
 108     [Arguments]    ${timeout}=60s    ${period}=1s    ${count}=1    ${assertor}=${ScalarClosures__fail}
 109     [Documentation]    Pass only if ${assertor} passes ${count} times in a row with ${period} between attempts; standard arguments.
 110     # TODO: Put default values into variables for users to override at pybot invocation?
 111     ${timeout_in_seconds}    ${period_in_seconds}    ${date_deadline} =    WaitUtils__Check_Sanity_And_Compute_Derived_Times    timeout=${timeout}    period=${period}    count=${count}
 112     ${result} =    Stateless_Assert_Closure_Has_To_Succeed_Consecutively_By_Deadline    date_deadline=${date_deadline}    period_in_seconds=${period_in_seconds}    count=${count}    assertor=${assertor}
 113     [Return]    ${result}
 114
 115 Stateful_Assert_Closure_Has_To_Succeed_Consecutively_By_Deadline
 116     [Arguments]    ${date_deadline}=0    ${period_in_seconds}=1    ${count}=1    ${assertor}=${ScalarClosures__fail}    ${initial_state}=${None}
 117     [Documentation]    Pass only if ${assertor} passes ${count} times in a row with ${period} between attempts. Keep assertor state in local variable. Less standard arguments.
 118     # TODO: Put default values into variables for users to override.
 119     ${result} =    BuiltIn.Set_Variable    No result yet.
 120     ${state} =    BuiltIn.Set_Variable    ${initial_state}
 121     # Do we have enough time to succeed?
 122     ${sleeps} =    BuiltIn.Evaluate    ${count} - 1
 123     WaitUtils__Is_Deadline_Reachable    date_deadline=${date_deadline}    period_in_seconds=${period_in_seconds}    sleeps_left=${sleeps}    message=Last result: ${result}
 124     # Entering the main loop.
 125     : FOR    ${sleeps_left}    IN RANGE    ${count}-1    -1    -1
 126     \    ${state}    ${result} =    ScalarClosures.Run_Keyword_And_Collect_Garbage    ScalarClosures.Run_Closure_After_Replacing_First_Argument    ${assertor}    ${state}
 127     \    # We have not failed yet. Was this the final try?
 128     \    BuiltIn.Return_From_Keyword_If    ${sleeps_left} <= 0    ${result}
 129     \    # Is there enough time left?
 130     \    WaitUtils__Is_Deadline_Reachable    date_deadline=${date_deadline}    period_in_seconds=${period_in_seconds}    sleeps_left=${sleeps_left}    message=Last result: ${result}
 131     \    # We will do next try, byt we have to sleep before.
 132     \    BuiltIn.Sleep    ${period_in_seconds} s
 133     BuiltIn.Fail    Logic error, we should have returned before.
 134
 135 Stateful_Assert_Closure_Has_To_Succeed_Consecutively
 136     [Arguments]    ${timeout}=60s    ${period}=1s    ${count}=1    ${assertor}=${ScalarClosures__fail}    ${initial_state}=${NONE}
 137     [Documentation]    Pass only if ${assertor} passes ${count} times in a row with ${period} between attempts. Keep assertor state in local variable. Standard arguments.
 138     # TODO: Put default values into variables for users to override.
 139     ${timeout_in_seconds}    ${period_in_seconds}    ${date_deadline} =    WaitUtils__Check_Sanity_And_Compute_Derived_Times    timeout=${timeout}    period=${period}    count=${count}
 140     ${result} =    Stateful_Assert_Closure_Has_To_Succeed_Consecutively_By_Deadline    date_deadline=${date_deadline}    period_in_seconds=${period_in_seconds}    count=${count}    assertor=${assertor}    initial_state=${initial_state}
 141     [Return]    ${result}
 142
 143 Getter_And_Safe_Stateful_Validator_Have_To_Succeed_Consecutively_By_Deadline
 144     [Arguments]    ${date_deadline}=0    ${period_in_seconds}=1    ${count}=1    ${getter}=${ScalarClosures__fail}    ${safe_validator}=${ScalarClosures__fail}    ${initial_state}=${NONE}
 145     [Documentation]    Pass only if consecutively ${count} times in a row with ${period} between attempts: ${getter} creates data and ${safe_validator} passes. Validator updates its state even if it reports failure. Always return validator state, status and message.
 146     ${result} =    BuiltIn.Set_Variable    No result yet.
 147     ${state} =    BuiltIn.Set_Variable    ${initial_state}
 148     # Do we have enough time to succeed?
 149     ${sleeps} =    BuiltIn.Evaluate    ${count} - 1
 150     ${status}    ${message} =    BuiltIn.Run_Keyword_And_Ignore_Error    WaitUtils__Is_Deadline_Reachable    date_deadline=${date_deadline}    period_in_seconds=${period_in_seconds}    sleeps_left=${sleeps}
 151     ...    message=Last result: ${result}
 152     BuiltIn.Return_From_Keyword_If    '''${status}''' != '''PASS'''    ${state}    ${status}    ${message}
 153     # Entering the main loop.
 154     : FOR    ${sleeps_left}    IN RANGE    ${count}-1    -1    -1
 155     \    # Getter may fail, but this Keyword should return state, so we need RKAIE.
 156     \    ${status}    ${data} =    BuiltIn.Run_Keyword_And_Ignore_Error    ScalarClosures.Run_Keyword_And_Collect_Garbage    ScalarClosures.Run_Closure_As_Is    ${getter}
 157     \    BuiltIn.Return_From_Keyword_If    '''${status}''' != '''PASS'''    ${state}    ${status}    Getter failed: ${data}
 158     \    # Is there enough time left?
 159     \    ${status}    ${message} =    BuiltIn.Run_Keyword_And_Ignore_Error    WaitUtils__Is_Deadline_Reachable    date_deadline=${date_deadline}    period_in_seconds=${period_in_seconds}
 160     \    ...    sleeps_left=${sleeps_left}    message=Last result: ${result}
 161     \    BuiltIn.Return_From_Keyword_If    '''${status}''' != '''PASS'''    ${state}    ${status}    ${message}
 162     \    ${state}    ${status}    ${result} =    ScalarClosures.Run_Keyword_And_Collect_Garbage    ScalarClosures.Run_Closure_After_Replacing_First_Two_Arguments    ${safe_validator}
 163     \    ...    ${state}    ${data}
 164     \    # Validator may have reported failure.
 165     \    BuiltIn.Return_From_Keyword_If    '''${status}''' != '''PASS'''    ${state}    ${status}    Validator failed: ${result}
 166     \    # Was this the final try?
 167     \    BuiltIn.Return_From_Keyword_If    ${sleeps_left} <= 0    ${state}    ${status}    ${result}
 168     \    # Is there enough time left?
 169     \    ${status}    ${message} =    BuiltIn.Run_Keyword_And_Ignore_Error    WaitUtils__Is_Deadline_Reachable    date_deadline=${date_deadline}    period_in_seconds=${period_in_seconds}
 170     \    ...    sleeps_left=${sleeps_left}    message=Last result: ${result}
 171     \    BuiltIn.Return_From_Keyword_If    '''${status}''' != '''PASS'''    ${state}    ${status}    ${message}
 172     \    # We will do next try, byt we have to sleep before.
 173     \    BuiltIn.Sleep    ${period_in_seconds} s
 174     BuiltIn.Fail    Logic error, we should have returned before.
 175
 176 Propagate_Fail_If_Message_Starts_With_Prefix
 177     [Arguments]    ${message}=${EMPTY}    ${prefix}=magic
 178     [Documentation]    Helper keyword to distinguish escalable failures by their prefix. If it is escalable, Fail without changing the message; otherwise Return comment.
 179     # TODO: Move to a more appropriate Resource.
 180     # Empty message cannot fit prefix.
 181     ${status}    ${result} =    BuiltIn.Run_Keyword_And_Ignore_Error    BuiltIn.Should_Be_Empty    ${message}
 182     BuiltIn.Return_From_Keyword_If    '${status}' == 'PASS'    Got empty message.
 183     # Is there anything except the prefix?
 184     @{message_chunks}=    String.Split_String    ${message}    ${prefix}
 185     # If there is something at the first chunk, the prefix was not at start.
 186     ${status}    ${result} =    BuiltIn.Run_Keyword_And_Ignore_Error    BuiltIn.Should_Be_Empty    ${message_chunks[0]}
 187     BuiltIn.Return_From_Keyword_If    '${status}' != 'PASS'    ${message} does not start with ${prefix}
 188     # We got the fail to propagate
 189     BuiltIn.Fail    ${message}
 190
 191 Wait_For_Getter_And_Safe_Stateful_Validator_Consecutive_Success
 192     [Arguments]    ${timeout}=60s    ${period}=1s    ${count}=1    ${getter}=${ScalarClosures__fail}    ${safe_validator}=${ScalarClosures__fail}    ${initial_state}=${NONE}
 193     [Documentation]    Analogue of Wait Until Keyword Succeeds, but it passes state of validator around. Calls GASSVHTSCBD to verify data is "stable".
 194     # FIXME: Document that Safe Stateful Validator has to return state, status and message (and never fail)
 195     ${timeout_in_seconds}    ${period_in_seconds}    ${date_deadline} =    WaitUtils__Check_Sanity_And_Compute_Derived_Times    timeout=${timeout}    period=${period}    count=${count}
 196     # Maximum number of tries. TODO: Move to separate Keyword?
 197     ${maximum_tries} =    BuiltIn.Evaluate    math.ceil(${timeout_in_seconds} / ${period_in_seconds})    modules=math
 198     ${result} =    BuiltIn.Set_Variable    No result yet.
 199     ${state} =    BuiltIn.Set_Variable    ${initial_state}
 200     # The loop for failures.
 201     : FOR    ${try}    IN RANGE    1    ${maximum_tries}+1    # If maximum_tries is 3, for will go through 1, 2, and 3.
 202     \    ${state}    ${status}    ${result} =    Getter_And_Safe_Stateful_Validator_Have_To_Succeed_Consecutively_By_Deadline    date_deadline=${date_deadline}    period_in_seconds=${period_in_seconds}
 203     \    ...    count=${count}    getter=${getter}    safe_validator=${safe_validator}    initial_state=${state}
 204     \    # Have we passed?
 205     \    BuiltIn.Return_From_Keyword_If    '''${status}''' == '''PASS'''    ${result}
 206     \    # Are we out of time?
 207     \    Propagate_Fail_If_Message_Starts_With_Prefix    ${result}    Not possible to succeed within the deadline.
 208     \    # We will do next try, but we have to sleep before.
 209     \    BuiltIn.Sleep    ${period_in_seconds} s
 210     BuiltIn.Fail    Logic error, we should have returned before.
 211
 212 Wait_For_Getter_Error_Or_Safe_Stateful_Validator_Consecutive_Success
 213     [Arguments]    ${timeout}=60s    ${period}=1s    ${count}=1    ${getter}=${ScalarClosures__fail}    ${safe_validator}=${ScalarClosures__fail}    ${initial_state}=${NONE}
 214     [Documentation]    Analogue of Wait Until Keyword Succeeds, but it passes state of validator around and exits early on getter failure. Calls GASSVHTSCBD to verify data is "stable".
 215     # If this ever fails, we want to know the exact inputs passed to it.
 216     ${tmp}=    BuiltIn.Evaluate    int(${count})
 217     BuiltIn.Log    count=${tmp}
 218     ${timeout_in_seconds}    ${period_in_seconds}    ${date_deadline} =    WaitUtils__Check_Sanity_And_Compute_Derived_Times    timeout=${timeout}    period=${period}    count=${count}
 219     # Maximum number of tries. TODO: Move to separate Keyword or add into CSACDT?
 220     ${maximum_tries} =    BuiltIn.Evaluate    math.ceil(${timeout_in_seconds} / ${period_in_seconds})    modules=math
 221     ${result} =    BuiltIn.Set_Variable    No result yet.
 222     ${state} =    BuiltIn.Set_Variable    ${initial_state}
 223     # The loop for failures.
 224     : FOR    ${try}    IN RANGE    1    ${maximum_tries}+1    # If maximum_tries is 3, for will go through 1, 2, and 3.
 225     \    ${state}    ${status}    ${result} =    Getter_And_Safe_Stateful_Validator_Have_To_Succeed_Consecutively_By_Deadline    date_deadline=${date_deadline}    period_in_seconds=${period_in_seconds}
 226     \    ...    count=${count}    getter=${getter}    safe_validator=${safe_validator}    initial_state=${state}
 227     \    # Have we passed?
 228     \    BuiltIn.Return_From_Keyword_If    '''${status}''' == '''PASS'''    ${result}
 229     \    # Are we out of time? Look at ${result}.
 230     \    Propagate_Fail_If_Message_Starts_With_Prefix    ${result}    Not possible to succeed within the deadline.
 231     \    # Now check for getter error, by analysing ${result}.
 232     \    Propagate_Fail_If_Message_Starts_With_Prefix    ${result}    Getter failed
 233     \    # We can do the next try, byt we have to sleep before.
 234     \    BuiltIn.Sleep    ${period_in_seconds} s
 235     BuiltIn.Fail    Logic error, we should have returned before.