1#!/usr/bin/env python
2
3r"""
4This module provides robot keyword execution functions such as run_key..
5"""
6
7import gen_print as gp
8from robot.libraries.BuiltIn import BuiltIn
9
10
11def run_key(keyword_buf,
12            quiet=None,
13            test_mode=None,
14            ignore=0):
15    r"""
16    Run the given keyword, return the status and the keyword return values.
17
18    The advantage of using this function verses having robot simply run your keyword is the handling of
19    parameters like quiet, test_mode and ignore.
20
21    Description of arguments:
22    keyword_buf                     The keyword string to be run.
23    quiet                           Indicates whether this function should run the pissuing function to print
24                                    'Issuing: <keyword string>' to stdout.
25    test_mode                       If test_mode is set, this function will not actually run the command.  If
26                                    quiet is 0, it will print a message indicating what it would have run
27                                    (e.g. "Issuing: (test_mode) your command").
28    ignore                          Ignore errors from running keyword.  If this is 0, this function will
29                                    fail with whatever error occurred when running the keyword.
30
31    Example usage from a robot script:
32
33    ${status}  ${ret_values}=  Run Key  My Keyword \ Arg1 \ Arg2
34
35    Note that to get robot to pass your command + args as a single string to this function, you must escape
36    extra spaces with a backslash.
37
38    Also note that ret_values is a python list:
39    ret_values:
40      ret_values[0]:    value1
41      ret_values[1]:    value2
42    """
43
44    # Set these vars to default values if they are None.
45    quiet = int(gp.get_var_value(quiet, 0))
46    test_mode = int(gp.get_var_value(test_mode, 0))
47    ignore = int(ignore)
48
49    # Convert the keyword_buf into a list split wherever 2 or more spaces are found.
50    keyword_list = keyword_buf.split('  ')
51    # Strip spaces from each argument to make the output look clean and uniform.
52    keyword_list = [item.strip(' ') for item in keyword_list]
53
54    if not quiet:
55        # Join the list back into keyword_buf for the sake of output.
56        keyword_buf = '  '.join(keyword_list)
57        gp.pissuing(keyword_buf, test_mode)
58
59    if test_mode:
60        return 'PASS', ""
61
62    try:
63        status, ret_values = \
64            BuiltIn().run_keyword_and_ignore_error(*keyword_list)
65    except Exception as my_assertion_error:
66        status = "FAIL"
67        ret_values = my_assertion_error.args[0]
68
69    if status != 'PASS':
70        # Output the error message to stderr.
71        BuiltIn().log_to_console(ret_values, stream='STDERR')
72        if not ignore:
73            # Fail with the given error message.
74            BuiltIn().fail(ret_values)
75
76    return status, ret_values
77
78
79def run_key_u(keyword_buf,
80              quiet=None,
81              ignore=0):
82    r"""
83    Run keyword unconditionally (i.e. without regard to global test_mode setting).
84
85    This function will simply call the run_key function passing on all of the callers parameters except
86    test_mode which will be hard-coded to 0.  See run_key (above) for details.
87
88    See the proglog of "run_key" function above for description of arguments.
89    """
90
91    return run_key(keyword_buf, test_mode=0, quiet=quiet, ignore=ignore)
92