blob: 304a836b8cefb2a1940b51cec66f87cd3d3fa6a5 [file] [log] [blame]
George Keishinge7e91712021-09-03 11:28:44 -05001#!/usr/bin/env python3
Michael Walshbcc404d2017-04-12 15:54:58 -05002
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
Patrick Williams57318182022-12-08 06:18:26 -060011def run_key(keyword_buf, quiet=None, test_mode=None, ignore=0):
Michael Walshbcc404d2017-04-12 15:54:58 -050012 r"""
13 Run the given keyword, return the status and the keyword return values.
14
Michael Walsh410b1782019-10-22 15:56:18 -050015 The advantage of using this function verses having robot simply run your keyword is the handling of
16 parameters like quiet, test_mode and ignore.
Michael Walshbcc404d2017-04-12 15:54:58 -050017
18 Description of arguments:
19 keyword_buf The keyword string to be run.
Michael Walsh410b1782019-10-22 15:56:18 -050020 quiet Indicates whether this function should run the pissuing function to print
21 'Issuing: <keyword string>' to stdout.
22 test_mode If test_mode is set, this function will not actually run the command. If
23 quiet is 0, it will print a message indicating what it would have run
24 (e.g. "Issuing: (test_mode) your command").
25 ignore Ignore errors from running keyword. If this is 0, this function will
26 fail with whatever error occurred when running the keyword.
Michael Walshbcc404d2017-04-12 15:54:58 -050027
28 Example usage from a robot script:
29
30 ${status} ${ret_values}= Run Key My Keyword \ Arg1 \ Arg2
31
Michael Walsh410b1782019-10-22 15:56:18 -050032 Note that to get robot to pass your command + args as a single string to this function, you must escape
33 extra spaces with a backslash.
Michael Walshbcc404d2017-04-12 15:54:58 -050034
35 Also note that ret_values is a python list:
36 ret_values:
37 ret_values[0]: value1
38 ret_values[1]: value2
39 """
40
41 # Set these vars to default values if they are None.
42 quiet = int(gp.get_var_value(quiet, 0))
43 test_mode = int(gp.get_var_value(test_mode, 0))
44 ignore = int(ignore)
45
Michael Walsh410b1782019-10-22 15:56:18 -050046 # Convert the keyword_buf into a list split wherever 2 or more spaces are found.
Patrick Williams57318182022-12-08 06:18:26 -060047 keyword_list = keyword_buf.split(" ")
Michael Walsh410b1782019-10-22 15:56:18 -050048 # Strip spaces from each argument to make the output look clean and uniform.
Patrick Williams57318182022-12-08 06:18:26 -060049 keyword_list = [item.strip(" ") for item in keyword_list]
Michael Walshbcc404d2017-04-12 15:54:58 -050050
51 if not quiet:
52 # Join the list back into keyword_buf for the sake of output.
Patrick Williams57318182022-12-08 06:18:26 -060053 keyword_buf = " ".join(keyword_list)
Michael Walshbcc404d2017-04-12 15:54:58 -050054 gp.pissuing(keyword_buf, test_mode)
55
56 if test_mode:
Patrick Williams57318182022-12-08 06:18:26 -060057 return "PASS", ""
Michael Walshbcc404d2017-04-12 15:54:58 -050058
Michael Walshdfcbaa82017-04-20 16:48:03 -050059 try:
Patrick Williams57318182022-12-08 06:18:26 -060060 status, ret_values = BuiltIn().run_keyword_and_ignore_error(
61 *keyword_list
62 )
Michael Walshdfcbaa82017-04-20 16:48:03 -050063 except Exception as my_assertion_error:
64 status = "FAIL"
65 ret_values = my_assertion_error.args[0]
Michael Walshbcc404d2017-04-12 15:54:58 -050066
Patrick Williams57318182022-12-08 06:18:26 -060067 if status != "PASS":
Michael Walshbcc404d2017-04-12 15:54:58 -050068 # Output the error message to stderr.
Patrick Williams57318182022-12-08 06:18:26 -060069 BuiltIn().log_to_console(ret_values, stream="STDERR")
Michael Walshefb3d172018-03-29 16:29:12 -050070 if not ignore:
71 # Fail with the given error message.
72 BuiltIn().fail(ret_values)
Michael Walshbcc404d2017-04-12 15:54:58 -050073
74 return status, ret_values
75
Michael Walshbcc404d2017-04-12 15:54:58 -050076
Patrick Williams57318182022-12-08 06:18:26 -060077def run_key_u(keyword_buf, quiet=None, ignore=0):
Michael Walshbcc404d2017-04-12 15:54:58 -050078 r"""
Michael Walsh410b1782019-10-22 15:56:18 -050079 Run keyword unconditionally (i.e. without regard to global test_mode setting).
Michael Walshbcc404d2017-04-12 15:54:58 -050080
Michael Walsh410b1782019-10-22 15:56:18 -050081 This function will simply call the run_key function passing on all of the callers parameters except
82 test_mode which will be hard-coded to 0. See run_key (above) for details.
Michael Walshbcc404d2017-04-12 15:54:58 -050083
84 See the proglog of "run_key" function above for description of arguments.
85 """
86
87 return run_key(keyword_buf, test_mode=0, quiet=quiet, ignore=ignore)