def save_environment(self): environment = {} environment['id'] = 'Robot Framework' environment['name'] = socket.getfqdn() environment['url'] = 'http://' + socket.getfqdn() + ':8000' included_args = self.AllureProperties.get_property( 'robot.cli.arguments.included') rf_args = sys.argv[1:] if included_args: rf_args = [] for index, arg in enumerate(sys.argv): if arg in included_args: rf_args.append(sys.argv[index]) if index < len( sys.argv) and not sys.argv[index + 1].startswith('-'): rf_args.append(sys.argv[index + 1]) env_dict = (\ {'Robot Framework Full Version': get_full_version()},\ {'Robot Framework Version': get_version()},\ {'Interpreter': get_interpreter()},\ {'Python version': sys.version.split()[0]},\ {'Allure Adapter version': VERSION},\ {'Robot Framework CLI Arguments': rf_args},\ {'Robot Framework Hostname': socket.getfqdn()},\ {'Robot Framework Platform': sys.platform}\ ) for key in env_dict: self.AllureImplc.environment.update(key) self.AllureImplc.logdir = self.AllureProperties.get_property( 'allure.cli.logs.xml') self.AllureImplc.store_environment(environment)
class Xtimer(DutShell): """Interface to the a node with xtimer_cli firmware.""" ROBOT_LIBRARY_SCOPE = 'TEST SUITE' ROBOT_LIBRARY_VERSION = get_version() FW_ID = 'xtimer_cli' def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) def is_connected_to_board(self): """Checks if board is connected.""" return self.i2c_get_id()["data"] == [self.FW_ID] def xtimer_now(self): """Get current timer ticks.""" return self.send_cmd('xtimer_now') def get_metadata(self): """Get the metadata of the firmware.""" return self.send_cmd('get_metadata') def get_command_list(self): """List of all commands.""" cmds = list() cmds.append(self.get_metadata) cmds.append(self.xtimer_now) return cmds
class mysqlLib(object): ROBOT_LIBRARY_SCOPE = 'GLOBAL' ROBOT_LIBRARY_VERSION = get_version() def mysqlName(self, a): print(a)
class PhilipAPI(Phil): """Robot framework wrapper for PHiLIP""" ROBOT_LIBRARY_SCOPE = 'TEST SUITE' ROBOT_LIBRARY_VERSION = get_version() def __init__(self, port, baudrate): super().__init__(port, baudrate) def setup_uart(self, mode=0, baudrate=115200, databits=serial.EIGHTBITS, parity=serial.PARITY_NONE, stopbits=serial.STOPBITS_ONE, rts=True): """Setup tester's UART.""" ret = list() mode = int(mode) assert mode >= 0 and mode < 3, "Invalid mode setting for the if_type" ret.append(self.write_reg('uart.mode.if_type', mode)) ret.append(self.write_reg('uart.baud', int(baudrate))) # setup UART control register if databits == serial.SEVENBITS: ret.append(self.write_reg('uart.mode.data_bits', 1)) if parity == serial.PARITY_EVEN: ret.append(self.write_reg('uart.mode.parity', 1)) elif parity == serial.PARITY_ODD: ret.append(self.write_reg('uart.mode.parity', 2)) if stopbits == serial.STOPBITS_TWO: ret.append(self.write_reg('uart.mode.stop_bits', 1)) # invert RTS level as it is a low active signal if not rts: ret.append(self.write_reg('uart.mode.rts', 1)) ret.append(self.write_reg('uart.mode.init', 0)) # apply changes ret.append(self.execute_changes()) return ret def get_counters(self): """Get rx/tx counters.""" ret = list() ret.append(self.read_reg('uart.rx_count')) ret.append(self.read_reg('uart.tx_count')) return ret def get_error_flags(self): """Get error flags.""" ret = list() ret.append(self.read_reg('uart.status.pe')) ret.append(self.read_reg('uart.status.fe')) ret.append(self.read_reg('uart.status.nf')) ret.append(self.read_reg('uart.status.ore')) return ret
class XiaoFish(object): ''' ''' ROBOT_LIBRARY_SCOPE = 'TEST_SUITE' ROBOT_LIBRARY_VERSION = get_version() def __init__(self): '''''' self._pkt_streamlist_cmdstring = [] self._pkt_kws = self._lib_kws = None self._pkt_class = rfbase.PacketBase() def get_keyword_names(self): return self._get_library_keywords() + self._get_pkt_keywords() def _get_library_keywords(self): if self._lib_kws is None: self._lib_kws = self._get_keywords(self, ['get_keyword_names']) return self._lib_kws def _get_keywords(self, source, excluded): return [name for name in dir(source) if self._is_keyword(name, source, excluded)] def _is_keyword(self, name, source, excluded): return (name not in excluded and not name.startswith('_') and name != 'get_keyword_names' and inspect.ismethod(getattr(source, name))) def _get_pkt_keywords(self): if self._pkt_kws is None: pkt = self._pkt_class excluded = ['get_packet_list','empty_packet_list','get_packet_list_ixiaapi'] self._pkt_kws = self._get_keywords(pkt, excluded) return self._pkt_kws def __getattr__(self, name): if name not in self._get_pkt_keywords(): raise AttributeError(name) # This makes it possible for Robot to create keyword # handlers when it imports the library. return getattr(self._pkt_class, name) def get_stream_from_pcapfile(self,filename): '''read pcap file and return bytes stream''' if not os.path.isfile(filename): logger.info('%s is not a file' % filename) raise AssertionError('%s is not file or path error' % filename) with open(filename,'rb') as handle: return handle.read() def build_stream(self): '''''' self._pkt_streamlist_cmdstring = self._pkt_class.get_packet_list() self._pkt_class.empty_packet_list() return self._pkt_streamlist_cmdstring
class ExcelLib: ROBOT_LIBRARY_SCOPE = 'GLOBAL' ROBOT_LIBRARY_VERSION = get_version() def Mul(self, a, b): logger.info("app/login") return int(a) * int(b) def Div(self, a, b): return float(a / b, 2)
class SearchKeywords(object): ROBOT_LIBRARY_VERSION = get_version() ROBOT_LIBRARY_SCOPE = 'GLOBAL' def __init__(self): self.browser = None self.home_page = None self.search_results_page = None self.listener = RobotListener( 'selenium.webdriver.remote.remote_connection') self.ROBOT_LIBRARY_LISTENER = self.listener def launch_browser(self, name='firefox', is_remote=False, enable_screenshot=False): self.browser = Browser(name=name, is_remote=is_remote) if str(enable_screenshot).lower() not in ('false', 'no'): self.listener.enable_screenshot(self.browser) def close_browser(self): if self.browser: self.browser.close() self.listener.disable_screenshot() def i_am_on_home_page(self, url): self.home_page = BingHomePage(url) def i_search_with_keyword(self, keyword): self.search_results_page = \ self.home_page.search_with_keyword( keyword ) def i_get_the_first_search_record_containing_keyword(self, keyword): assert isinstance( self.search_results_page, SearchResultsPage), 'The search results page is displayed' bag_of_keywords = str.split( self.search_results_page.text_of_first_record.lower()) if (bag_of_keywords[0] in keyword.lower()) or (bag_of_keywords[-1] in keyword.lower()): logger.info('Succeed on searching keyword within bing.com', # html=True ) else: logger.error('"{}" not in "{}"'.format( keyword, self.search_results_page.text_of_first_record), html=True)
def run_test_body(self, context, test): from robot import version IS_ROBOT_4_ONWARDS = not version.get_version().startswith("3.") if IS_ROBOT_4_ONWARDS: from robot.running.bodyrunner import BodyRunner # noqa BodyRunner(context, templated=False).run(test.body) else: from robot.running.steprunner import StepRunner # noqa StepRunner(context, False).run_steps(test.keywords.normal)
class PhilipAPI(LLMemMapIf): ROBOT_LIBRARY_SCOPE = 'TEST SUITE' ROBOT_LIBRARY_VERSION = get_version() def __init__(self, port, baudrate): super(PhilipAPI, self).__init__(PHILIP_MEM_MAP_PATH, 'serial', port, baudrate) def reset_dut(self): ret = list() ret.append(self.write_reg('sys.cr', 0xff)) ret.append(self.execute_changes()) sleep(1) ret.append(self.write_reg('sys.cr', 0x00)) ret.append(self.execute_changes()) sleep(1) return ret def setup_uart(self, mode=0, baudrate=115200, parity=serial.PARITY_NONE, stopbits=serial.STOPBITS_ONE, rts=True): '''Setup tester's UART.''' ret = list() ret.append(self.write_reg('uart.mode', int(mode))) ret.append(self.write_reg('uart.baud', int(baudrate))) # setup UART control register ctrl = 0 if parity == serial.PARITY_EVEN: ctrl = ctrl | 0x02 elif parity == serial.PARITY_ODD: ctrl = ctrl | 0x04 if stopbits == serial.STOPBITS_TWO: ctrl = ctrl | 0x01 # invert RTS level as it is a low active signal if not rts: ctrl = ctrl | 0x08 ret.append(self.write_reg('uart.ctrl', ctrl)) # reset status register ret.append(self.write_reg('uart.status', 0x00)) # apply changes ret.append(self.execute_changes()) sleep(1) return ret
def __init__(self, cfg='debug.rdb', *bps): from robot import version ROBOT_VERSION = version.get_version() if ROBOT_VERSION < '2.1': sys.__stderr__.write("Robot 2.1 is required for RDB(robot debug).\n") sys.exit(0) self.debuger = RobotDebuger(cfg) self.debuger.run() self.call_stack = [] self.debugCtx = self.debuger.debugCtx self.logger = logging.getLogger("rbt.lis") for e in bps: self.debuger.add_breakpoint(e)
def output_error_in_robot_log(self, e): import traceback from robot.output import LOGGER from robot import version ROBOT_VERSION = version.get_version() if ROBOT_VERSION >= '2.1': syslog = LOGGER from robot.output.loggerhelper import Message syslog.message( Message("%s:%s" % ('Import Keyword Error', e.message), 'ERROR')) syslog.message(Message(traceback.format_exc(), 'ERROR')) else: syslog = LOGGER syslog.error("*ERROR* %s:%s" % ('Import Keyword Error', e.message)) syslog.error(traceback.format_exc())
class Collections(_List, _Dictionary): """A test library providing keywords for handling lists and dictionaries. `Collections` is Robot Framework's standard library that provides a set of keywords for handling Python lists and dictionaries. This library has keywords, for example, for modifying and getting values from lists and dictionaries (e.g. `Append To List`, `Get From Dictionary`) and for verifying their contents (e.g. `Lists Should Be Equal`, `Dictionary Should Contain Value`). Following keywords from the BuiltIn library can also be used with lists and dictionaries: | *Keyword Name* | *Applicable With* | | `Create List` | lists | | `Get Length` | both | | `Length Should Be` | both | | `Should Be Empty` | both | | `Should Not Be Empty` | both | | `Should Contain` | lists | | `Should Not Contain` | lists | | `Should Contain X Times` | lists | | `Should Not Contain X Times` | lists | | `Get Count` | lists | All list keywords expect a scalar variable (e.g. ${list}) as an argument. It is, however, possible to use list variables (e.g. @{list}) as scalars simply by replacing '@' with '$'. List keywords that do not alter the given list can also be used with tuples, and to some extend also with other iterables. `Convert To List` can be used to convert tuples and other iterables to lists. ------- List related keywords use variables in format ${Lx} in their examples, which means a list with as many alphabetic characters as specified by 'x'. For example ${L1} means ['a'] and ${L3} means ['a', 'b', 'c']. Dictionary keywords use similar ${Dx} variables. For example ${D1} means {'a': 1} and ${D3} means {'a': 1, 'b': 2, 'c': 3}. -------- """ ROBOT_LIBRARY_SCOPE = 'GLOBAL' ROBOT_LIBRARY_VERSION = get_version()
class TestData(): """Interface to the node.""" ROBOT_LIBRARY_SCOPE = "TEST" ROBOT_LIBRARY_VERSION = get_version() def get_empty(self): return "" def get_long_list(self): return [i for i in range(0, 500)] def get_long_dict(self): return {f"{str(i)}": i**2 for i in range(0, 500)} def get_long_string(self): return ''.join(random.choices("HEYDSLKJSDFLKJD", k=1000))
def save_environment(self): environment = {} environment['id'] = 'Robot Framework' environment['name'] = socket.getfqdn() environment['url']= 'http://'+socket.getfqdn()+':8000' env_dict = (\ {'Robot Framework Full Version': get_full_version()},\ {'Robot Framework Version': get_version()},\ {'Interpreter': get_interpreter()},\ {'Python version': sys.version.split()[0]},\ {'Allure Adapter version': VERSION},\ {'Robot Framework CLI Arguments': sys.argv[1:]},\ {'Robot Framework Hostname': socket.getfqdn()},\ {'Robot Framework Platform': sys.platform}\ ) for key in env_dict: self.AllureImplc.environment.update(key) self.AllureImplc.logdir = self.AllureProperties.get_property('allure.cli.logs.xml') self.AllureImplc.store_environment(environment)
def close(self): environment = {} environment['id'] = 'Robot Framework' environment['name'] = socket.getfqdn() environment['url']= 'http://'+socket.getfqdn()+':8000' env_dict = (\ {'Robot Framework Full Version': get_full_version()},\ {'Robot Framework Version': get_version()},\ {'Interpreter': get_interpreter()},\ {'Python version': sys.version.split()[0]},\ {'Allure Adapter version': VERSION},\ {'Robot Framework CLI Arguments': sys.argv[1:]},\ {'Robot Framework Hostname': socket.getfqdn()},\ {'Robot Framework Platform': sys.platform}\ ) for key in env_dict: self.AllureImplc.environment.update(key) self.AllureImplc.store_environment(environment) # store the Allure properties # with self.AllureImplc._attachfile('allure.properties') as f: li = self.AllureProperties lilen = int(len(self.AllureProperties)) for i in range(lilen): if i < len(li): key = list(li[i].keys())[0] value = list(li[i].values())[0] f.write(key+'='+value+'\n') f.close() return
class Psw(object): ROBOT_LIBRARY_SCOPE = 'TEST_SUITE' ROBOT_LIBRARY_VERSION = get_version() keywords = [ 'setup connect', '*IDN', 'APPLy', 'OUTPut', 'SYSTem', 'MEASure', 'SOURce' ] def __init__(self, uart_port, baudrate=9600): self._conn = self._get_connection(uart_port, baudrate) #def open_connection(self,) def _get_connection(self, *args): """Can be overridden to use a custom connection.""" self._conn = PswRun(*args) return self._conn def get_keyword_names(self): return Psw.keywords def __getattr__(self, name): return getattr(self._conn or self._get_connection(), name)
if opt in ('-q','--quit'): verbosity = 0 if opt in ('-v', '--verbose'): verbosity = 2 if opt in ('-d', '--doc'): docs = 1 verbosity = 2 return docs, verbosity def usage_exit(msg=None): print __doc__ if msg is None: rc = 251 else: print '\nError:', msg rc = 252 sys.exit(rc) if __name__ == '__main__': print "Testing with Robot version: %s" % get_version() docs, vrbst = parse_args(sys.argv[1:]) tests = get_tests() suite = unittest.TestSuite(tests) runner = unittest.TextTestRunner(descriptions=docs, verbosity=vrbst) result = runner.run(suite) rc = len(result.failures) + len(result.errors) if rc > 250: rc = 250 sys.exit(rc)
class Telnet: """A test library providing communication over Telnet connections. `Telnet` is Robot Framework's standard library that makes it possible to connect to Telnet servers and execute commands on the opened connections. == Table of contents == - `Connections` - `Writing and reading` - `Configuration` - `Terminal emulation` - `Logging` - `Time string format` - `Importing` - `Shortcuts` - `Keywords` = Connections = The first step of using `Telnet` is opening a connection with `Open Connection` keyword. Typically the next step is logging in with `Login` keyword, and in the end the opened connection can be closed with `Close Connection`. It is possible to open multiple connections and switch the active one using `Switch Connection`. `Close All Connections` can be used to close all the connections, which is especially useful in suite teardowns to guarantee that all connections are always closed. = Writing and reading = After opening a connection and possibly logging in, commands can be executed or text written to the connection for other reasons using `Write` and `Write Bare` keywords. The main difference between these two is that the former adds a [#Configuration|configurable newline] after the text automatically. After writing something to the connection, the resulting output can be read using `Read`, `Read Until`, `Read Until Regexp`, and `Read Until Prompt` keywords. Which one to use depends on the context, but the latest one is often the most convenient. As a convenience when running a command, it is possible to use `Execute Command` that simply uses `Write` and `Read Until Prompt` internally. `Write Until Expected Output` is useful if you need to wait until writing something produces a desired output. Written and read text is automatically encoded/decoded using a [#Configuration|configured encoding]. The ANSI escape codes, like cursor movement and color codes, are normally returned as part of the read operation. If an escape code occurs in middle of a search pattern it may also prevent finding the searched string. `Terminal emulation` can be used to process these escape codes as they would be if a real terminal would be in use. = Configuration = Many aspects related the connections can be easily configured either globally or per connection basis. Global configuration is done when [#Importing|library is imported], and these values can be overridden per connection by `Open Connection` or with setting specific keywords `Set Timeout`, `Set Newline`, `Set Prompt`, `Set Encoding`, and `Set Default Log Level` Values of `environ_user`, `window_size`, `terminal_emulation`, and `terminal_type` can not be changed after opening the connection. == Timeout == Timeout defines how long is the maximum time to wait when reading output. It is used internally by `Read Until`, `Read Until Regexp`, `Read Until Prompt`, and `Login` keywords. The default value is 3 seconds. == Newline == Newline defines which line separator `Write` keyword should use. The default value is `CRLF` that is typically used by Telnet connections. Newline can be given either in escaped format using '\\n' and '\\r' or with special 'LF' and 'CR' syntax. Examples: | `Set Newline` | \\n | | `Set Newline` | CRLF | == Prompt == Often the easiest way to read the output of a command is reading all the output until the next prompt with `Read Until Prompt`. It also makes it easier, and faster, to verify did `Login` succeed. Prompt can be specified either as a normal string or a regular expression. The latter is especially useful if the prompt changes as a result of the executed commands. == Encoding == To ease handling text containing non-ASCII characters, all written text is encoded and read text decoded by default. The default encoding is UTF-8 that works also with ASCII. Encoding can be disabled by using a special encoding value `NONE`. This is mainly useful if you need to get the bytes received from the connection as-is. Notice that when writing to the connection, only Unicode strings are encoded using the defined encoding. Byte strings are expected to be already encoded correctly. Notice also that normal text in test data is passed to the library as Unicode and you need to use variables to use bytes. It is also possible to configure the error handler to use if encoding or decoding characters fails. Accepted values are the same that encode/decode functions in Python strings accept. In practice the following values are the most useful: - `ignore`: ignore characters that cannot be encoded (default) - `strict`: fail if characters cannot be encoded - `replace`: replace characters that cannot be encoded with a replacement character Examples: | `Open Connection` | lolcathost | encoding=Latin1 | encoding_errors=strict | | `Set Encoding` | ISO-8859-15 | | `Set Encoding` | errors=ignore | Using UTF-8 encoding by default and being able to configure the encoding are new features in Robot Framework 2.7.6. In earlier versions only ASCII was supported and encoding errors were silently ignored. Robot Framework 2.7.7 added a possibility to specify the error handler, changed the default behavior back to ignoring encoding errors, and added the possibility to disable encoding. == Default log level == Default log level specifies the log level keywords use for `logging` unless they are given an explicit log level. The default value is `INFO`, and changing it, for example, to `DEBUG` can be a good idea if there is lot of unnecessary output that makes log files big. Configuring default log level in `importing` and with `Open Connection` are new features in Robot Framework 2.7.6. In earlier versions only `Set Default Log Level` could be used. == Terminal type == By default the Telnet library does not negotiate any specific terminal type with the server. If a specific terminal type, for example `vt100`, is desired, the terminal type can be configured in `importing` and with `Open Connection`. New in Robot Framework 2.8.2. == Window size == Window size for negotiation with the server can be configured when `importing` the library and with `Open Connection`. New in Robot Framework 2.8.2. == USER environment variable == Telnet protocol allows the `USER` environment variable to be sent when connecting to the server. On some servers it may happen that there is no login prompt, and on those cases this configuration option will allow still to define the desired username. The option `environ_user` can be used in `importing` and with `Open Connection`. New in Robot Framework 2.8.2. = Terminal emulation = Starting from Robot Framework 2.8.2, Telnet library supports terminal emulation with [https://github.com/selectel/pyte|Pyte]. Terminal emulation will process the output in a virtual screen. This means that ANSI escape codes, like cursor movements, and also control characters, like carriage returns and backspaces, have the same effect on the result as they would have on a normal terminal screen. For example the sequence 'acdc\\x1b[3Dbba' will result in output 'abba'. Terminal emulation is taken into use with option terminal_emulation=True, either in the library initialization, or as a option to `Open Connection`. As Pyte approximates vt-style terminal, you may also want to set the terminal type as `vt100`. We also recommend that you increase the window size, as the terminal emulation will break all lines that are longer than the window row length. When terminal emulation is used, the `newline` and `encoding` can not be changed anymore after opening the connection. As a prequisite for using terminal emulation you need to have [https://github.com/selectel/pyte|Pyte] installed. This is easiest done with [http://pip-installer.org|pip] by running `pip install pyte`. Examples: | `Open Connection` | lolcathost | terminal_emulation=True | terminal_type=vt100 | window_size=400x100 | = Logging = All keywords that read something log the output. These keywords take the log level to use as an optional argument, and if no log level is specified they use the [#Configuration|configured] default value. The valid log levels to use are `TRACE`, `DEBUG`, `INFO` (default), and `WARN`. Levels below `INFO` are not shown in log files by default whereas warnings are shown more prominently. The [http://docs.python.org/2/library/telnetlib.html|telnetlib module] used by this library has a custom logging system for logging content it sends and receives. Starting from Robot Framework 2.7.7, these low level log messages are forwarded to Robot's log file using `TRACE` level. = Time string format = Timeouts and other times used must be given as a time string using format in format like '15 seconds' or '1min 10s'. If the timeout is given as just a number, for example, '10' or '1.5', it is considered to be seconds. The time string format is described in more detail in an appendix of [http://code.google.com/p/robotframework/wiki/UserGuide|Robot Framework User Guide]. """ ROBOT_LIBRARY_SCOPE = 'TEST_SUITE' ROBOT_LIBRARY_VERSION = get_version() def __init__(self, timeout='3 seconds', newline='CRLF', prompt=None, prompt_is_regexp=False, encoding='UTF-8', encoding_errors='ignore', default_log_level='INFO', window_size=None, environ_user=None, terminal_emulation=False, terminal_type=None): """Telnet library can be imported with optional configuration parameters. Configuration parameters are used as default values when new connections are opened with `Open Connection` keyword. They can also be overridden after opening the connection using the `Set Timeout`, `Set Newline`, `Set Prompt`, `Set Encoding`, and `Set Default Log Level` keywords. See these keywords as well as `Configuration` and `Terminal emulation` sections above for more information about these parameters and their possible values. Examples (use only one of these): | *Setting* | *Value* | *Value* | *Value* | *Value* | *Value* | *Comment* | | Library | Telnet | | | | | # default values | | Library | Telnet | 0.5 | | | | # set only timeout | | Library | Telnet | | LF | | | # set only newline | | Library | Telnet | newline=LF | encoding=ISO-8859-1 | | | # set newline and encoding using named arguments | | Library | Telnet | 2.0 | LF | | | # set timeout and newline | | Library | Telnet | 2.0 | CRLF | $ | | # set also prompt | | Library | Telnet | 2.0 | LF | (> |# ) | True | # set prompt as a regular expression | | Library | Telnet | terminal_emulation=True | terminal_type=vt100 | window_size=400x100 | | # use terminal emulation with defined window size and terminal type | """ self._timeout = timeout or 3.0 self._newline = newline or 'CRLF' self._prompt = (prompt, bool(prompt_is_regexp)) self._encoding = encoding self._encoding_errors = encoding_errors self._default_log_level = default_log_level self._window_size = self._parse_window_size(window_size) self._environ_user = environ_user self._terminal_emulation = self._parse_terminal_emulation(terminal_emulation) self._terminal_type = terminal_type self._cache = utils.ConnectionCache() self._conn = None self._conn_kws = self._lib_kws = None def get_keyword_names(self): return self._get_library_keywords() + self._get_connection_keywords() def _get_library_keywords(self): if self._lib_kws is None: self._lib_kws = self._get_keywords(self, ['get_keyword_names']) return self._lib_kws def _get_keywords(self, source, excluded): return [name for name in dir(source) if self._is_keyword(name, source, excluded)] def _is_keyword(self, name, source, excluded): return (name not in excluded and not name.startswith('_') and name != 'get_keyword_names' and inspect.ismethod(getattr(source, name))) def _get_connection_keywords(self): if self._conn_kws is None: conn = self._get_connection() excluded = [name for name in dir(telnetlib.Telnet()) if name not in ['write', 'read', 'read_until']] self._conn_kws = self._get_keywords(conn, excluded) return self._conn_kws def __getattr__(self, name): if name not in self._get_connection_keywords(): raise AttributeError(name) # If no connection is initialized, get attributes from a non-active # connection. This makes it possible for Robot to create keyword # handlers when it imports the library. return getattr(self._conn or self._get_connection(), name) def open_connection(self, host, alias=None, port=23, timeout=None, newline=None, prompt=None, prompt_is_regexp=False, encoding=None, encoding_errors=None, default_log_level=None, window_size=None, environ_user=None, terminal_emulation=False, terminal_type=None): """Opens a new Telnet connection to the given host and port. The `timeout`, `newline`, `prompt`, `prompt_is_regexp`, `encoding`, `default_log_level`, `window_size`, `environ_user`, `terminal_emulation`, and `terminal_type` arguments get default values when the library is [#Importing|imported]. Setting them here overrides those values for the opened connection. See `Configuration` and `Terminal emulation` sections for more information. Possible already opened connections are cached and it is possible to switch back to them using `Switch Connection` keyword. It is possible to switch either using explicitly given `alias` or using index returned by this keyword. Indexing starts from 1 and is reset back to it by `Close All Connections` keyword. """ timeout = timeout or self._timeout newline = newline or self._newline encoding = encoding or self._encoding encoding_errors = encoding_errors or self._encoding_errors default_log_level = default_log_level or self._default_log_level window_size = self._parse_window_size(window_size) or self._window_size environ_user = environ_user or self._environ_user terminal_emulation = self._get_terminal_emulation_with_default(terminal_emulation) terminal_type = terminal_type or self._terminal_type if not prompt: prompt, prompt_is_regexp = self._prompt logger.info('Opening connection to %s:%s with prompt: %s' % (host, port, prompt)) self._conn = self._get_connection(host, port, timeout, newline, prompt, prompt_is_regexp, encoding, encoding_errors, default_log_level, window_size, environ_user, terminal_emulation, terminal_type) return self._cache.register(self._conn, alias) def _get_terminal_emulation_with_default(self, terminal_emulation): if terminal_emulation is None or terminal_emulation == '': return self._terminal_emulation return self._parse_terminal_emulation(terminal_emulation) def _parse_terminal_emulation(self, terminal_emulation): if not terminal_emulation: return False if isinstance(terminal_emulation, basestring): return terminal_emulation.lower() == 'true' return bool(terminal_emulation) def _parse_window_size(self, window_size): if not window_size: return None try: cols, rows = window_size.split('x') cols, rows = (int(cols), int(rows)) except: raise AssertionError("Invalid window size '%s'. Should be <rows>x<columns>" % window_size) return cols, rows def _get_connection(self, *args): """Can be overridden to use a custom connection.""" return TelnetConnection(*args) def switch_connection(self, index_or_alias): """Switches between active connections using an index or an alias. Aliases can be given to `Open Connection` keyword which also always returns the connection index. This keyword returns the index of previous active connection. Example: | `Open Connection` | myhost.net | | | | `Login` | john | secret | | | `Write` | some command | | | | `Open Connection` | yourhost.com | 2nd conn | | | `Login` | root | password | | | `Write` | another cmd | | | | ${old index}= | `Switch Connection` | 1 | # index | | `Write` | something | | | | `Switch Connection` | 2nd conn | | # alias | | `Write` | whatever | | | | `Switch Connection` | ${old index} | | # back to original | | [Teardown] | `Close All Connections` | | | The example above expects that there were no other open connections when opening the first one, because it used index '1' when switching to the connection later. If you are not sure about that, you can store the index into a variable as shown below. | ${index} = | `Open Connection` | myhost.net | | `Do Something` | | | | `Switch Connection` | ${index} | | """ old_index = self._cache.current_index self._conn = self._cache.switch(index_or_alias) return old_index def close_all_connections(self): """Closes all open connections and empties the connection cache. If multiple connections are opened, this keyword should be used in a test or suite teardown to make sure that all connections are closed. It is not an error is some of the connections have already been closed by `Close Connection`. After this keyword, new indexes returned by `Open Connection` keyword are reset to 1. """ self._conn = self._cache.close_all()
verbosity = 0 if opt in ("-v", "--verbose"): verbosity = 2 if opt in ("-d", "--doc"): docs = 1 verbosity = 2 return docs, verbosity def usage_exit(msg=None): print __doc__ if msg is None: rc = 251 else: print "\nError:", msg rc = 252 sys.exit(rc) if __name__ == "__main__": print "Testing with Robot version: %s" % get_version() docs, vrbst = parse_args(sys.argv[1:]) tests = get_tests() suite = unittest.TestSuite(tests) runner = unittest.TextTestRunner(descriptions=docs, verbosity=vrbst) result = runner.run(suite) rc = len(result.failures) + len(result.errors) if rc > 250: rc = 250 sys.exit(rc)
The command line entry points provided by the framework are exposed for programmatic usage as follows: * :func:`~robot.run.run`: Function to run tests. * :func:`~robot.run.run_cli`: Function to run tests with command line argument processing. * :func:`~robot.rebot.rebot`: Function to post-process outputs. * :func:`~robot.rebot.rebot_cli`: Function to post-process outputs with command line argument processing. * :mod:`~robot.libdoc`: Module for library documentation generation. * :mod:`~robot.testdoc`: Module for test case documentation generation. * :mod:`~robot.tidy`: Module for test data clean-up and format change. All the functions above can be imported like ``from robot import run``. Functions and classes provided by the modules need to be imported like ``from robot.libdoc import libdoc_cli``. The functions and modules listed above are considered stable. Other modules in this package are for for internal usage and may change without prior notice. .. tip:: More public APIs are exposed by the :mod:`robot.api` package. """ from robot.rebot import rebot, rebot_cli from robot.run import run, run_cli from robot.version import get_version __all__ = ['run', 'run_cli', 'rebot', 'rebot_cli'] __version__ = get_version()
class Process(object): """Robot Framework test library for running processes. This library utilizes Python's [http://docs.python.org/2/library/subprocess.html|subprocess] module and its [http://docs.python.org/2/library/subprocess.html#subprocess.Popen|Popen] class. The library has following main usages: - Running processes in system and waiting for their completion using `Run Process` keyword. - Starting processes on background using `Start Process`. - Waiting started process to complete using `Wait For Process` or stopping them with `Terminate Process` or `Terminate All Processes`. This library is new in Robot Framework 2.8. == Table of contents == - `Specifying command and arguments` - `Process configuration` - `Active process` - `Result object` - `Boolean arguments` - `Using with OperatingSystem library` - `Example` - `Shortcuts` - `Keywords` = Specifying command and arguments = Both `Run Process` and `Start Process` accept the command to execute and all arguments passed to it as separate arguments. This is convenient to use and also allows these keywords to automatically escape possible spaces and other special characters in the command or arguments. When `running processes in shell`, it is also possible to give the whole command to execute as a single string. The command can then contain multiple commands, for example, connected with pipes. When using this approach the caller is responsible on escaping. Examples: | `Run Process` | ${progdir}${/}prog.py | first arg | second | | `Run Process` | script1.sh arg && script2.sh | shell=yes | cwd=${progdir} | Starting from Robot Framework 2.8.6, possible non-string arguments are converted to strings automatically. = Process configuration = `Run Process` and `Start Process` keywords can be configured using optional `**configuration` keyword arguments. Configuration arguments must be given after other arguments passed to these keywords and must use syntax like `name=value`. Available configuration arguments are listed below and discussed further in sections afterwards. | = Name = | = Explanation = | | shell | Specifies whether to run the command in shell or not | | cwd | Specifies the working directory. | | env | Specifies environment variables given to the process. | | env:<name> | Overrides the named environment variable(s) only. | | stdout | Path of a file where to write standard output. | | stderr | Path of a file where to write standard error. | | alias | Alias given to the process. | Note that because `**configuration` is passed using `name=value` syntax, possible equal signs in other arguments passed to `Run Process` and `Start Process` must be escaped with a backslash like `name\\=value`. See `Run Process` for an example. == Running processes in shell == The `shell` argument specifies whether to run the process in a shell or not. By default shell is not used, which means that shell specific commands, like `copy` and `dir` on Windows, are not available. Giving the `shell` argument any non-false value, such as `shell=True`, changes the program to be executed in a shell. It allows using the shell capabilities, but can also make the process invocation operating system dependent. When using a shell it is possible to give the whole command to execute as a single string. See `Specifying command and arguments` section for examples and more details in general. == Current working directory == By default the child process will be executed in the same directory as the parent process, the process running tests, is executed. This can be changed by giving an alternative location using the `cwd` argument. Forward slashes in the given path are automatically converted to backslashes on Windows. `Standard output and error streams`, when redirected to files, are also relative to the current working directory possibly set using the `cwd` argument. Example: | `Run Process` | prog.exe | cwd=${ROOT}/directory | stdout=stdout.txt | == Environment variables == By default the child process will get a copy of the parent process's environment variables. The `env` argument can be used to give the child a custom environment as a Python dictionary. If there is a need to specify only certain environment variable, it is possible to use the `env:<name>=<value>` format to set or override only that named variables. It is also possible to use these two approaches together. Examples: | `Run Process` | program | env=${environ} | | `Run Process` | program | env:http_proxy=10.144.1.10:8080 | env:PATH=%{PATH}${:}${PROGDIR} | | `Run Process` | program | env=${environ} | env:EXTRA=value | == Standard output and error streams == By default processes are run so that their standard output and standard error streams are kept in the memory. This works fine normally, but if there is a lot of output, the output buffers may get full and the program can hang. Additionally on Jython, everything written to these in-memory buffers can be lost if the process is terminated. To avoid the above mentioned problems, it is possible to use `stdout` and `stderr` arguments to specify files on the file system where to redirect the outputs. This can also be useful if other processes or other keywords need to read or manipulate the outputs somehow. Given `stdout` and `stderr` paths are relative to the `current working directory`. Forward slashes in the given paths are automatically converted to backslashes on Windows. As a special feature, it is possible to redirect the standard error to the standard output by using `stderr=STDOUT`. Regardless are outputs redirected to files or not, they are accessible through the `result object` returned when the process ends. Examples: | ${result} = | `Run Process` | program | stdout=${TEMPDIR}/stdout.txt | stderr=${TEMPDIR}/stderr.txt | | `Log Many` | stdout: ${result.stdout} | stderr: ${result.stderr} | | ${result} = | `Run Process` | program | stderr=STDOUT | | `Log` | all output: ${result.stdout} | Note that the created output files are not automatically removed after the test run. The user is responsible to remove them if needed. == Alias == A custom name given to the process that can be used when selecting the `active process`. Examples: | `Start Process` | program | alias=example | | `Run Process` | python | -c | print 'hello' | alias=hello | = Active process = The test library keeps record which of the started processes is currently active. By default it is latest process started with `Start Process`, but `Switch Process` can be used to select a different one. Using `Run Process` does not affect the active process. The keywords that operate on started processes will use the active process by default, but it is possible to explicitly select a different process using the `handle` argument. The handle can be the identifier returned by `Start Process` or an `alias` explicitly given to `Start Process` or `Run Process`. = Result object = `Run Process`, `Wait For Process` and `Terminate Process` keywords return a result object that contains information about the process execution as its attributes. The same result object, or some of its attributes, can also be get using `Get Process Result` keyword. Attributes available in the object are documented in the table below. | = Attribute = | = Explanation = | | rc | Return code of the process as an integer. | | stdout | Contents of the standard output stream. | | stderr | Contents of the standard error stream. | | stdout_path | Path where stdout was redirected or `None` if not redirected. | | stderr_path | Path where stderr was redirected or `None` if not redirected. | Example: | ${result} = | `Run Process` | program | | `Should Be Equal As Integers` | ${result.rc} | 0 | | `Should Match` | ${result.stdout} | Some t?xt* | | `Should Be Empty` | ${result.stderr} | | | ${stdout} = | `Get File` | ${result.stdout_path} | | `Should Be Equal` | ${stdout} | ${result.stdout} | | `File Should Be Empty` | ${result.stderr_path} | | = Boolean arguments = Some keywords accept arguments that are handled as Boolean values. If such an argument is given as a string, it is considered false if it is either empty or case-insensitively equal to `false`. Other strings are considered true regardless what they contain, and other argument types are tested using same [http://docs.python.org/2/library/stdtypes.html#truth-value-testing|rules as in Python]. True examples: | `Terminate Process` | kill=True | # Strings are generally true. | | `Terminate Process` | kill=yes | # Same as above. | | `Terminate Process` | kill=${TRUE} | # Python `True` is true. | | `Terminate Process` | kill=${42} | # Numbers other than 0 are true. | False examples: | `Terminate Process` | kill=False | # String `False` is false. | | `Terminate Process` | kill=${EMPTY} | # Empty string is false. | | `Terminate Process` | kill=${FALSE} | # Python `False` is false. | | `Terminate Process` | kill=${0} | # Number 0 is false. | Note that prior to Robot Framework 2.8 all non-empty strings, including `false`, were considered true. = Using with OperatingSystem library = The OperatingSystem library also contains keywords for running processes. They are not as flexible as the keywords provided by this library, and thus not recommended to be used anymore. They may eventually even be deprecated. There is a name collision because both of these libraries have `Start Process` and `Switch Process` keywords. This is handled so that if both libraries are imported, the keywords in the Process library are used by default. If there is a need to use the OperatingSystem variants, it is possible to use `OperatingSystem.Start Process` syntax or use the `BuiltIn` keyword `Set Library Search Order` to change the priority. Other keywords in the OperatingSystem library can be used freely with keywords in the Process library. = Example = | ***** Settings ***** | Library Process | Suite Teardown `Terminate All Processes` kill=True | | ***** Test Cases ***** | Example | `Start Process` program arg1 arg2 alias=First | ${handle} = `Start Process` command.sh arg | command2.sh shell=True cwd=/path | ${result} = `Run Process` ${CURDIR}/script.py | `Should Not Contain` ${result.stdout} FAIL | `Terminate Process` ${handle} | ${result} = `Wait For Process` First | `Should Be Equal As Integers` ${result.rc} 0 """ ROBOT_LIBRARY_SCOPE = 'GLOBAL' ROBOT_LIBRARY_VERSION = get_version() TERMINATE_TIMEOUT = 30 KILL_TIMEOUT = 10 def __init__(self): self._processes = ConnectionCache('No active process.') self._results = {} def run_process(self, command, *arguments, **configuration): """Runs a process and waits for it to complete. `command` and `*arguments` specify the command to execute and arguments passed to it. See `Specifying command and arguments` for more details. `**configuration` contains additional configuration related to starting processes and waiting for them to finish. See `Process configuration` for more details about configuration related to starting processes. Configuration related to waiting for processes consists of `timeout` and `on_timeout` arguments that have same semantics as with `Wait For Process` keyword. By default there is no timeout, and if timeout is defined the default action on timeout is `terminate`. Returns a `result object` containing information about the execution. Note that possible equal signs in `*arguments` must be escaped with a backslash (e.g. `name\\=value`) to avoid them to be passed in as `**configuration`. Examples: | ${result} = | Run Process | python | -c | print 'Hello, world!' | | Should Be Equal | ${result.stdout} | Hello, world! | | ${result} = | Run Process | ${command} | stderr=STDOUT | timeout=10s | | ${result} = | Run Process | ${command} | timeout=1min | on_timeout=continue | | ${result} = | Run Process | java -Dname\\=value Example | shell=True | cwd=${EXAMPLE} | This command does not change the `active process`. `timeout` and `on_timeout` arguments are new in Robot Framework 2.8.4. """ current = self._processes.current timeout = configuration.pop('timeout', None) on_timeout = configuration.pop('on_timeout', 'terminate') try: handle = self.start_process(command, *arguments, **configuration) return self.wait_for_process(handle, timeout, on_timeout) finally: self._processes.current = current def start_process(self, command, *arguments, **configuration): """Starts a new process on background. See `Specifying command and arguments` and `Process configuration` for more information about the arguments, and `Run Process` keyword for related examples. Makes the started process new `active process`. Returns an identifier that can be used as a handle to active the started process if needed. Starting from Robot Framework 2.8.5, processes are started so that they create a new process group. This allows sending signals to and terminating also possible child processes. """ config = ProcessConfig(**configuration) executable_command = self._cmd(command, arguments, config.shell) logger.info('Starting process:\n%s' % executable_command) logger.debug('Process configuration:\n%s' % config) process = subprocess.Popen(executable_command, **config.full_config) self._results[process] = ExecutionResult(process, config.stdout_stream, config.stderr_stream) return self._processes.register(process, alias=config.alias) def _cmd(self, command, args, use_shell): command = [encode_to_system(item) for item in [command] + list(args)] if not use_shell: return command if args: return subprocess.list2cmdline(command) return command[0] def is_process_running(self, handle=None): """Checks is the process running or not. If `handle` is not given, uses the current `active process`. Returns `True` if the process is still running and `False` otherwise. """ return self._processes[handle].poll() is None def process_should_be_running(self, handle=None, error_message='Process is not running.'): """Verifies that the process is running. If `handle` is not given, uses the current `active process`. Fails if the process has stopped. """ if not self.is_process_running(handle): raise AssertionError(error_message) def process_should_be_stopped(self, handle=None, error_message='Process is running.'): """Verifies that the process is not running. If `handle` is not given, uses the current `active process`. Fails if the process is still running. """ if self.is_process_running(handle): raise AssertionError(error_message) def wait_for_process(self, handle=None, timeout=None, on_timeout='continue'): """Waits for the process to complete or to reach the given timeout. The process to wait for must have been started earlier with `Start Process`. If `handle` is not given, uses the current `active process`. `timeout` defines the maximum time to wait for the process. It is interpreted according to Robot Framework User Guide Appendix `Time Format`, for example, '42', '42 s', or '1 minute 30 seconds'. `on_timeout` defines what to do if the timeout occurs. Possible values and corresponding actions are explained in the table below. Notice that reaching the timeout never fails the test. | = Value = | = Action = | | `continue` | The process is left running (default). | | `terminate` | The process is gracefully terminated. | | `kill` | The process is forcefully stopped. | See `Terminate Process` keyword for more details how processes are terminated and killed. If the process ends before the timeout or it is terminated or killed, this keyword returns a `result object` containing information about the execution. If the process is left running, Python `None` is returned instead. Examples: | # Process ends cleanly | | | | ${result} = | Wait For Process | example | | Process Should Be Stopped | example | | | Should Be Equal As Integers | ${result.rc} | 0 | | # Process does not end | | | | ${result} = | Wait For Process | timeout=42 secs | | Process Should Be Running | | | | Should Be Equal | ${result} | ${NONE} | | # Kill non-ending process | | | | ${result} = | Wait For Process | timeout=1min 30s | on_timeout=kill | | Process Should Be Stopped | | | | Should Be Equal As Integers | ${result.rc} | -9 | `timeout` and `on_timeout` are new in Robot Framework 2.8.2. """ process = self._processes[handle] logger.info('Waiting for process to complete.') if timeout: timeout = timestr_to_secs(timeout) if not self._process_is_stopped(process, timeout): logger.info('Process did not complete in %s.' % secs_to_timestr(timeout)) return self._manage_process_timeout(handle, on_timeout.lower()) return self._wait(process) def _manage_process_timeout(self, handle, on_timeout): if on_timeout == 'terminate': return self.terminate_process(handle) elif on_timeout == 'kill': return self.terminate_process(handle, kill=True) else: logger.info('Leaving process intact.') return None def _wait(self, process): result = self._results[process] result.rc = process.wait() or 0 result.close_streams() logger.info('Process completed.') return result def terminate_process(self, handle=None, kill=False): """Stops the process gracefully or forcefully. If `handle` is not given, uses the current `active process`. Waits for the process to stop after terminating it. Returns a `result object` containing information about the execution similarly as `Wait For Process`. On Unix-like machines, by default, first tries to terminate the process group gracefully, but forcefully kills it if it does not stop in 30 seconds. Kills the process group immediately if the `kill` argument is given any value considered true. See `Boolean arguments` section for more details about true and false values. Termination is done using `TERM (15)` signal and killing using `KILL (9)`. Use `Send Signal To Process` instead if you just want to send either of these signals without waiting for the process to stop. On Windows, by default, sends `CTRL_BREAK_EVENT` signal to the process group. If that does not stop the process in 30 seconds, or `kill` argument is given a true value, uses Win32 API function `TerminateProcess()` to kill the process forcefully. Note that `TerminateProcess()` does not kill possible child processes. | ${result} = | Terminate Process | | | Should Be Equal As Integers | ${result.rc} | -15 | # On Unixes | | Terminate Process | myproc | kill=true | *NOTE:* Stopping processes requires the [http://docs.python.org/2/library/subprocess.html|subprocess] module to have working `terminate` and `kill` functions. They were added in Python 2.6 and are thus missing from earlier versions. With Jython termination is supported starting from Jython 2.7 beta 3 with some limitations. One problem is that everything written to the `standard output and error streams` before termination can be lost unless custom streams are used. A bigger problem is that at least beta 3 does not support killing the process Automatically killing the process if termination fails as well as returning a result object are new features in Robot Framework 2.8.2. Terminating also possible child processes, including using `CTRL_BREAK_EVENT` on Windows, is new in Robot Framework 2.8.5. """ process = self._processes[handle] if not hasattr(process, 'terminate'): raise RuntimeError('Terminating processes is not supported ' 'by this Python version.') terminator = self._kill if is_true(kill) else self._terminate try: terminator(process) except OSError: if not self._process_is_stopped(process, self.KILL_TIMEOUT): raise logger.debug('Ignored OSError because process was stopped.') return self._wait(process) def _kill(self, process): logger.info('Forcefully killing process.') if hasattr(os, 'killpg'): os.killpg(process.pid, signal_module.SIGKILL) else: process.kill() if not self._process_is_stopped(process, self.KILL_TIMEOUT): raise RuntimeError('Failed to kill process.') def _terminate(self, process): logger.info('Gracefully terminating process.') # Sends signal to the whole process group both on POSIX and on Windows # if supported by the interpreter. if hasattr(os, 'killpg'): os.killpg(process.pid, signal_module.SIGTERM) elif hasattr(signal_module, 'CTRL_BREAK_EVENT'): if sys.platform == 'cli': # https://ironpython.codeplex.com/workitem/35020 ctypes.windll.kernel32.GenerateConsoleCtrlEvent( signal_module.CTRL_BREAK_EVENT, process.pid) else: process.send_signal(signal_module.CTRL_BREAK_EVENT) else: process.terminate() if not self._process_is_stopped(process, self.TERMINATE_TIMEOUT): logger.info('Graceful termination failed.') self._kill(process) def terminate_all_processes(self, kill=False): """Terminates all still running processes started by this library. This keyword can be used in suite teardown or elsewhere to make sure that all processes are stopped, By default tries to terminate processes gracefully, but can be configured to forcefully kill them immediately. See `Terminate Process` that this keyword uses internally for more details. """ for handle in range(1, len(self._processes) + 1): if self.is_process_running(handle): self.terminate_process(handle, kill=kill) self.__init__() def send_signal_to_process(self, signal, handle=None, group=False): """Sends the given `signal` to the specified process. If `handle` is not given, uses the current `active process`. Signal can be specified either as an integer, or anything that can be converted to an integer, or as a signal name. In the latter case it is possible to give the name both with or without a `SIG` prefix, but names are case-sensitive. For example, all the examples below send signal `INT (2)`: | Send Signal To Process | 2 | | # Send to active process | | Send Signal To Process | INT | | | | Send Signal To Process | SIGINT | myproc | # Send to named process | What signals are supported depends on the system. For a list of existing signals on your system, see the Unix man pages related to signal handling (typically `man signal` or `man 7 signal`). By default sends the signal only to the parent process, not to possible child processes started by it. Notice that when `running processes in shell`, the shell is the parent process and it depends on the system does the shell propagate the signal to the actual started process. To send the signal to the whole process group, `group` argument can be set to any true value: | Send Signal To Process | TERM | group=yes | If you are stopping a process, it is often easier and safer to use `Terminate Process` keyword instead. *NOTE:* Sending signals requires the [http://docs.python.org/2/library/subprocess.html|subprocess] module to have working `send_signal` function. It was added in Python 2.6 and are thus missing from earlier versions. How well it will work with forthcoming Jython 2.7 is unknown. New in Robot Framework 2.8.2. Support for `group` argument is new in Robot Framework 2.8.5. """ if os.sep == '\\': raise RuntimeError('This keyword does not work on Windows.') process = self._processes[handle] signum = self._get_signal_number(signal) logger.info('Sending signal %s (%d).' % (signal, signum)) if is_true(group) and hasattr(os, 'killpg'): os.killpg(process.pid, signum) elif hasattr(process, 'send_signal'): process.send_signal(signum) else: raise RuntimeError('Sending signals is not supported ' 'by this Python version.') def _get_signal_number(self, int_or_name): try: return int(int_or_name) except ValueError: return self._convert_signal_name_to_number(int_or_name) def _convert_signal_name_to_number(self, name): try: return getattr(signal_module, name if name.startswith('SIG') else 'SIG' + name) except AttributeError: raise RuntimeError("Unsupported signal '%s'." % name) def get_process_id(self, handle=None): """Returns the process ID (pid) of the process. If `handle` is not given, uses the current `active process`. Returns the pid assigned by the operating system as an integer. Note that with Jython, at least with the 2.5 version, the returned pid seems to always be `None`. The pid is not the same as the identifier returned by `Start Process` that is used internally by this library. """ return self._processes[handle].pid def get_process_object(self, handle=None): """Return the underlying `subprocess.Popen` object. If `handle` is not given, uses the current `active process`. """ return self._processes[handle] def get_process_result(self, handle=None, rc=False, stdout=False, stderr=False, stdout_path=False, stderr_path=False): """Returns the specified `result object` or some of its attributes. The given `handle` specifies the process whose results should be returned. If no `handle` is given, results of the current `active process` are returned. In either case, the process must have been finishes before this keyword can be used. In practice this means that processes started with `Start Process` must be finished either with `Wait For Process` or `Terminate Process` before using this keyword. If no other arguments than the optional `handle` are given, a whole `result object` is returned. If one or more of the other arguments are given any true value, only the specified attributes of the `result object` are returned. These attributes are always returned in the same order as arguments are specified in the keyword signature. See `Boolean arguments` section for more details about true and false values. Examples: | Run Process | python | -c | print 'Hello, world!' | alias=myproc | | # Get result object | | | | ${result} = | Get Process Result | myproc | | Should Be Equal | ${result.rc} | ${0} | | Should Be Equal | ${result.stdout} | Hello, world! | | Should Be Empty | ${result.stderr} | | | # Get one attribute | | | | ${stdout} = | Get Process Result | myproc | stdout=true | | Should Be Equal | ${stdout} | Hello, world! | | # Multiple attributes | | | | ${stdout} | ${stderr} = | Get Process Result | myproc | stdout=yes | stderr=yes | | Should Be Equal | ${stdout} | Hello, world! | | Should Be Empty | ${stderr} | | Although getting results of a previously executed process can be handy in general, the main use case for this keyword is returning results over the remote library interface. The remote interface does not support returning the whole result object, but individual attributes can be returned without problems. New in Robot Framework 2.8.2. """ result = self._results[self._processes[handle]] if result.rc is None: raise RuntimeError('Getting results of unfinished processes ' 'is not supported.') attributes = self._get_result_attributes(result, rc, stdout, stderr, stdout_path, stderr_path) if not attributes: return result elif len(attributes) == 1: return attributes[0] return attributes def _get_result_attributes(self, result, *includes): attributes = (result.rc, result.stdout, result.stderr, result.stdout_path, result.stderr_path) includes = (is_true(incl) for incl in includes) return tuple(attr for attr, incl in zip(attributes, includes) if incl) def switch_process(self, handle): """Makes the specified process the current `active process`. The handle can be an identifier returned by `Start Process` or the `alias` given to it explicitly. Example: | Start Process | prog1 | alias=process1 | | Start Process | prog2 | alias=process2 | | # currently active process is process2 | | Switch Process | process1 | | # now active process is process1 | """ self._processes.switch(handle) def _process_is_stopped(self, process, timeout): max_time = time.time() + timeout while time.time() <= max_time: if process.poll() is not None: return True time.sleep(0.1) return False
# The master toctree document. master_doc = 'index' # General information about the project. project = u'Robot Framework' copyright = u'2012, Nokia Siemens Networks' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. version = VERSION # The full version, including alpha/beta/rc tags. release = get_version() # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: #today = '' # Else, today_fmt is used as the format for a strftime call. #today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = ['_build']
class Collections(_List, _Dictionary): """A test library providing keywords for handling lists and dictionaries. ``Collections`` is Robot Framework's standard library that provides a set of keywords for handling Python lists and dictionaries. This library has keywords, for example, for modifying and getting values from lists and dictionaries (e.g. `Append To List`, `Get From Dictionary`) and for verifying their contents (e.g. `Lists Should Be Equal`, `Dictionary Should Contain Value`). Following keywords from the BuiltIn library can also be used with lists and dictionaries: | = Keyword Name = | = Applicable With = | = Comment = | | `Create List` | lists | | `Create Dictionary` | dicts | Was in Collections until RF 2.9. | | `Get Length` | both | | `Length Should Be` | both | | `Should Be Empty` | both | | `Should Not Be Empty` | both | | `Should Contain` | both | | `Should Not Contain` | both | | `Should Contain X Times` | lists | | `Should Not Contain X Times` | lists | | `Get Count` | lists | List keywords that do not alter the given list can also be used with tuples, and to some extend also with other iterables. `Convert To List` can be used to convert tuples and other iterables to lists. ------- List related keywords use variables in format ``${Lx}`` in their examples. They mean lists with as many alphabetic characters as specified by ``x``. For example, ``${L1}`` means ``['a']`` and ``${L3}`` means ``['a', 'b', 'c']``. Dictionary keywords use similar ``${Dx}`` variables. For example, ``${D1}`` means ``{'a': 1}`` and ``${D3}`` means ``{'a': 1, 'b': 2, 'c': 3}``. -------- """ ROBOT_LIBRARY_SCOPE = 'GLOBAL' ROBOT_LIBRARY_VERSION = get_version() def should_contain_match(self, list, pattern, msg=None, case_insensitive=False, whitespace_insensitive=False): """Fails if ``pattern`` is not found in ``list``. See `List Should Contain Value` for an explanation of ``msg``. By default, pattern matching is similar to matching files in a shell and is case-sensitive and whitespace-sensitive. In the pattern syntax, ``*`` matches to anything and ``?`` matches to any single character. You can also prepend ``glob=`` to your pattern to explicitly use this pattern matching behavior. If you prepend ``regexp=`` to your pattern, your pattern will be used according to the Python [http://docs.python.org/2/library/re.html|re module] regular expression syntax. Important note: Backslashes are an escape character, and must be escaped with another backslash (e.g. ``regexp=\\\\d{6}`` to search for ``\\d{6}``). See `BuiltIn.Should Match Regexp` for more details. If ``case_insensitive`` is True, the pattern matching will ignore case. If ``whitespace_insensitive`` is True, the pattern matching will ignore whitespace. Non-string values in lists are ignored when matching patterns. The given list is never altered by this keyword. See also ``Should Not Contain Match``. Examples: | Should Contain Match | ${list} | a* | # List should contain any string beginning with 'a' | | Should Contain Match | ${list} | regexp=a.* | # List should contain any string beginning with 'a' (regexp version) | | Should Contain Match | ${list} | regexp=\\\\d{6} | # List should contain any string which contains six decimal digits | | Should Contain Match | ${list} | a* | case_insensitive=${True} | # List should contain any string beginning with 'a' or 'A' | | Should Contain Match | ${list} | ab* | whitespace_insensitive=${True} | # List should contain any string beginning with 'ab' or 'a b' or any other combination of whitespace | | Should Contain Match | ${list} | ab* | whitespace_insensitive=${True} | case_insensitive=${True} | # List should contain any string beginning with 'ab' or 'a b' or 'AB' or 'A B' or any other combination of whitespace and upper/lower case 'a' and 'b' | New in Robot Framework 2.8.6. """ default = "%s does not contain match for pattern '%s'." % ( seq2str2(list), pattern) _verify_condition( _get_matches_in_iterable(list, pattern, case_insensitive, whitespace_insensitive), default, msg) def should_not_contain_match(self, list, pattern, msg=None, case_insensitive=False, whitespace_insensitive=False): """Fails if ``pattern`` is found in ``list``. See `List Should Contain Value` for an explanation of ``msg``. See `Should Contain Match` for usage details and examples. New in Robot Framework 2.8.6. """ default = "%s contains match for pattern '%s'." % (seq2str2(list), pattern) _verify_condition( not _get_matches_in_iterable(list, pattern, case_insensitive, whitespace_insensitive), default, msg) def get_matches(self, list, pattern, case_insensitive=False, whitespace_insensitive=False): """Returns a list of matches to ``pattern`` in ``list``. For more information on ``pattern``, ``case_insensitive``, and ``whitespace_insensitive``, see `Should Contain Match`. Examples: | ${matches}= | Get Matches | ${list} | a* | # ${matches} will contain any string beginning with 'a' | | ${matches}= | Get Matches | ${list} | regexp=a.* | # ${matches} will contain any string beginning with 'a' (regexp version) | | ${matches}= | Get Matches | ${list} | a* | case_insensitive=${True} | # ${matches} will contain any string beginning with 'a' or 'A' | New in Robot Framework 2.8.6. """ return _get_matches_in_iterable(list, pattern, case_insensitive, whitespace_insensitive) def get_match_count(self, list, pattern, case_insensitive=False, whitespace_insensitive=False): """Returns the count of matches to ``pattern`` in ``list``. For more information on ``pattern``, ``case_insensitive``, and ``whitespace_insensitive``, see `Should Contain Match`. Examples: | ${count}= | Get Match Count | ${list} | a* | # ${count} will be the count of strings beginning with 'a' | | ${count}= | Get Match Count | ${list} | regexp=a.* | # ${matches} will be the count of strings beginning with 'a' (regexp version) | | ${count}= | Get Match Count | ${list} | a* | case_insensitive=${True} | # ${matches} will be the count of strings beginning with 'a' or 'A' | New in Robot Framework 2.8.6. """ return len( self.get_matches(list, pattern, case_insensitive, whitespace_insensitive))
# The encoding of source files. #source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' # General information about the project. project = u'Robot Framework' copyright = u'2008-2015 Nokia Solutions and Networks' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. version = get_version(naked=True) # The full version, including alpha/beta/rc tags. release = get_version() # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: #today = '' # Else, today_fmt is used as the format for a strftime call. #today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files.
# You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. import robot.parsing.populators robot.parsing.populators.PROCESS_CURDIR = False from robot.version import get_version from robot.utils import normpath, NormalizedDict try: # Robot 2.8+ from robot.running.usererrorhandler import UserErrorHandler except ImportError: from robot.common.handlers import UserErrorHandler from robot.parsing import TestCaseFile, ResourceFile, TestDataDirectory from robot.parsing.model import TestCase, UserKeyword from robot.parsing.datarow import DataRow from robot.parsing.model import Variable from robot.running import TestLibrary from robot.output import LOGGER as ROBOT_LOGGER from robot.variables import Variables as RobotVariables from robot.variables import is_scalar_var, is_list_var, is_var, VariableSplitter ROBOT_VERSION = get_version()
class String(object): """A test library for string manipulation and verification. ``String`` is Robot Framework's standard library for manipulating strings (e.g. `Replace String Using Regexp`, `Split To Lines`) and verifying their contents (e.g. `Should Be String`). Following keywords from ``BuiltIn`` library can also be used with strings: - `Catenate` - `Get Length` - `Length Should Be` - `Should (Not) Be Empty` - `Should (Not) Be Equal (As Strings/Integers/Numbers)` - `Should (Not) Match (Regexp)` - `Should (Not) Contain` - `Should (Not) Start With` - `Should (Not) End With` - `Convert To String` - `Convert To Bytes` """ ROBOT_LIBRARY_SCOPE = 'GLOBAL' ROBOT_LIBRARY_VERSION = get_version() def convert_to_lower_case(self, string): """Converts string to lower case. Uses Python's standard [https://docs.python.org/library/stdtypes.html#str.lower|lower()] method. Examples: | ${str1} = | Convert To Lower Case | ABC | | ${str2} = | Convert To Lower Case | 1A2c3D | | Should Be Equal | ${str1} | abc | | Should Be Equal | ${str2} | 1a2c3d | """ # Custom `lower` needed due to IronPython bug. See its code and # comments for more details. return lower(string) def convert_to_upper_case(self, string): """Converts string to upper case. Uses Python's standard [https://docs.python.org/library/stdtypes.html#str.upper|upper()] method. Examples: | ${str1} = | Convert To Upper Case | abc | | ${str2} = | Convert To Upper Case | 1a2C3d | | Should Be Equal | ${str1} | ABC | | Should Be Equal | ${str2} | 1A2C3D | """ return string.upper() @keyword(types=None) def convert_to_title_case(self, string, exclude=None): """Converts string to title case. Uses the following algorithm: - Split the string to words from whitespace characters (spaces, newlines, etc.). - Exclude words that are not all lower case. This preserves, for example, "OK" and "iPhone". - Exclude also words listed in the optional ``exclude`` argument. - Title case the first alphabetical character of each word that has not been excluded. - Join all words together so that original whitespace is preserved. Explicitly excluded words can be given as a list or as a string with words separated by a comma and an optional space. Excluded words are actually considered to be regular expression patterns, so it is possible to use something like "example[.!?]?" to match the word "example" on it own and also if followed by ".", "!" or "?". See `BuiltIn.Should Match Regexp` for more information about Python regular expression syntax in general and how to use it in Robot Framework test data in particular. Examples: | ${str1} = | Convert To Title Case | hello, world! | | ${str2} = | Convert To Title Case | it's an OK iPhone | exclude=a, an, the | | ${str3} = | Convert To Title Case | distance is 1 km. | exclude=is, km.? | | Should Be Equal | ${str1} | Hello, World! | | Should Be Equal | ${str2} | It's an OK iPhone | | Should Be Equal | ${str3} | Distance is 1 km. | The reason this keyword does not use Python's standard [https://docs.python.org/library/stdtypes.html#str.title|title()] method is that it can yield undesired results, for example, if strings contain upper case letters or special characters like apostrophes. It would, for example, convert "it's an OK iPhone" to "It'S An Ok Iphone". New in Robot Framework 3.2. """ if is_string(exclude): exclude = [e.strip() for e in exclude.split(',')] elif not exclude: exclude = [] exclude = [re.compile('^%s$' % e) for e in exclude] def title(word): if any(e.match(word) for e in exclude) or not word.islower(): return word for index, char in enumerate(word): if char.isalpha(): return word[:index] + word[index].title() + word[index + 1:] return word tokens = re.split(r'(\s+)', string, flags=re.UNICODE) return ''.join(title(token) for token in tokens) def encode_string_to_bytes(self, string, encoding, errors='strict'): """Encodes the given Unicode ``string`` to bytes using the given ``encoding``. ``errors`` argument controls what to do if encoding some characters fails. All values accepted by ``encode`` method in Python are valid, but in practice the following values are most useful: - ``strict``: fail if characters cannot be encoded (default) - ``ignore``: ignore characters that cannot be encoded - ``replace``: replace characters that cannot be encoded with a replacement character Examples: | ${bytes} = | Encode String To Bytes | ${string} | UTF-8 | | ${bytes} = | Encode String To Bytes | ${string} | ASCII | errors=ignore | Use `Convert To Bytes` in ``BuiltIn`` if you want to create bytes based on character or integer sequences. Use `Decode Bytes To String` if you need to convert byte strings to Unicode strings and `Convert To String` in ``BuiltIn`` if you need to convert arbitrary objects to Unicode. """ return bytes(string.encode(encoding, errors)) def decode_bytes_to_string(self, bytes, encoding, errors='strict'): """Decodes the given ``bytes`` to a Unicode string using the given ``encoding``. ``errors`` argument controls what to do if decoding some bytes fails. All values accepted by ``decode`` method in Python are valid, but in practice the following values are most useful: - ``strict``: fail if characters cannot be decoded (default) - ``ignore``: ignore characters that cannot be decoded - ``replace``: replace characters that cannot be decoded with a replacement character Examples: | ${string} = | Decode Bytes To String | ${bytes} | UTF-8 | | ${string} = | Decode Bytes To String | ${bytes} | ASCII | errors=ignore | Use `Encode String To Bytes` if you need to convert Unicode strings to byte strings, and `Convert To String` in ``BuiltIn`` if you need to convert arbitrary objects to Unicode strings. """ if PY3 and is_unicode(bytes): raise TypeError('Can not decode strings on Python 3.') return bytes.decode(encoding, errors) def format_string(self, template, *positional, **named): """Formats a ``template`` using the given ``positional`` and ``named`` arguments. The template can be either be a string or an absolute path to an existing file. In the latter case the file is read and its contents are used as the template. If the template file contains non-ASCII characters, it must be encoded using UTF-8. The template is formatted using Python's [https://docs.python.org/library/string.html#format-string-syntax|format string syntax]. Placeholders are marked using ``{}`` with possible field name and format specification inside. Literal curly braces can be inserted by doubling them like `{{` and `}}`. Examples: | ${to} = | Format String | To: {} <{}> | ${user} | ${email} | | ${to} = | Format String | To: {name} <{email}> | name=${name} | email=${email} | | ${to} = | Format String | To: {user.name} <{user.email}> | user=${user} | | ${xx} = | Format String | {:*^30} | centered | | ${yy} = | Format String | {0:{width}{base}} | ${42} | base=X | width=10 | | ${zz} = | Format String | ${CURDIR}/template.txt | positional | named=value | New in Robot Framework 3.1. """ if os.path.isabs(template) and os.path.isfile(template): template = template.replace('/', os.sep) logger.info('Reading template from file <a href="%s">%s</a>.' % (template, template), html=True) with FileReader(template) as reader: template = reader.read() return template.format(*positional, **named) def get_line_count(self, string): """Returns and logs the number of lines in the given string.""" count = len(string.splitlines()) logger.info('%d lines' % count) return count def split_to_lines(self, string, start=0, end=None): """Splits the given string to lines. It is possible to get only a selection of lines from ``start`` to ``end`` so that ``start`` index is inclusive and ``end`` is exclusive. Line numbering starts from 0, and it is possible to use negative indices to refer to lines from the end. Lines are returned without the newlines. The number of returned lines is automatically logged. Examples: | @{lines} = | Split To Lines | ${manylines} | | | | @{ignore first} = | Split To Lines | ${manylines} | 1 | | | @{ignore last} = | Split To Lines | ${manylines} | | -1 | | @{5th to 10th} = | Split To Lines | ${manylines} | 4 | 10 | | @{first two} = | Split To Lines | ${manylines} | | 1 | | @{last two} = | Split To Lines | ${manylines} | -2 | | Use `Get Line` if you only need to get a single line. """ start = self._convert_to_index(start, 'start') end = self._convert_to_index(end, 'end') lines = string.splitlines()[start:end] logger.info('%d lines returned' % len(lines)) return lines def get_line(self, string, line_number): """Returns the specified line from the given ``string``. Line numbering starts from 0 and it is possible to use negative indices to refer to lines from the end. The line is returned without the newline character. Examples: | ${first} = | Get Line | ${string} | 0 | | ${2nd last} = | Get Line | ${string} | -2 | Use `Split To Lines` if all lines are needed. """ line_number = self._convert_to_integer(line_number, 'line_number') return string.splitlines()[line_number] def get_lines_containing_string(self, string, pattern, case_insensitive=False): """Returns lines of the given ``string`` that contain the ``pattern``. The ``pattern`` is always considered to be a normal string, not a glob or regexp pattern. A line matches if the ``pattern`` is found anywhere on it. The match is case-sensitive by default, but giving ``case_insensitive`` a true value makes it case-insensitive. The value is considered true if it is a non-empty string that is not equal to ``false``, ``none`` or ``no``. If the value is not a string, its truth value is got directly in Python. Considering ``none`` false is new in RF 3.0.3. Lines are returned as one string catenated back together with newlines. Possible trailing newline is never returned. The number of matching lines is automatically logged. Examples: | ${lines} = | Get Lines Containing String | ${result} | An example | | ${ret} = | Get Lines Containing String | ${ret} | FAIL | case-insensitive | See `Get Lines Matching Pattern` and `Get Lines Matching Regexp` if you need more complex pattern matching. """ if is_truthy(case_insensitive): pattern = pattern.lower() contains = lambda line: pattern in line.lower() else: contains = lambda line: pattern in line return self._get_matching_lines(string, contains) def get_lines_matching_pattern(self, string, pattern, case_insensitive=False): """Returns lines of the given ``string`` that match the ``pattern``. The ``pattern`` is a _glob pattern_ where: | ``*`` | matches everything | | ``?`` | matches any single character | | ``[chars]`` | matches any character inside square brackets (e.g. ``[abc]`` matches either ``a``, ``b`` or ``c``) | | ``[!chars]`` | matches any character not inside square brackets | A line matches only if it matches the ``pattern`` fully. The match is case-sensitive by default, but giving ``case_insensitive`` a true value makes it case-insensitive. The value is considered true if it is a non-empty string that is not equal to ``false``, ``none`` or ``no``. If the value is not a string, its truth value is got directly in Python. Considering ``none`` false is new in RF 3.0.3. Lines are returned as one string catenated back together with newlines. Possible trailing newline is never returned. The number of matching lines is automatically logged. Examples: | ${lines} = | Get Lines Matching Pattern | ${result} | Wild???? example | | ${ret} = | Get Lines Matching Pattern | ${ret} | FAIL: * | case_insensitive=true | See `Get Lines Matching Regexp` if you need more complex patterns and `Get Lines Containing String` if searching literal strings is enough. """ if is_truthy(case_insensitive): pattern = pattern.lower() matches = lambda line: fnmatchcase(line.lower(), pattern) else: matches = lambda line: fnmatchcase(line, pattern) return self._get_matching_lines(string, matches) def get_lines_matching_regexp(self, string, pattern, partial_match=False): """Returns lines of the given ``string`` that match the regexp ``pattern``. See `BuiltIn.Should Match Regexp` for more information about Python regular expression syntax in general and how to use it in Robot Framework test data in particular. By default lines match only if they match the pattern fully, but partial matching can be enabled by giving the ``partial_match`` argument a true value. The value is considered true if it is a non-empty string that is not equal to ``false``, ``none`` or ``no``. If the value is not a string, its truth value is got directly in Python. Considering ``none`` false is new in RF 3.0.3. If the pattern is empty, it matches only empty lines by default. When partial matching is enabled, empty pattern matches all lines. Notice that to make the match case-insensitive, you need to prefix the pattern with case-insensitive flag ``(?i)``. Lines are returned as one string concatenated back together with newlines. Possible trailing newline is never returned. The number of matching lines is automatically logged. Examples: | ${lines} = | Get Lines Matching Regexp | ${result} | Reg\\\\w{3} example | | ${lines} = | Get Lines Matching Regexp | ${result} | Reg\\\\w{3} example | partial_match=true | | ${ret} = | Get Lines Matching Regexp | ${ret} | (?i)FAIL: .* | See `Get Lines Matching Pattern` and `Get Lines Containing String` if you do not need full regular expression powers (and complexity). ``partial_match`` argument is new in Robot Framework 2.9. In earlier versions exact match was always required. """ if not is_truthy(partial_match): pattern = '^%s$' % pattern return self._get_matching_lines(string, re.compile(pattern).search) def _get_matching_lines(self, string, matches): lines = string.splitlines() matching = [line for line in lines if matches(line)] logger.info('%d out of %d lines matched' % (len(matching), len(lines))) return '\n'.join(matching) def get_regexp_matches(self, string, pattern, *groups): """Returns a list of all non-overlapping matches in the given string. ``string`` is the string to find matches from and ``pattern`` is the regular expression. See `BuiltIn.Should Match Regexp` for more information about Python regular expression syntax in general and how to use it in Robot Framework test data in particular. If no groups are used, the returned list contains full matches. If one group is used, the list contains only contents of that group. If multiple groups are used, the list contains tuples that contain individual group contents. All groups can be given as indexes (starting from 1) and named groups also as names. Examples: | ${no match} = | Get Regexp Matches | the string | xxx | | ${matches} = | Get Regexp Matches | the string | t.. | | ${one group} = | Get Regexp Matches | the string | t(..) | 1 | | ${named group} = | Get Regexp Matches | the string | t(?P<name>..) | name | | ${two groups} = | Get Regexp Matches | the string | t(.)(.) | 1 | 2 | => | ${no match} = [] | ${matches} = ['the', 'tri'] | ${one group} = ['he', 'ri'] | ${named group} = ['he', 'ri'] | ${two groups} = [('h', 'e'), ('r', 'i')] New in Robot Framework 2.9. """ regexp = re.compile(pattern) groups = [self._parse_group(g) for g in groups] return [m.group(*groups) for m in regexp.finditer(string)] def _parse_group(self, group): try: return int(group) except ValueError: return group def replace_string(self, string, search_for, replace_with, count=-1): """Replaces ``search_for`` in the given ``string`` with ``replace_with``. ``search_for`` is used as a literal string. See `Replace String Using Regexp` if more powerful pattern matching is needed. If you need to just remove a string see `Remove String`. If the optional argument ``count`` is given, only that many occurrences from left are replaced. Negative ``count`` means that all occurrences are replaced (default behaviour) and zero means that nothing is done. A modified version of the string is returned and the original string is not altered. Examples: | ${str} = | Replace String | Hello, world! | world | tellus | | Should Be Equal | ${str} | Hello, tellus! | | | | ${str} = | Replace String | Hello, world! | l | ${EMPTY} | count=1 | | Should Be Equal | ${str} | Helo, world! | | | """ count = self._convert_to_integer(count, 'count') return string.replace(search_for, replace_with, count) def replace_string_using_regexp(self, string, pattern, replace_with, count=-1): """Replaces ``pattern`` in the given ``string`` with ``replace_with``. This keyword is otherwise identical to `Replace String`, but the ``pattern`` to search for is considered to be a regular expression. See `BuiltIn.Should Match Regexp` for more information about Python regular expression syntax in general and how to use it in Robot Framework test data in particular. If you need to just remove a string see `Remove String Using Regexp`. Examples: | ${str} = | Replace String Using Regexp | ${str} | 20\\\\d\\\\d-\\\\d\\\\d-\\\\d\\\\d | <DATE> | | ${str} = | Replace String Using Regexp | ${str} | (Hello|Hi) | ${EMPTY} | count=1 | """ count = self._convert_to_integer(count, 'count') # re.sub handles 0 and negative counts differently than string.replace if count == 0: return string return re.sub(pattern, replace_with, string, max(count, 0)) def remove_string(self, string, *removables): """Removes all ``removables`` from the given ``string``. ``removables`` are used as literal strings. Each removable will be matched to a temporary string from which preceding removables have been already removed. See second example below. Use `Remove String Using Regexp` if more powerful pattern matching is needed. If only a certain number of matches should be removed, `Replace String` or `Replace String Using Regexp` can be used. A modified version of the string is returned and the original string is not altered. Examples: | ${str} = | Remove String | Robot Framework | work | | Should Be Equal | ${str} | Robot Frame | | ${str} = | Remove String | Robot Framework | o | bt | | Should Be Equal | ${str} | R Framewrk | """ for removable in removables: string = self.replace_string(string, removable, '') return string def remove_string_using_regexp(self, string, *patterns): """Removes ``patterns`` from the given ``string``. This keyword is otherwise identical to `Remove String`, but the ``patterns`` to search for are considered to be a regular expression. See `Replace String Using Regexp` for more information about the regular expression syntax. That keyword can also be used if there is a need to remove only a certain number of occurrences. """ for pattern in patterns: string = self.replace_string_using_regexp(string, pattern, '') return string @keyword(types=None) def split_string(self, string, separator=None, max_split=-1): """Splits the ``string`` using ``separator`` as a delimiter string. If a ``separator`` is not given, any whitespace string is a separator. In that case also possible consecutive whitespace as well as leading and trailing whitespace is ignored. Split words are returned as a list. If the optional ``max_split`` is given, at most ``max_split`` splits are done, and the returned list will have maximum ``max_split + 1`` elements. Examples: | @{words} = | Split String | ${string} | | @{words} = | Split String | ${string} | ,${SPACE} | | ${pre} | ${post} = | Split String | ${string} | :: | 1 | See `Split String From Right` if you want to start splitting from right, and `Fetch From Left` and `Fetch From Right` if you only want to get first/last part of the string. """ if separator == '': separator = None max_split = self._convert_to_integer(max_split, 'max_split') return string.split(separator, max_split) @keyword(types=None) def split_string_from_right(self, string, separator=None, max_split=-1): """Splits the ``string`` using ``separator`` starting from right. Same as `Split String`, but splitting is started from right. This has an effect only when ``max_split`` is given. Examples: | ${first} | ${rest} = | Split String | ${string} | - | 1 | | ${rest} | ${last} = | Split String From Right | ${string} | - | 1 | """ if separator == '': separator = None max_split = self._convert_to_integer(max_split, 'max_split') return string.rsplit(separator, max_split) def split_string_to_characters(self, string): """Splits the given ``string`` to characters. Example: | @{characters} = | Split String To Characters | ${string} | """ return list(string) def fetch_from_left(self, string, marker): """Returns contents of the ``string`` before the first occurrence of ``marker``. If the ``marker`` is not found, whole string is returned. See also `Fetch From Right`, `Split String` and `Split String From Right`. """ return string.split(marker)[0] def fetch_from_right(self, string, marker): """Returns contents of the ``string`` after the last occurrence of ``marker``. If the ``marker`` is not found, whole string is returned. See also `Fetch From Left`, `Split String` and `Split String From Right`. """ return string.split(marker)[-1] def generate_random_string(self, length=8, chars='[LETTERS][NUMBERS]'): """Generates a string with a desired ``length`` from the given ``chars``. The population sequence ``chars`` contains the characters to use when generating the random string. It can contain any characters, and it is possible to use special markers explained in the table below: | = Marker = | = Explanation = | | ``[LOWER]`` | Lowercase ASCII characters from ``a`` to ``z``. | | ``[UPPER]`` | Uppercase ASCII characters from ``A`` to ``Z``. | | ``[LETTERS]`` | Lowercase and uppercase ASCII characters. | | ``[NUMBERS]`` | Numbers from 0 to 9. | Examples: | ${ret} = | Generate Random String | | ${low} = | Generate Random String | 12 | [LOWER] | | ${bin} = | Generate Random String | 8 | 01 | | ${hex} = | Generate Random String | 4 | [NUMBERS]abcdef | """ if length == '': length = 8 length = self._convert_to_integer(length, 'length') for name, value in [('[LOWER]', ascii_lowercase), ('[UPPER]', ascii_uppercase), ('[LETTERS]', ascii_lowercase + ascii_uppercase), ('[NUMBERS]', digits)]: chars = chars.replace(name, value) maxi = len(chars) - 1 return ''.join(chars[randint(0, maxi)] for _ in range(length)) def get_substring(self, string, start, end=None): """Returns a substring from ``start`` index to ``end`` index. The ``start`` index is inclusive and ``end`` is exclusive. Indexing starts from 0, and it is possible to use negative indices to refer to characters from the end. Examples: | ${ignore first} = | Get Substring | ${string} | 1 | | | ${ignore last} = | Get Substring | ${string} | | -1 | | ${5th to 10th} = | Get Substring | ${string} | 4 | 10 | | ${first two} = | Get Substring | ${string} | | 1 | | ${last two} = | Get Substring | ${string} | -2 | | """ start = self._convert_to_index(start, 'start') end = self._convert_to_index(end, 'end') return string[start:end] @keyword(types=None) def strip_string(self, string, mode='both', characters=None): """Remove leading and/or trailing whitespaces from the given string. ``mode`` is either ``left`` to remove leading characters, ``right`` to remove trailing characters, ``both`` (default) to remove the characters from both sides of the string or ``none`` to return the unmodified string. If the optional ``characters`` is given, it must be a string and the characters in the string will be stripped in the string. Please note, that this is not a substring to be removed but a list of characters, see the example below. Examples: | ${stripped}= | Strip String | ${SPACE}Hello${SPACE} | | | Should Be Equal | ${stripped} | Hello | | | ${stripped}= | Strip String | ${SPACE}Hello${SPACE} | mode=left | | Should Be Equal | ${stripped} | Hello${SPACE} | | | ${stripped}= | Strip String | aabaHelloeee | characters=abe | | Should Be Equal | ${stripped} | Hello | | New in Robot Framework 3.0. """ try: method = { 'BOTH': string.strip, 'LEFT': string.lstrip, 'RIGHT': string.rstrip, 'NONE': lambda characters: string }[mode.upper()] except KeyError: raise ValueError("Invalid mode '%s'." % mode) return method(characters) def should_be_string(self, item, msg=None): """Fails if the given ``item`` is not a string. With Python 2, except with IronPython, this keyword passes regardless is the ``item`` a Unicode string or a byte string. Use `Should Be Unicode String` or `Should Be Byte String` if you want to restrict the string type. Notice that with Python 2, except with IronPython, ``'string'`` creates a byte string and ``u'unicode'`` must be used to create a Unicode string. With Python 3 and IronPython, this keyword passes if the string is a Unicode string but fails if it is bytes. Notice that with both Python 3 and IronPython, ``'string'`` creates a Unicode string, and ``b'bytes'`` must be used to create a byte string. The default error message can be overridden with the optional ``msg`` argument. """ if not is_string(item): self._fail(msg, "'%s' is not a string.", item) def should_not_be_string(self, item, msg=None): """Fails if the given ``item`` is a string. See `Should Be String` for more details about Unicode strings and byte strings. The default error message can be overridden with the optional ``msg`` argument. """ if is_string(item): self._fail(msg, "'%s' is a string.", item) def should_be_unicode_string(self, item, msg=None): """Fails if the given ``item`` is not a Unicode string. Use `Should Be Byte String` if you want to verify the ``item`` is a byte string, or `Should Be String` if both Unicode and byte strings are fine. See `Should Be String` for more details about Unicode strings and byte strings. The default error message can be overridden with the optional ``msg`` argument. """ if not is_unicode(item): self._fail(msg, "'%s' is not a Unicode string.", item) def should_be_byte_string(self, item, msg=None): """Fails if the given ``item`` is not a byte string. Use `Should Be Unicode String` if you want to verify the ``item`` is a Unicode string, or `Should Be String` if both Unicode and byte strings are fine. See `Should Be String` for more details about Unicode strings and byte strings. The default error message can be overridden with the optional ``msg`` argument. """ if not is_bytes(item): self._fail(msg, "'%s' is not a byte string.", item) def should_be_lowercase(self, string, msg=None): """Fails if the given ``string`` is not in lowercase. For example, ``'string'`` and ``'with specials!'`` would pass, and ``'String'``, ``''`` and ``' '`` would fail. The default error message can be overridden with the optional ``msg`` argument. See also `Should Be Uppercase` and `Should Be Titlecase`. """ if not string.islower(): self._fail(msg, "'%s' is not lowercase.", string) def should_be_uppercase(self, string, msg=None): """Fails if the given ``string`` is not in uppercase. For example, ``'STRING'`` and ``'WITH SPECIALS!'`` would pass, and ``'String'``, ``''`` and ``' '`` would fail. The default error message can be overridden with the optional ``msg`` argument. See also `Should Be Titlecase` and `Should Be Lowercase`. """ if not string.isupper(): self._fail(msg, "'%s' is not uppercase.", string) def should_be_titlecase(self, string, msg=None): """Fails if given ``string`` is not title. ``string`` is a titlecased string if there is at least one character in it, uppercase characters only follow uncased characters and lowercase characters only cased ones. For example, ``'This Is Title'`` would pass, and ``'Word In UPPER'``, ``'Word In lower'``, ``''`` and ``' '`` would fail. The default error message can be overridden with the optional ``msg`` argument. See also `Should Be Uppercase` and `Should Be Lowercase`. """ if not string.istitle(): self._fail(msg, "'%s' is not titlecase.", string) def _convert_to_index(self, value, name): if value == '': return 0 if value is None: return None return self._convert_to_integer(value, name) def _convert_to_integer(self, value, name): try: return int(value) except ValueError: raise ValueError( "Cannot convert '%s' argument '%s' to an integer." % (name, value)) def _fail(self, message, default_template, *items): if not message: message = default_template % tuple(unic(item) for item in items) raise AssertionError(message)
class Screenshot(object): """Test library for taking screenshots on the machine where tests are run. Notice that successfully taking screenshots requires tests to be run with a physical or virtual display. *Using with Python* With Python you need to have one of the following modules installed to be able to use this library. The first module that is found will be used. - wxPython :: http://wxpython.org :: Required also by RIDE so many Robot Framework users already have this module installed. - PyGTK :: http://pygtk.org :: This module is available by default on most Linux distributions. - Python Imaging Library (PIL) :: http://www.pythonware.com/products/pil :: This module can take screenshots only on Windows. Python support was added in Robot Framework 2.5.5. *Using with Jython and IronPython* With Jython and IronPython this library uses APIs provided by JVM and .NET platforms, respectively. These APIs are always available and thus no external modules are needed. IronPython support was added in Robot Framework 2.7.5. *Where screenshots are saved* By default screenshots are saved into the same directory where the Robot Framework log file is written. If no log is created, screenshots are saved into the directory where the XML output file is written. It is possible to specify a custom location for screenshots using `screenshot_directory` argument in `importing` and `Set Screenshot Directory` keyword during execution. It is also possible to save screenshots using an absolute path. Note that prior to Robot Framework 2.5.5 the default screenshot location was system's temporary directory. *Changes in Robot Framework 2.5.5 and Robot Framework 2.6* This library was heavily enhanced in Robot Framework 2.5.5 release. The changes are listed below and explained more thoroughly in affected places. - The support for using this library on Python (see above) was added. - The default location where screenshots are saved was changed (see above). - New `Take Screenshot` and `Take Screenshot Without Embedding` keywords were added. These keywords should be used for taking screenshots in the future. Other screenshot taking keywords will be deprecated and removed later. - `log_file_directory` argument was deprecated everywhere it was used. In Robot Framework 2.6, following additional changes were made: - `log_file_directory` argument was removed altogether. - `Set Screenshot Directories` keyword was removed. - `Save Screenshot`, `Save Screenshot To` and `Log Screenshot` keywords were deprecated. They will be removed in Robot Framework 2.8. """ ROBOT_LIBRARY_SCOPE = 'TEST SUITE' ROBOT_LIBRARY_VERSION = get_version() def __init__(self, screenshot_directory=None): """Configure where screenshots are saved. If `screenshot_directory` is not given, screenshots are saved into same directory as the log file. The directory can also be set using `Set Screenshot Directory` keyword. Examples (use only one of these): | *Setting* | *Value* | *Value* | *Value* | | Library | Screenshot | | # Default location | | Library | Screenshot | ${TEMPDIR} | # System temp (this was default prior to 2.5.5) | """ self._given_screenshot_dir = self._norm_path(screenshot_directory) self._screenshot_taker = ScreenshotTaker() def _norm_path(self, path): if not path: return path return os.path.normpath(path.replace('/', os.sep)) @property def _screenshot_dir(self): return self._given_screenshot_dir or self._log_dir @property def _log_dir(self): variables = BuiltIn().get_variables() outdir = variables['${OUTPUTDIR}'] log = variables['${LOGFILE}'] log = os.path.dirname(log) if log != 'NONE' else '.' return self._norm_path(os.path.join(outdir, log)) def set_screenshot_directory(self, path): """Sets the directory where screenshots are saved. It is possible to use `/` as a path separator in all operating systems. Path to the old directory is returned. The directory can also be set in `importing`. """ path = self._norm_path(path) if not os.path.isdir(path): raise RuntimeError("Directory '%s' does not exist." % path) old = self._screenshot_dir self._given_screenshot_dir = path return old def save_screenshot_to(self, path): """*DEPRECATED* Use `Take Screenshot` or `Take Screenshot Without Embedding` instead.""" path = self._screenshot_to_file(path) self._link_screenshot(path) return path def save_screenshot(self, basename="screenshot", directory=None): """*DEPRECATED* Use `Take Screenshot` or `Take Screenshot Without Embedding` instead.""" path = self._save_screenshot(basename, directory) self._link_screenshot(path) return path def log_screenshot(self, basename='screenshot', directory=None, width='100%'): """*DEPRECATED* Use `Take Screenshot` or `Take Screenshot Without Embedding` instead.""" path = self._save_screenshot(basename, directory) self._embed_screenshot(path, width) return path def take_screenshot(self, name="screenshot", width="800px"): """Takes a screenshot in JPEG format and embeds it into the log file. Name of the file where the screenshot is stored is derived from the given `name`. If the `name` ends with extension `.jpg` or `.jpeg`, the screenshot will be stored with that exact name. Otherwise a unique name is created by adding an underscore, a running index and an extension to the `name`. The name will be interpreted to be relative to the directory where the log file is written. It is also possible to use absolute paths. Using `/` as a path separator works in all operating systems. `width` specifies the size of the screenshot in the log file. Examples: (LOGDIR is determined automatically by the library) | Take Screenshot | | | # LOGDIR/screenshot_1.jpg (index automatically incremented) | | Take Screenshot | mypic | | # LOGDIR/mypic_1.jpg (index automatically incremented) | | Take Screenshot | ${TEMPDIR}/mypic | | # /tmp/mypic_1.jpg (index automatically incremented) | | Take Screenshot | pic.jpg | | # LOGDIR/pic.jpg (always uses this file) | | Take Screenshot | images/login.jpg | 80% | # Specify both name and width. | | Take Screenshot | width=550px | | # Specify only width. | The path where the screenshot is saved is returned. """ path = self._save_screenshot(name) self._embed_screenshot(path, width) return path def take_screenshot_without_embedding(self, name="screenshot"): """Takes a screenshot and links it from the log file. This keyword is otherwise identical to `Take Screenshot` but the saved screenshot is not embedded into the log file. The screenshot is linked so it is nevertheless easily available. """ path = self._save_screenshot(name) self._link_screenshot(path) return path def _save_screenshot(self, basename, directory=None): path = self._get_screenshot_path(basename, directory) return self._screenshot_to_file(path) def _screenshot_to_file(self, path): path = self._validate_screenshot_path(path) logger.debug('Using %s modules for taking screenshot.' % self._screenshot_taker.module) try: self._screenshot_taker(path) except: logger.warn( 'Taking screenshot failed: %s\n' 'Make sure tests are run with a physical or virtual display.' % utils.get_error_message()) return path def _validate_screenshot_path(self, path): path = utils.abspath(self._norm_path(path)) if not os.path.exists(os.path.dirname(path)): raise RuntimeError("Directory '%s' where to save the screenshot " "does not exist" % os.path.dirname(path)) return path def _get_screenshot_path(self, basename, directory): directory = self._norm_path( directory) if directory else self._screenshot_dir if basename.lower().endswith(('.jpg', '.jpeg')): return os.path.join(directory, basename) index = 0 while True: index += 1 path = os.path.join(directory, "%s_%d.jpg" % (basename, index)) if not os.path.exists(path): return path def _embed_screenshot(self, path, width): link = utils.get_link_path(path, self._log_dir) logger.info('<a href="%s"><img src="%s" width="%s"></a>' % (link, link, width), html=True) def _link_screenshot(self, path): link = utils.get_link_path(path, self._log_dir) logger.info("Screenshot saved to '<a href=\"%s\">%s</a>'." % (link, path), html=True)
class String(object): """A test library for string manipulation and verification. `String` is Robot Framework's standard library for manipulating strings (e.g. `Replace String Using Regexp`, `Split To Lines`) and verifying their contents (e.g. `Should Be String`). Following keywords from `BuiltIn` library can also be used with strings: - `Catenate` - `Get Length` - `Length Should Be` - `Should (Not) Be Empty` - `Should (Not) Be Equal (As Strings/Integers/Numbers)` - `Should (Not) Match (Regexp)` - `Should (Not) Contain` - `Should (Not) Start With` - `Should (Not) End With` - `Convert To String` - `Convert To Bytes` """ ROBOT_LIBRARY_SCOPE = 'GLOBAL' ROBOT_LIBRARY_VERSION = get_version() def encode_string_to_bytes(self, string, encoding, errors='strict'): """Encodes the given Unicode `string` to bytes using the given `encoding`. `errors` argument controls what to do if encoding some characters fails. All values accepted by `encode` method in Python are valid, but in practice the following values are most useful: - `strict`: fail if characters cannot be encoded (default) - `ignore`: ignore characters that cannot be encoded - `replace`: replace characters that cannot be encoded with a replacement character Examples: | ${bytes} = | Encode String To Bytes | ${string} | UTF-8 | | ${bytes} = | Encode String To Bytes | ${string} | ASCII | errors=ignore | Use `Convert To Bytes` in `BuiltIn` if you want to create bytes based on character or integer sequences. Use `Decode Bytes To String` if you need to convert byte strings to Unicode strings and `Convert To String` in `BuiltIn` if you need to convert arbitrary objects to Unicode. New in Robot Framework 2.7.7. """ return string.encode(encoding, errors) def decode_bytes_to_string(self, bytes, encoding, errors='strict'): """Decodes the given `bytes` to a Unicode string using the given `encoding`. `errors` argument controls what to do if decoding some bytes fails. All values accepted by `decode` method in Python are valid, but in practice the following values are most useful: - `strict`: fail if characters cannot be decoded (default) - `ignore`: ignore characters that cannot be decoded - `replace`: replace characters that cannot be decoded with a replacement character Examples: | ${string} = | Decode Bytes To String | ${bytes} | UTF-8 | | ${string} = | Decode Bytes To String | ${bytes} | ASCII | errors=ignore | Use `Encode String To Bytes` if you need to convert Unicode strings to byte strings, and `Convert To String` in `BuiltIn` if you need to convert arbitrary objects to Unicode strings. New in Robot Framework 2.7.7. """ return bytes.decode(encoding, errors) def get_line_count(self, string): """Returns and logs the number of lines in the given `string`.""" count = len(string.splitlines()) logger.info('%d lines' % count) return count def split_to_lines(self, string, start=0, end=None): """Converts the `string` into a list of lines. It is possible to get only a selection of lines from `start` to `end` so that `start` index is inclusive and `end` is exclusive. Line numbering starts from 0, and it is possible to use negative indices to refer to lines from the end. Lines are returned without the newlines. The number of returned lines is automatically logged. Examples: | @{lines} = | Split To Lines | ${manylines} | | | | @{ignore first} = | Split To Lines | ${manylines} | 1 | | | @{ignore last} = | Split To Lines | ${manylines} | | -1 | | @{5th to 10th} = | Split To Lines | ${manylines} | 4 | 10 | | @{first two} = | Split To Lines | ${manylines} | | 1 | | @{last two} = | Split To Lines | ${manylines} | -2 | | Use `Get Line` if you only need to get a single line. """ start = self._convert_to_index(start, 'start') end = self._convert_to_index(end, 'end') lines = string.splitlines()[start:end] logger.info('%d lines returned' % len(lines)) return lines def get_line(self, string, line_number): """Returns the specified line from the given `string`. Line numbering starts from 0 and it is possible to use negative indices to refer to lines from the end. The line is returned without the newline character. Examples: | ${first} = | Get Line | ${string} | 0 | | ${2nd last} = | Get Line | ${string} | -2 | """ line_number = self._convert_to_integer(line_number, 'line_number') return string.splitlines()[line_number] def get_lines_containing_string(self, string, pattern, case_insensitive=False): """Returns lines of the given `string` that contain the `pattern`. The `pattern` is always considered to be a normal string and a line matches if the `pattern` is found anywhere in it. By default the match is case-sensitive, but setting `case_insensitive` to any value makes it case-insensitive. Lines are returned as one string catenated back together with newlines. Possible trailing newline is never returned. The number of matching lines is automatically logged. Examples: | ${lines} = | Get Lines Containing String | ${result} | An example | | ${ret} = | Get Lines Containing String | ${ret} | FAIL | case-insensitive | See `Get Lines Matching Pattern` and `Get Lines Matching Regexp` if you need more complex pattern matching. """ if case_insensitive: pattern = pattern.lower() contains = lambda line: pattern in line.lower() else: contains = lambda line: pattern in line return self._get_matching_lines(string, contains) def get_lines_matching_pattern(self, string, pattern, case_insensitive=False): """Returns lines of the given `string` that match the `pattern`. The `pattern` is a _glob pattern_ where: | * | matches everything | | ? | matches any single character | | [chars] | matches any character inside square brackets (e.g. '[abc]' matches either 'a', 'b' or 'c') | | [!chars] | matches any character not inside square brackets | A line matches only if it matches the `pattern` fully. By default the match is case-sensitive, but setting `case_insensitive` to any value makes it case-insensitive. Lines are returned as one string catenated back together with newlines. Possible trailing newline is never returned. The number of matching lines is automatically logged. Examples: | ${lines} = | Get Lines Matching Pattern | ${result} | Wild???? example | | ${ret} = | Get Lines Matching Pattern | ${ret} | FAIL: * | case-insensitive | See `Get Lines Matching Regexp` if you need more complex patterns and `Get Lines Containing String` if searching literal strings is enough. """ if case_insensitive: pattern = pattern.lower() matches = lambda line: fnmatchcase(line.lower(), pattern) else: matches = lambda line: fnmatchcase(line, pattern) return self._get_matching_lines(string, matches) def get_lines_matching_regexp(self, string, pattern): """Returns lines of the given `string` that match the regexp `pattern`. See `BuiltIn.Should Match Regexp` for more information about Python regular expression syntax in general and how to use it in Robot Framework test data in particular. A line matches only if it matches the `pattern` fully. Notice that to make the match case-insensitive, you need to embed case-insensitive flag into the pattern. Lines are returned as one string catenated back together with newlines. Possible trailing newline is never returned. The number of matching lines is automatically logged. Examples: | ${lines} = | Get Lines Matching Regexp | ${result} | Reg\\\\w{3} example | | ${ret} = | Get Lines Matching Regexp | ${ret} | (?i)FAIL: .* | See `Get Lines Matching Pattern` and `Get Lines Containing String` if you do not need full regular expression powers (and complexity). """ regexp = re.compile('^%s$' % pattern) return self._get_matching_lines(string, regexp.match) def _get_matching_lines(self, string, matches): lines = string.splitlines() matching = [line for line in lines if matches(line)] logger.info('%d out of %d lines matched' % (len(matching), len(lines))) return '\n'.join(matching) def replace_string(self, string, search_for, replace_with, count=-1): """Replaces `search_for` in the given `string` with `replace_with`. `search_for` is used as a literal string. See `Replace String Using Regexp` if more powerful pattern matching is needed. If you need to just remove a string see `Remove String`. If the optional argument `count` is given, only that many occurrences from left are replaced. Negative `count` means that all occurrences are replaced (default behaviour) and zero means that nothing is done. A modified version of the string is returned and the original string is not altered. Examples: | ${str} = | Replace String | Hello, world! | world | tellus | | Should Be Equal | ${str} | Hello, tellus! | | | | ${str} = | Replace String | Hello, world! | l | ${EMPTY} | count=1 | | Should Be Equal | ${str} | Helo, world! | | | """ count = self._convert_to_integer(count, 'count') return string.replace(search_for, replace_with, count) def replace_string_using_regexp(self, string, pattern, replace_with, count=-1): """Replaces `pattern` in the given `string` with `replace_with`. This keyword is otherwise identical to `Replace String`, but the `pattern` to search for is considered to be a regular expression. See `BuiltIn.Should Match Regexp` for more information about Python regular expression syntax in general and how to use it in Robot Framework test data in particular. If you need to just remove a string see `Remove String Using Regexp`. Examples: | ${str} = | Replace String Using Regexp | ${str} | 20\\\\d\\\\d-\\\\d\\\\d-\\\\d\\\\d | <DATE> | | ${str} = | Replace String Using Regexp | ${str} | (Hello|Hi) | ${EMPTY} | count=1 | """ count = self._convert_to_integer(count, 'count') # re.sub handles 0 and negative counts differently than string.replace if count == 0: return string return re.sub(pattern, replace_with, string, max(count, 0)) def remove_string(self, string, *removables): """Removes all `removables` from the given `string`. `removables` are used as literal strings. Each removable will be matched to a temporary string from which preceding removables have been already removed. See second example below. Use `Remove String Using Regexp` if more powerful pattern matching is needed. If only a certain number of matches should be removed, `Replace String` or `Replace String Using Regexp` can be used. A modified version of the string is returned and the original string is not altered. Examples: | ${str} = | Remove String | Robot Framework | work | | Should Be Equal | ${str} | Robot Frame | | ${str} = | Remove String | Robot Framework | o | bt | | Should Be Equal | ${str} | R Framewrk | New in Robot Framework 2.8.2. """ for removable in removables: string = self.replace_string(string, removable, '') return string def remove_string_using_regexp(self, string, *patterns): """Removes `patterns` from the given `string`. This keyword is otherwise identical to `Remove String`, but the `patterns` to search for are considered to be a regular expression. See `Replace String Using Regexp` for more information about the regular expression syntax. That keyword can also be used if there is a need to remove only a certain number of occurrences. New in Robot Framework 2.8.2. """ for pattern in patterns: string = self.replace_string_using_regexp(string, pattern, '') return string def split_string(self, string, separator=None, max_split=-1): """Splits the `string` using `separator` as a delimiter string. If a `separator` is not given, any whitespace string is a separator. In that case also possible consecutive whitespace as well as leading and trailing whitespace is ignored. Split words are returned as a list. If the optional `max_split` is given, at most `max_split` splits are done, and the returned list will have maximum `max_split + 1` elements. Examples: | @{words} = | Split String | ${string} | | @{words} = | Split String | ${string} | ,${SPACE} | | ${pre} | ${post} = | Split String | ${string} | :: | 1 | See `Split String From Right` if you want to start splitting from right, and `Fetch From Left` and `Fetch From Right` if you only want to get first/last part of the string. """ if separator == '': separator = None max_split = self._convert_to_integer(max_split, 'max_split') return string.split(separator, max_split) def split_string_from_right(self, string, separator=None, max_split=-1): """Splits the `string` using `separator` starting from right. Same as `Split String`, but splitting is started from right. This has an effect only when `max_split` is given. Examples: | ${first} | ${rest} = | Split String | ${string} | - | 1 | | ${rest} | ${last} = | Split String From Right | ${string} | - | 1 | """ if separator == '': separator = None max_split = self._convert_to_integer(max_split, 'max_split') return string.rsplit(separator, max_split) def split_string_to_characters(self, string): """Splits the given `string` to characters. Example: | @{characters} = | Split String To Characters | ${string} | New in Robot Framework 2.7. """ return list(string) def fetch_from_left(self, string, marker): """Returns contents of the `string` before the first occurrence of `marker`. If the `marker` is not found, whole string is returned. See also `Fetch From Right`, `Split String` and `Split String From Right`. """ return string.split(marker)[0] def fetch_from_right(self, string, marker): """Returns contents of the `string` after the last occurrence of `marker`. If the `marker` is not found, whole string is returned. See also `Fetch From Left`, `Split String` and `Split String From Right`. """ return string.split(marker)[-1] def generate_random_string(self, length=8, chars='[LETTERS][NUMBERS]'): """Generates a string with a desired `length` from the given `chars`. The population sequence `chars` contains the characters to use when generating the random string. It can contain any characters, and it is possible to use special markers explained in the table below: | = Marker = | = Explanation = | | _[LOWER]_ | Lowercase ASCII characters from 'a' to 'z'. | | _[UPPER]_ | Uppercase ASCII characters from 'A' to 'Z'. | | _[LETTERS]_ | Lowercase and uppercase ASCII characters. | | _[NUMBERS]_ | Numbers from 0 to 9. | Examples: | ${ret} = | Generate Random String | | ${low} = | Generate Random String | 12 | [LOWER] | | ${bin} = | Generate Random String | 8 | 01 | | ${hex} = | Generate Random String | 4 | [NUMBERS]abcdef | """ if length == '': length = 8 length = self._convert_to_integer(length, 'length') for name, value in [('[LOWER]', ascii_lowercase), ('[UPPER]', ascii_uppercase), ('[LETTERS]', ascii_lowercase + ascii_uppercase), ('[NUMBERS]', digits)]: chars = chars.replace(name, value) maxi = len(chars) - 1 return ''.join(chars[randint(0, maxi)] for _ in range(length)) def get_substring(self, string, start, end=None): """Returns a substring from `start` index to `end` index. The `start` index is inclusive and `end` is exclusive. Indexing starts from 0, and it is possible to use negative indices to refer to characters from the end. Examples: | ${ignore first} = | Get Substring | ${string} | 1 | | | ${ignore last} = | Get Substring | ${string} | | -1 | | ${5th to 10th} = | Get Substring | ${string} | 4 | 10 | | ${first two} = | Get Substring | ${string} | | 1 | | ${last two} = | Get Substring | ${string} | -2 | | """ start = self._convert_to_index(start, 'start') end = self._convert_to_index(end, 'end') return string[start:end] def should_be_string(self, item, msg=None): """Fails if the given `item` is not a string. This keyword passes regardless is the `item` is a Unicode string or a byte string. Use `Should Be Unicode String` or `Should Be Byte String` if you want to restrict the string type. The default error message can be overridden with the optional `msg` argument. """ if not isinstance(item, string_types): self._fail(msg, "'%s' is not a string.", item) def should_not_be_string(self, item, msg=None): """Fails if the given `item` is a string. The default error message can be overridden with the optional `msg` argument. """ if isinstance(item, string_types): self._fail(msg, "'%s' is a string.", item) def should_be_unicode_string(self, item, msg=None): """Fails if the given `item` is not a Unicode string. Use `Should Be Byte String` if you want to verify the `item` is a byte string, or `Should Be String` if both Unicode and byte strings are fine. The default error message can be overridden with the optional `msg` argument. New in Robot Framework 2.7.7. """ if not isinstance(item, unicode): self._fail(msg, "'%s' is not a Unicode string.", item) def should_be_byte_string(self, item, msg=None): """Fails if the given `item` is not a byte string. Use `Should Be Unicode String` if you want to verify the `item` is a Unicode string, or `Should Be String` if both Unicode and byte strings are fine. The default error message can be overridden with the optional `msg` argument. New in Robot Framework 2.7.7. """ # Python 2.7 also has 'bytes' (alias for 'str') if not isinstance(item, bytes): self._fail(msg, "'%s' is not a byte string.", item) def should_be_lowercase(self, string, msg=None): """Fails if the given `string` is not in lowercase. For example 'string' and 'with specials!' would pass, and 'String', '' and ' ' would fail. The default error message can be overridden with the optional `msg` argument. See also `Should Be Uppercase` and `Should Be Titlecase`. All these keywords were added in Robot Framework 2.1.2. """ if not string.islower(): self._fail(msg, "'%s' is not lowercase.", string) def should_be_uppercase(self, string, msg=None): """Fails if the given `string` is not in uppercase. For example 'STRING' and 'WITH SPECIALS!' would pass, and 'String', '' and ' ' would fail. The default error message can be overridden with the optional `msg` argument. See also `Should Be Titlecase` and `Should Be Lowercase`. All these keywords were added in Robot Framework 2.1.2. """ if not string.isupper(): self._fail(msg, "'%s' is not uppercase.", string) def should_be_titlecase(self, string, msg=None): """Fails if given `string` is not title. `string` is a titlecased string if there is at least one character in it, uppercase characters only follow uncased characters and lowercase characters only cased ones. For example 'This Is Title' would pass, and 'Word In UPPER', 'Word In lower', '' and ' ' would fail. The default error message can be overridden with the optional `msg` argument. See also `Should Be Uppercase` and `Should Be Lowercase`. All theses keyword were added in Robot Framework 2.1.2. """ if not string.istitle(): self._fail(msg, "'%s' is not titlecase.", string) def _convert_to_index(self, value, name): if value == '': return 0 if value is None: return None return self._convert_to_integer(value, name) def _convert_to_integer(self, value, name): try: return int(value) except ValueError: raise ValueError( "Cannot convert '%s' argument '%s' to an integer." % (name, value)) def _fail(self, message, default_template, *items): if not message: message = default_template % tuple(unic(item) for item in items) raise AssertionError(message)
class Screenshot: """A test library for taking full-screen screenshots of the desktop. `Screenshot` is Robot Framework's standard library that provides keywords to capture and store screenshots of the whole desktop. This library is implemented with Java AWT APIs, so it can be used only when running Robot Framework on Jython. """ ROBOT_LIBRARY_SCOPE = 'TEST SUITE' ROBOT_LIBRARY_VERSION = get_version() def __init__(self, default_directory=None, log_file_directory=None): """Screenshot library can be imported with optional arguments. If the `default_directory` is provided, all the screenshots are saved into that directory by default. Otherwise the default location is the system temporary directory. `log_file_directory` is used to create relative paths when screenshots are logged. By default the paths to images in the log file are absolute. Examples (use only one of these): | *Setting* | *Value* | *Value* | *Value* | | Library | Screenshot | | | | Library | Screenshot | ${CURDIR}/images | | | Library | Screenshot | ${OUTPUTDIR} | ${OUTPUTDIR} | It is also possible to set these directories using `Set Screenshot Directories` keyword. """ self.set_screenshot_directories(default_directory, log_file_directory) def set_screenshot_directories(self, default_directory=None, log_file_directory=None): """Used to set `default_directory` and `log_file_directory`. See the `library importing` for details. """ if not default_directory: self._default_dir = tempfile.gettempdir() else: self._default_dir = os.path.normpath( default_directory.replace('/', os.sep)) if not log_file_directory: self._log_file_dir = None else: self._log_file_dir = os.path.normpath( log_file_directory.replace('/', os.sep)) def save_screenshot_to(self, path): """Saves a screenshot to the specified file. The directory holding the file must exist or an exception is raised. """ path = os.path.abspath(path.replace('/', os.sep)) if not os.path.exists(os.path.dirname(path)): raise RuntimeError( "Directory '%s' where to save the screenshot does " "not exist" % os.path.dirname(path)) screensize = Toolkit.getDefaultToolkit().getScreenSize() rectangle = Rectangle(0, 0, screensize.width, screensize.height) image = Robot().createScreenCapture(rectangle) ImageIO.write(image, "jpg", File(path)) print "Screenshot saved to '%s'" % path return path def save_screenshot(self, basename="screenshot", directory=None): """Saves a screenshot with a generated unique name. The unique name is derived based on the provided `basename` and `directory` passed in as optional arguments. If a `directory` is provided, the screenshot is saved under that directory. Otherwise, the `default_directory` set during the library import or by the keyword `Set Screenshot Directories` is used. If a `basename` for the screenshot file is provided, a unique filename is determined by appending an underscore and a running counter. Otherwise, the `basename` defaults to 'screenshot'. The path where the screenshot is saved is returned. Examples: | Save Screenshot | mypic | /home/user | # (1) | | Save Screenshot | mypic | | # (2) | | Save Screenshot | | | # (3) | => 1. /home/user/mypic_1.jpg, /home/user/mypic_2.jpg, ... 2. /tmp/mypic_1.jpg, /tmp/mypic_2.jpg, ... 3. /tmp/screenshot_1.jpg, /tmp/screenshot_2.jpg, ... """ if directory is None: directory = self._default_dir else: directory = directory.replace('/', os.sep) index = 0 while True: index += 1 path = os.path.join(directory, "%s_%d.jpg" % (basename, index)) if not os.path.exists(path): break return self.save_screenshot_to(path) def log_screenshot(self, basename="screenshot", directory=None, log_file_directory=None, width="100%"): """Takes a screenshot and logs it to Robot Framework's log file. Saves the files as defined in the keyword `Save Screenshot` and creates a picture to Robot Framework's log. `directory` defines the directory where the screenshots are saved. By default, its value is `default_directory`, which is set at the library import or with the keyword `Set Screenshot Directories`. `log_file_directory` is used to create relative paths to the pictures. This allows moving the log and pictures to different machines and having still working pictures. If `log_file_directory` is not given or set (in the same way as `default_directory` is set), the paths are absolute. The path where the screenshot is saved is returned. """ path = self.save_screenshot(basename, directory) if log_file_directory is None: log_file_directory = self._log_file_dir if log_file_directory is not None: link = utils.get_link_path(path, log_file_directory) else: link = 'file:///' + path.replace('\\', '/') print '*HTML* <a href="%s"><img src="%s" width="%s" /></a>' \ % (link, link, width) return path
from datetime import datetime from robot import run import os from robot.libraries.BuiltIn import BuiltIn from . import models as m from multiprocessing import Pool import multiprocessing from operator import itemgetter from .constants import AppConfig from .util import RobotLogger from robot.version import get_version AppConfig.ROBOT_VERSION = get_version() if AppConfig.ROBOT_VERSION < '3.2.2': from robot.api import TestData, ResourceFile, TestCaseFile else: from robot.api import TestSuiteBuilder, get_model, get_resource_model def run_task(task): # print('worker_started:', multiprocessing.current_process().name, multiprocessing.current_process().pid) logger = RobotLogger(__name__).logger logger.debug("In Run task") logger.debug('BatchID:%s', task.get('Batch_ID')) logger.debug('RUN_ID:%s', task.get('RUN_ID')) logger.debug('Test Name:%s', task.get('ScriptName')) logger.debug('Test Source:%s', task.get('Source')) variable_list = [] logger.debug('Test Type:%s', task.get('TestType')) logger.debug('Starting Test Name:%s', task.get('ScriptName'))
class Process(object): """Robot Framework test library for running processes. This library utilizes Python's [http://docs.python.org/2/library/subprocess.html|subprocess] module and its [http://docs.python.org/2/library/subprocess.html#subprocess.Popen|Popen] class. The library has following main usages: - Running processes in system and waiting for their completion using `Run Process` keyword. - Starting processes on background using `Start Process`. - Waiting started process to complete using `Wait For Process` or stopping them with `Terminate Process` or `Terminate All Processes`. This library is new in Robot Framework 2.8. == Table of contents == - `Specifying command and arguments` - `Process configuration` - `Active process` - `Result object` - `Boolean arguments` - `Example` - `Shortcuts` - `Keywords` = Specifying command and arguments = Both `Run Process` and `Start Process` accept the command to execute and all arguments passed to the command as separate arguments. This makes usage convenient and also allows these keywords to automatically escape possible spaces and other special characters in commands and arguments. Notice that if a command accepts options that themselves accept values, these options and their values must be given as separate arguments. When `running processes in shell`, it is also possible to give the whole command to execute as a single string. The command can then contain multiple commands to be run together. When using this approach, the caller is responsible on escaping. Examples: | `Run Process` | ${tools}${/}prog.py | argument | second arg with spaces | | `Run Process` | java | -jar | ${jars}${/}example.jar | --option | value | | `Run Process` | prog.py "one arg" && tool.sh | shell=yes | cwd=${tools} | Starting from Robot Framework 2.8.6, possible non-string arguments are converted to strings automatically. = Process configuration = `Run Process` and `Start Process` keywords can be configured using optional ``**configuration`` keyword arguments. Configuration arguments must be given after other arguments passed to these keywords and must use syntax like ``name=value``. Available configuration arguments are listed below and discussed further in sections afterwards. | = Name = | = Explanation = | | shell | Specifies whether to run the command in shell or not. | | cwd | Specifies the working directory. | | env | Specifies environment variables given to the process. | | env:<name> | Overrides the named environment variable(s) only. | | stdout | Path of a file where to write standard output. | | stderr | Path of a file where to write standard error. | | output_encoding | Encoding to use when reading command outputs. | | alias | Alias given to the process. | Note that because ``**configuration`` is passed using ``name=value`` syntax, possible equal signs in other arguments passed to `Run Process` and `Start Process` must be escaped with a backslash like ``name\\=value``. See `Run Process` for an example. == Running processes in shell == The ``shell`` argument specifies whether to run the process in a shell or not. By default shell is not used, which means that shell specific commands, like ``copy`` and ``dir`` on Windows, are not available. You can, however, run shell scripts and batch files without using a shell. Giving the ``shell`` argument any non-false value, such as ``shell=True``, changes the program to be executed in a shell. It allows using the shell capabilities, but can also make the process invocation operating system dependent. Having a shell between the actually started process and this library can also interfere communication with the process such as stopping it and reading its outputs. Because of these problems, it is recommended to use the shell only when absolutely necessary. When using a shell it is possible to give the whole command to execute as a single string. See `Specifying command and arguments` section for examples and more details in general. == Current working directory == By default the child process will be executed in the same directory as the parent process, the process running tests, is executed. This can be changed by giving an alternative location using the ``cwd`` argument. Forward slashes in the given path are automatically converted to backslashes on Windows. `Standard output and error streams`, when redirected to files, are also relative to the current working directory possibly set using the ``cwd`` argument. Example: | `Run Process` | prog.exe | cwd=${ROOT}/directory | stdout=stdout.txt | == Environment variables == By default the child process will get a copy of the parent process's environment variables. The ``env`` argument can be used to give the child a custom environment as a Python dictionary. If there is a need to specify only certain environment variable, it is possible to use the ``env:<name>=<value>`` format to set or override only that named variables. It is also possible to use these two approaches together. Examples: | `Run Process` | program | env=${environ} | | `Run Process` | program | env:http_proxy=10.144.1.10:8080 | env:PATH=%{PATH}${:}${PROGDIR} | | `Run Process` | program | env=${environ} | env:EXTRA=value | == Standard output and error streams == By default processes are run so that their standard output and standard error streams are kept in the memory. This works fine normally, but if there is a lot of output, the output buffers may get full and the program can hang. Additionally on Jython, everything written to these in-memory buffers can be lost if the process is terminated. To avoid the above mentioned problems, it is possible to use ``stdout`` and ``stderr`` arguments to specify files on the file system where to redirect the outputs. This can also be useful if other processes or other keywords need to read or manipulate the outputs somehow. Given ``stdout`` and ``stderr`` paths are relative to the `current working directory`. Forward slashes in the given paths are automatically converted to backslashes on Windows. As a special feature, it is possible to redirect the standard error to the standard output by using ``stderr=STDOUT``. Regardless are outputs redirected to files or not, they are accessible through the `result object` returned when the process ends. Commands are expected to write outputs using the console encoding, but `output encoding` can be configured using the ``output_encoding`` argument if needed. Examples: | ${result} = | `Run Process` | program | stdout=${TEMPDIR}/stdout.txt | stderr=${TEMPDIR}/stderr.txt | | `Log Many` | stdout: ${result.stdout} | stderr: ${result.stderr} | | ${result} = | `Run Process` | program | stderr=STDOUT | | `Log` | all output: ${result.stdout} | Note that the created output files are not automatically removed after the test run. The user is responsible to remove them if needed. == Output encoding == Executed commands are, by default, expected to write outputs to the `standard output and error streams` using the encoding used by the system console. If the command uses some other encoding, that can be configured using the ``output_encoding`` argument. This is especially useful on Windows where the console uses a different encoding than rest of the system, and many commands use the general system encoding instead of the console encoding. The value used with the ``output_encoding`` argument must be a valid encoding and must match the encoding actually used by the command. As a convenience, it is possible to use strings ``CONSOLE`` and ``SYSTEM`` to specify that the console or system encoding is used, respectively. If produced outputs use different encoding then configured, values got through the `result object` will be invalid. Examples: | `Start Process` | program | output_encoding=UTF-8 | | `Run Process` | program | stdout=${path} | output_encoding=SYSTEM | The support to set output encoding is new in Robot Framework 3.0. == Alias == A custom name given to the process that can be used when selecting the `active process`. Examples: | `Start Process` | program | alias=example | | `Run Process` | python | -c | print 'hello' | alias=hello | = Active process = The test library keeps record which of the started processes is currently active. By default it is latest process started with `Start Process`, but `Switch Process` can be used to select a different one. Using `Run Process` does not affect the active process. The keywords that operate on started processes will use the active process by default, but it is possible to explicitly select a different process using the ``handle`` argument. The handle can be the identifier returned by `Start Process` or an ``alias`` explicitly given to `Start Process` or `Run Process`. = Result object = `Run Process`, `Wait For Process` and `Terminate Process` keywords return a result object that contains information about the process execution as its attributes. The same result object, or some of its attributes, can also be get using `Get Process Result` keyword. Attributes available in the object are documented in the table below. | = Attribute = | = Explanation = | | rc | Return code of the process as an integer. | | stdout | Contents of the standard output stream. | | stderr | Contents of the standard error stream. | | stdout_path | Path where stdout was redirected or ``None`` if not redirected. | | stderr_path | Path where stderr was redirected or ``None`` if not redirected. | Example: | ${result} = | `Run Process` | program | | `Should Be Equal As Integers` | ${result.rc} | 0 | | `Should Match` | ${result.stdout} | Some t?xt* | | `Should Be Empty` | ${result.stderr} | | | ${stdout} = | `Get File` | ${result.stdout_path} | | `Should Be Equal` | ${stdout} | ${result.stdout} | | `File Should Be Empty` | ${result.stderr_path} | | = Boolean arguments = Some keywords accept arguments that are handled as Boolean values true or false. If such an argument is given as a string, it is considered false if it is either empty or case-insensitively equal to ``false`` or ``no``. Other strings are considered true regardless their value, and other argument types are tested using same [http://docs.python.org/2/library/stdtypes.html#truth-value-testing|rules as in Python]. True examples: | `Terminate Process` | kill=True | # Strings are generally true. | | `Terminate Process` | kill=yes | # Same as the above. | | `Terminate Process` | kill=${TRUE} | # Python ``True`` is true. | | `Terminate Process` | kill=${42} | # Numbers other than 0 are true. | False examples: | `Terminate Process` | kill=False | # String ``false`` is false. | | `Terminate Process` | kill=no | # Also string ``no`` is false. | | `Terminate Process` | kill=${EMPTY} | # Empty string is false. | | `Terminate Process` | kill=${FALSE} | # Python ``False`` is false. | Note that prior to Robot Framework 2.8 all non-empty strings, including ``false``, were considered true. Additionally, ``no`` is considered false only in Robot Framework 2.9 and newer. = Example = | ***** Settings ***** | Library Process | Suite Teardown `Terminate All Processes` kill=True | | ***** Test Cases ***** | Example | `Start Process` program arg1 arg2 alias=First | ${handle} = `Start Process` command.sh arg | command2.sh shell=True cwd=/path | ${result} = `Run Process` ${CURDIR}/script.py | `Should Not Contain` ${result.stdout} FAIL | `Terminate Process` ${handle} | ${result} = `Wait For Process` First | `Should Be Equal As Integers` ${result.rc} 0 """ ROBOT_LIBRARY_SCOPE = 'GLOBAL' ROBOT_LIBRARY_VERSION = get_version() TERMINATE_TIMEOUT = 30 KILL_TIMEOUT = 10 def __init__(self): self._processes = ConnectionCache('No active process.') self._results = {} def run_process(self, command, *arguments, **configuration): """Runs a process and waits for it to complete. ``command`` and ``*arguments`` specify the command to execute and arguments passed to it. See `Specifying command and arguments` for more details. ``**configuration`` contains additional configuration related to starting processes and waiting for them to finish. See `Process configuration` for more details about configuration related to starting processes. Configuration related to waiting for processes consists of ``timeout`` and ``on_timeout`` arguments that have same semantics as with `Wait For Process` keyword. By default there is no timeout, and if timeout is defined the default action on timeout is ``terminate``. Returns a `result object` containing information about the execution. Note that possible equal signs in ``*arguments`` must be escaped with a backslash (e.g. ``name\\=value``) to avoid them to be passed in as ``**configuration``. Examples: | ${result} = | Run Process | python | -c | print 'Hello, world!' | | Should Be Equal | ${result.stdout} | Hello, world! | | ${result} = | Run Process | ${command} | stderr=STDOUT | timeout=10s | | ${result} = | Run Process | ${command} | timeout=1min | on_timeout=continue | | ${result} = | Run Process | java -Dname\\=value Example | shell=True | cwd=${EXAMPLE} | This keyword does not change the `active process`. ``timeout`` and ``on_timeout`` arguments are new in Robot Framework 2.8.4. """ current = self._processes.current timeout = configuration.pop('timeout', None) on_timeout = configuration.pop('on_timeout', 'terminate') try: handle = self.start_process(command, *arguments, **configuration) return self.wait_for_process(handle, timeout, on_timeout) finally: self._processes.current = current def start_process(self, command, *arguments, **configuration): """Starts a new process on background. See `Specifying command and arguments` and `Process configuration` for more information about the arguments, and `Run Process` keyword for related examples. Makes the started process new `active process`. Returns an identifier that can be used as a handle to activate the started process if needed. Starting from Robot Framework 2.8.5, processes are started so that they create a new process group. This allows sending signals to and terminating also possible child processes. This is not supported by Jython in general nor by Python versions prior to 2.7 on Windows. """ conf = ProcessConfiguration(**configuration) command = conf.get_command(command, list(arguments)) self._log_start(command, conf) process = subprocess.Popen(command, **conf.popen_config) self._results[process] = ExecutionResult(process, **conf.result_config) return self._processes.register(process, alias=conf.alias) def _log_start(self, command, config): if is_list_like(command): command = self.join_command_line(command) logger.info(u'Starting process:\n%s' % system_decode(command)) logger.debug(u'Process configuration:\n%s' % config) def is_process_running(self, handle=None): """Checks is the process running or not. If ``handle`` is not given, uses the current `active process`. Returns ``True`` if the process is still running and ``False`` otherwise. """ return self._processes[handle].poll() is None def process_should_be_running(self, handle=None, error_message='Process is not running.'): """Verifies that the process is running. If ``handle`` is not given, uses the current `active process`. Fails if the process has stopped. """ if not self.is_process_running(handle): raise AssertionError(error_message) def process_should_be_stopped(self, handle=None, error_message='Process is running.'): """Verifies that the process is not running. If ``handle`` is not given, uses the current `active process`. Fails if the process is still running. """ if self.is_process_running(handle): raise AssertionError(error_message) def wait_for_process(self, handle=None, timeout=None, on_timeout='continue'): """Waits for the process to complete or to reach the given timeout. The process to wait for must have been started earlier with `Start Process`. If ``handle`` is not given, uses the current `active process`. ``timeout`` defines the maximum time to wait for the process. It can be given in [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format| various time formats] supported by Robot Framework, for example, ``42``, ``42 s``, or ``1 minute 30 seconds``. ``on_timeout`` defines what to do if the timeout occurs. Possible values and corresponding actions are explained in the table below. Notice that reaching the timeout never fails the test. | = Value = | = Action = | | continue | The process is left running (default). | | terminate | The process is gracefully terminated. | | kill | The process is forcefully stopped. | See `Terminate Process` keyword for more details how processes are terminated and killed. If the process ends before the timeout or it is terminated or killed, this keyword returns a `result object` containing information about the execution. If the process is left running, Python ``None`` is returned instead. Examples: | # Process ends cleanly | | | | ${result} = | Wait For Process | example | | Process Should Be Stopped | example | | | Should Be Equal As Integers | ${result.rc} | 0 | | # Process does not end | | | | ${result} = | Wait For Process | timeout=42 secs | | Process Should Be Running | | | | Should Be Equal | ${result} | ${NONE} | | # Kill non-ending process | | | | ${result} = | Wait For Process | timeout=1min 30s | on_timeout=kill | | Process Should Be Stopped | | | | Should Be Equal As Integers | ${result.rc} | -9 | ``timeout`` and ``on_timeout`` are new in Robot Framework 2.8.2. """ process = self._processes[handle] logger.info('Waiting for process to complete.') if timeout: timeout = timestr_to_secs(timeout) if not self._process_is_stopped(process, timeout): logger.info('Process did not complete in %s.' % secs_to_timestr(timeout)) return self._manage_process_timeout(handle, on_timeout.lower()) return self._wait(process) def _manage_process_timeout(self, handle, on_timeout): if on_timeout == 'terminate': return self.terminate_process(handle) elif on_timeout == 'kill': return self.terminate_process(handle, kill=True) else: logger.info('Leaving process intact.') return None def _wait(self, process): result = self._results[process] result.rc = process.wait() or 0 result.close_streams() logger.info('Process completed.') return result def terminate_process(self, handle=None, kill=False): """Stops the process gracefully or forcefully. If ``handle`` is not given, uses the current `active process`. By default first tries to stop the process gracefully. If the process does not stop in 30 seconds, or ``kill`` argument is given a true value, (see `Boolean arguments`) kills the process forcefully. Stops also all the child processes of the originally started process. Waits for the process to stop after terminating it. Returns a `result object` containing information about the execution similarly as `Wait For Process`. On Unix-like machines graceful termination is done using ``TERM (15)`` signal and killing using ``KILL (9)``. Use `Send Signal To Process` instead if you just want to send either of these signals without waiting for the process to stop. On Windows graceful termination is done using ``CTRL_BREAK_EVENT`` event and killing using Win32 API function ``TerminateProcess()``. Examples: | ${result} = | Terminate Process | | | Should Be Equal As Integers | ${result.rc} | -15 | # On Unixes | | Terminate Process | myproc | kill=true | Limitations: - Graceful termination is not supported on Windows by Jython nor by Python versions prior to 2.7. Process is killed instead. - Stopping the whole process group is not supported by Jython at all nor by Python versions prior to 2.7 on Windows. - On Windows forceful kill only stops the main process, not possible child processes. Automatically killing the process if termination fails as well as returning a result object are new features in Robot Framework 2.8.2. Terminating also possible child processes, including using ``CTRL_BREAK_EVENT`` on Windows, is new in Robot Framework 2.8.5. """ process = self._processes[handle] if not hasattr(process, 'terminate'): raise RuntimeError('Terminating processes is not supported ' 'by this Python version.') terminator = self._kill if is_truthy(kill) else self._terminate try: terminator(process) except OSError: if not self._process_is_stopped(process, self.KILL_TIMEOUT): raise logger.debug('Ignored OSError because process was stopped.') return self._wait(process) def _kill(self, process): logger.info('Forcefully killing process.') if hasattr(os, 'killpg'): os.killpg(process.pid, signal_module.SIGKILL) else: process.kill() if not self._process_is_stopped(process, self.KILL_TIMEOUT): raise RuntimeError('Failed to kill process.') def _terminate(self, process): logger.info('Gracefully terminating process.') # Sends signal to the whole process group both on POSIX and on Windows # if supported by the interpreter. if hasattr(os, 'killpg'): os.killpg(process.pid, signal_module.SIGTERM) elif hasattr(signal_module, 'CTRL_BREAK_EVENT'): if IRONPYTHON: # https://ironpython.codeplex.com/workitem/35020 ctypes.windll.kernel32.GenerateConsoleCtrlEvent( signal_module.CTRL_BREAK_EVENT, process.pid) else: process.send_signal(signal_module.CTRL_BREAK_EVENT) else: process.terminate() if not self._process_is_stopped(process, self.TERMINATE_TIMEOUT): logger.info('Graceful termination failed.') self._kill(process) def terminate_all_processes(self, kill=False): """Terminates all still running processes started by this library. This keyword can be used in suite teardown or elsewhere to make sure that all processes are stopped, By default tries to terminate processes gracefully, but can be configured to forcefully kill them immediately. See `Terminate Process` that this keyword uses internally for more details. """ for handle in range(1, len(self._processes) + 1): if self.is_process_running(handle): self.terminate_process(handle, kill=kill) self.__init__() def send_signal_to_process(self, signal, handle=None, group=False): """Sends the given ``signal`` to the specified process. If ``handle`` is not given, uses the current `active process`. Signal can be specified either as an integer as a signal name. In the latter case it is possible to give the name both with or without ``SIG`` prefix, but names are case-sensitive. For example, all the examples below send signal ``INT (2)``: | Send Signal To Process | 2 | | # Send to active process | | Send Signal To Process | INT | | | | Send Signal To Process | SIGINT | myproc | # Send to named process | This keyword is only supported on Unix-like machines, not on Windows. What signals are supported depends on the system. For a list of existing signals on your system, see the Unix man pages related to signal handling (typically ``man signal`` or ``man 7 signal``). By default sends the signal only to the parent process, not to possible child processes started by it. Notice that when `running processes in shell`, the shell is the parent process and it depends on the system does the shell propagate the signal to the actual started process. To send the signal to the whole process group, ``group`` argument can be set to any true value (see `Boolean arguments`). This is not supported by Jython, however. New in Robot Framework 2.8.2. Support for ``group`` argument is new in Robot Framework 2.8.5. """ if os.sep == '\\': raise RuntimeError('This keyword does not work on Windows.') process = self._processes[handle] signum = self._get_signal_number(signal) logger.info('Sending signal %s (%d).' % (signal, signum)) if is_truthy(group) and hasattr(os, 'killpg'): os.killpg(process.pid, signum) elif hasattr(process, 'send_signal'): process.send_signal(signum) else: raise RuntimeError('Sending signals is not supported ' 'by this Python version.') def _get_signal_number(self, int_or_name): try: return int(int_or_name) except ValueError: return self._convert_signal_name_to_number(int_or_name) def _convert_signal_name_to_number(self, name): try: return getattr(signal_module, name if name.startswith('SIG') else 'SIG' + name) except AttributeError: raise RuntimeError("Unsupported signal '%s'." % name) def get_process_id(self, handle=None): """Returns the process ID (pid) of the process as an integer. If ``handle`` is not given, uses the current `active process`. Notice that the pid is not the same as the handle returned by `Start Process` that is used internally by this library. """ return self._processes[handle].pid def get_process_object(self, handle=None): """Return the underlying ``subprocess.Popen`` object. If ``handle`` is not given, uses the current `active process`. """ return self._processes[handle] def get_process_result(self, handle=None, rc=False, stdout=False, stderr=False, stdout_path=False, stderr_path=False): """Returns the specified `result object` or some of its attributes. The given ``handle`` specifies the process whose results should be returned. If no ``handle`` is given, results of the current `active process` are returned. In either case, the process must have been finishes before this keyword can be used. In practice this means that processes started with `Start Process` must be finished either with `Wait For Process` or `Terminate Process` before using this keyword. If no other arguments than the optional ``handle`` are given, a whole `result object` is returned. If one or more of the other arguments are given any true value, only the specified attributes of the `result object` are returned. These attributes are always returned in the same order as arguments are specified in the keyword signature. See `Boolean arguments` section for more details about true and false values. Examples: | Run Process | python | -c | print 'Hello, world!' | alias=myproc | | # Get result object | | | | ${result} = | Get Process Result | myproc | | Should Be Equal | ${result.rc} | ${0} | | Should Be Equal | ${result.stdout} | Hello, world! | | Should Be Empty | ${result.stderr} | | | # Get one attribute | | | | ${stdout} = | Get Process Result | myproc | stdout=true | | Should Be Equal | ${stdout} | Hello, world! | | # Multiple attributes | | | | ${stdout} | ${stderr} = | Get Process Result | myproc | stdout=yes | stderr=yes | | Should Be Equal | ${stdout} | Hello, world! | | Should Be Empty | ${stderr} | | Although getting results of a previously executed process can be handy in general, the main use case for this keyword is returning results over the remote library interface. The remote interface does not support returning the whole result object, but individual attributes can be returned without problems. New in Robot Framework 2.8.2. """ result = self._results[self._processes[handle]] if result.rc is None: raise RuntimeError('Getting results of unfinished processes ' 'is not supported.') attributes = self._get_result_attributes(result, rc, stdout, stderr, stdout_path, stderr_path) if not attributes: return result elif len(attributes) == 1: return attributes[0] return attributes def _get_result_attributes(self, result, *includes): attributes = (result.rc, result.stdout, result.stderr, result.stdout_path, result.stderr_path) includes = (is_truthy(incl) for incl in includes) return tuple(attr for attr, incl in zip(attributes, includes) if incl) def switch_process(self, handle): """Makes the specified process the current `active process`. The handle can be an identifier returned by `Start Process` or the ``alias`` given to it explicitly. Example: | Start Process | prog1 | alias=process1 | | Start Process | prog2 | alias=process2 | | # currently active process is process2 | | Switch Process | process1 | | # now active process is process1 | """ self._processes.switch(handle) def _process_is_stopped(self, process, timeout): stopped = lambda: process.poll() is not None max_time = time.time() + timeout while time.time() <= max_time and not stopped(): time.sleep(min(0.1, timeout)) return stopped() def split_command_line(self, args, escaping=False): """Splits command line string into a list of arguments. String is split from spaces, but argument surrounded in quotes may contain spaces in them. If ``escaping`` is given a true value, then backslash is treated as an escape character. It can escape unquoted spaces, quotes inside quotes, and so on, but it also requires using double backslashes when using Windows paths. Examples: | @{cmd} = | Split Command Line | --option "value with spaces" | | Should Be True | $cmd == ['--option', 'value with spaces'] | New in Robot Framework 2.9.2. """ return cmdline2list(args, escaping=escaping) def join_command_line(self, *args): """Joins arguments into one command line string. In resulting command line string arguments are delimited with a space, arguments containing spaces are surrounded with quotes, and possible quotes are escaped with a backslash. If this keyword is given only one argument and that is a list like object, then the values of that list are joined instead. Example: | ${cmd} = | Join Command Line | --option | value with spaces | | Should Be Equal | ${cmd} | --option "value with spaces" | New in Robot Framework 2.9.2. """ if len(args) == 1 and is_list_like(args[0]): args = args[0] return subprocess.list2cmdline(args)
# limitations under the License. import sys try: from robot.common import UserErrorHandler from robot.common.model import BaseTestSuite from robot.running import TestSuite from robot.running.model import RunnableTestSuite, RunnableTestCase from robot.conf import RobotSettings from robot.running.namespace import Namespace from robot.utils import (ArgumentParser, get_timestamp, normalize, elapsed_time_to_string, eq, normalize_tags, unescape, get_elapsed_time) from robot import version ROBOT_VERSION = version.get_version() from robot.errors import DataError, Information from robot.output.logger import LOGGER LOGGER.disable_automatic_console_logger() except ImportError, error: print """All needed Robot modules could not be imported. Check your Robot installation.""" print "Error was: %s" % (error) raise error def XmlTestSuite(suite): if ROBOT_VERSION < '2.7': from robot.output import TestSuite return TestSuite(suite) from robot.result import ExecutionResult
class Collections(_List, _Dictionary): """A test library providing keywords for handling lists and dictionaries. ``Collections`` is Robot Framework's standard library that provides a set of keywords for handling Python lists and dictionaries. This library has keywords, for example, for modifying and getting values from lists and dictionaries (e.g. `Append To List`, `Get From Dictionary`) and for verifying their contents (e.g. `Lists Should Be Equal`, `Dictionary Should Contain Value`). = Related keywords in BuiltIn = Following keywords in the BuiltIn library can also be used with lists and dictionaries: | = Keyword Name = | = Applicable With = | = Comment = | | `Create List` | lists | | `Create Dictionary` | dicts | Was in Collections until RF 2.9. | | `Get Length` | both | | `Length Should Be` | both | | `Should Be Empty` | both | | `Should Not Be Empty` | both | | `Should Contain` | both | | `Should Not Contain` | both | | `Should Contain X Times` | lists | | `Should Not Contain X Times` | lists | | `Get Count` | lists | = Using with list-like and dictionary-like objects = List keywords that do not alter the given list can also be used with tuples, and to some extend also with other iterables. `Convert To List` can be used to convert tuples and other iterables to Python ``list`` objects. Similarly dictionary keywords can, for most parts, be used with other mappings. `Convert To Dictionary` can be used if real Python ``dict`` objects are needed. = Boolean arguments = Some keywords accept arguments that are handled as Boolean values true or false. If such an argument is given as a string, it is considered false if it is either an empty string or case-insensitively equal to ``false``, ``none`` or ``no``. Keywords verifying something that allow dropping actual and expected values from the possible error message also consider string ``no values`` to be false. Other strings are considered true regardless their value, and other argument types are tested using the same [http://docs.python.org/3/library/stdtypes.html#truth|rules as in Python]. True examples: | `Should Contain Match` | ${list} | ${pattern} | case_insensitive=True | # Strings are generally true. | | `Should Contain Match` | ${list} | ${pattern} | case_insensitive=yes | # Same as the above. | | `Should Contain Match` | ${list} | ${pattern} | case_insensitive=${TRUE} | # Python ``True`` is true. | | `Should Contain Match` | ${list} | ${pattern} | case_insensitive=${42} | # Numbers other than 0 are true. | False examples: | `Should Contain Match` | ${list} | ${pattern} | case_insensitive=False | # String ``false`` is false. | | `Should Contain Match` | ${list} | ${pattern} | case_insensitive=no | # Also string ``no`` is false. | | `Should Contain Match` | ${list} | ${pattern} | case_insensitive=${EMPTY} | # Empty string is false. | | `Should Contain Match` | ${list} | ${pattern} | case_insensitive=${FALSE} | # Python ``False`` is false. | | `Lists Should Be Equal` | ${x} | ${y} | Custom error | values=no values | # ``no values`` works with ``values`` argument | Note that prior to Robot Framework 2.9 some keywords considered all non-empty strings, including ``False``, to be true. Considering ``none`` false is new in Robot Framework 3.0.3. = Data in examples = List related keywords use variables in format ``${Lx}`` in their examples. They mean lists with as many alphabetic characters as specified by ``x``. For example, ``${L1}`` means ``['a']`` and ``${L3}`` means ``['a', 'b', 'c']``. Dictionary keywords use similar ``${Dx}`` variables. For example, ``${D1}`` means ``{'a': 1}`` and ``${D3}`` means ``{'a': 1, 'b': 2, 'c': 3}``. """ ROBOT_LIBRARY_SCOPE = 'GLOBAL' ROBOT_LIBRARY_VERSION = get_version() def should_contain_match(self, list, pattern, msg=None, case_insensitive=False, whitespace_insensitive=False): """Fails if ``pattern`` is not found in ``list``. See `List Should Contain Value` for an explanation of ``msg``. By default, pattern matching is similar to matching files in a shell and is case-sensitive and whitespace-sensitive. In the pattern syntax, ``*`` matches to anything and ``?`` matches to any single character. You can also prepend ``glob=`` to your pattern to explicitly use this pattern matching behavior. If you prepend ``regexp=`` to your pattern, your pattern will be used according to the Python [http://docs.python.org/3/library/re.html|re module] regular expression syntax. Important note: Backslashes are an escape character, and must be escaped with another backslash (e.g. ``regexp=\\\\d{6}`` to search for ``\\d{6}``). See `BuiltIn.Should Match Regexp` for more details. If ``case_insensitive`` is given a true value (see `Boolean arguments`), the pattern matching will ignore case. If ``whitespace_insensitive`` is given a true value (see `Boolean arguments`), the pattern matching will ignore whitespace. Non-string values in lists are ignored when matching patterns. The given list is never altered by this keyword. See also ``Should Not Contain Match``. Examples: | Should Contain Match | ${list} | a* | | | # Match strings beginning with 'a'. | | Should Contain Match | ${list} | regexp=a.* | | | # Same as the above but with regexp. | | Should Contain Match | ${list} | regexp=\\\\d{6} | | | # Match strings containing six digits. | | Should Contain Match | ${list} | a* | case_insensitive=True | | # Match strings beginning with 'a' or 'A'. | | Should Contain Match | ${list} | ab* | whitespace_insensitive=yes | | # Match strings beginning with 'ab' with possible whitespace ignored. | | Should Contain Match | ${list} | ab* | whitespace_insensitive=true | case_insensitive=true | # Same as the above but also ignore case. | New in Robot Framework 2.8.6. """ matches = _get_matches_in_iterable(list, pattern, case_insensitive, whitespace_insensitive) default = "%s does not contain match for pattern '%s'." \ % (seq2str2(list), pattern) _verify_condition(matches, default, msg) def should_not_contain_match(self, list, pattern, msg=None, case_insensitive=False, whitespace_insensitive=False): """Fails if ``pattern`` is found in ``list``. Exact opposite of `Should Contain Match` keyword. See that keyword for information about arguments and usage in general. New in Robot Framework 2.8.6. """ matches = _get_matches_in_iterable(list, pattern, case_insensitive, whitespace_insensitive) default = "%s contains match for pattern '%s'." \ % (seq2str2(list), pattern) _verify_condition(not matches, default, msg) def get_matches(self, list, pattern, case_insensitive=False, whitespace_insensitive=False): """Returns a list of matches to ``pattern`` in ``list``. For more information on ``pattern``, ``case_insensitive``, and ``whitespace_insensitive``, see `Should Contain Match`. Examples: | ${matches}= | Get Matches | ${list} | a* | # ${matches} will contain any string beginning with 'a' | | ${matches}= | Get Matches | ${list} | regexp=a.* | # ${matches} will contain any string beginning with 'a' (regexp version) | | ${matches}= | Get Matches | ${list} | a* | case_insensitive=${True} | # ${matches} will contain any string beginning with 'a' or 'A' | New in Robot Framework 2.8.6. """ return _get_matches_in_iterable(list, pattern, case_insensitive, whitespace_insensitive) def get_match_count(self, list, pattern, case_insensitive=False, whitespace_insensitive=False): """Returns the count of matches to ``pattern`` in ``list``. For more information on ``pattern``, ``case_insensitive``, and ``whitespace_insensitive``, see `Should Contain Match`. Examples: | ${count}= | Get Match Count | ${list} | a* | # ${count} will be the count of strings beginning with 'a' | | ${count}= | Get Match Count | ${list} | regexp=a.* | # ${matches} will be the count of strings beginning with 'a' (regexp version) | | ${count}= | Get Match Count | ${list} | a* | case_insensitive=${True} | # ${matches} will be the count of strings beginning with 'a' or 'A' | New in Robot Framework 2.8.6. """ return len( self.get_matches(list, pattern, case_insensitive, whitespace_insensitive))
class Process(object): """Robot Framework test library for running processes. This library utilizes Python's [http://docs.python.org/2.7/library/subprocess.html|subprocess] module and its [http://docs.python.org/2.7/library/subprocess.html#subprocess.Popen|Popen] class. The library has following main usages: - Running processes in system and waiting for their completion using `Run Process` keyword. - Starting processes on background using `Start Process`. - Waiting started process to complete using `Wait For Process` or stopping them with `Terminate Process` or `Terminate All Processes`. This library is new in Robot Framework 2.8. == Table of contents == - `Specifying command and arguments` - `Process configuration` - `Active process` - `Stopping processes` - `Result object` - `Using with OperatingSystem library` - `Example` = Specifying command and arguments = Both `Run Process` and `Start Process` accept the command to execute and all arguments passed to it as separate arguments. This is convenient to use and also allows these keywords to automatically escape possible spaces and other special characters in the command or arguments. When `running processes in shell`, it is also possible to give the whole command to execute as a single string. The command can then contain multiple commands, for example, connected with pipes. When using this approach the caller is responsible on escaping. Examples: | `Run Process` | ${progdir}${/}prog.py | first arg | second | | `Run Process` | script1.sh arg && script2.sh | shell=yes | cwd=${progdir} | = Process configuration = `Run Process` and `Start Process` keywords can be configured using optional `**configuration` keyword arguments. Available configuration arguments are listed below and discussed further in sections afterwards. | *Name* | *Explanation* | | shell | Specifies whether to run the command in shell or not | | cwd | Specifies the working directory. | | env | Specifies environment variables given to the process. | | env:<name> | Overrides the named environment variable(s) only. | | stdout | Path of a file where to write standard output. | | stderr | Path of a file where to write standard error. | | alias | Alias given to the process. | Configuration must be given after other arguments passed to these keywords and must use syntax `name=value`. == Running processes in shell == The `shell` argument specifies whether to run the process in a shell or not. By default shell is not used, which means that shell specific commands, like `copy` and `dir` on Windows, are not available. Giving the `shell` argument any non-false value, such as `shell=True`, changes the program to be executed in a shell. It allows using the shell capabilities, but can also make the process invocation operating system dependent. When using a shell it is possible to give the whole command to execute as a single string. See `Specifying command and arguments` section for more details. == Current working directory == By default the child process will be executed in the same directory as the parent process, the process running tests, is executed. This can be changed by giving an alternative location using the `cwd` argument. Forward slashes in the given path are automatically converted to backslashes on Windows. `Standard output and error streams`, when redirected to files, are also relative to the current working directory possibly set using the `cwd` argument. Example: | `Run Process` | prog.exe | cwd=${ROOT}/directory | stdout=stdout.txt | == Environment variables == By default the child process will get a copy of the parent process's environment variables. The `env` argument can be used to give the child a custom environment as a Python dictionary. If there is a need to specify only certain environment variable, it is possible to use the `env:<name>` format to set or override only that named variables. It is also possible to use these two approaches together. Examples: | `Run Process` | program | env=${environ} | | `Run Process` | program | env:PATH=%{PATH}${:}${PROGRAM DIR} | | `Run Process` | program | env=${environ} | env:EXTRA=value | == Standard output and error streams == By default processes are run so that their standard output and standard error streams are kept in the memory. This works fine normally, but if there is a lot of output, the output buffers may get full and the program could hang. To avoid output buffers getting full, it is possible to use `stdout` and `stderr` arguments to specify files on the file system where to redirect the outputs. This can also be useful if other processes or other keywords need to read or manipulate the outputs somehow. Given `stdout` and `stderr` paths are relative to the `current working directory`. Forward slashes in the given paths are automatically converted to backslashes on Windows. As a special feature, it is possible to redirect the standard error to the standard output by using `stderr=STDOUT`. Regardless are outputs redirected to files or not, they are accessible through the `result object` returned when the process ends. Examples: | ${result} = | `Run Process` | program | stdout=${TEMPDIR}/stdout.txt | stderr=${TEMPDIR}/stderr.txt | | `Log Many` | stdout: ${result.stdout} | stderr: ${result.stderr} | | ${result} = | `Run Process` | program | stderr=STDOUT | | `Log` | all output: ${result.stdout} | *Note:* The created output files are not automatically removed after the test run. The user is responsible to remove them if needed. == Alias == A custom name given to the process that can be used when selecting the `active process`. Example: | `Start Process` | program | alias=example | = Active process = The test library keeps record which of the started processes is currently active. By default it is latest process started with `Start Process`, but `Switch Process` can be used to select a different one. The keywords that operate on started processes will use the active process by default, but it is possible to explicitly select a different process using the `handle` argument. The handle can be the identifier returned by `Start Process` or an explicitly given `alias`. = Stopping processes = Started processed can be stopped using `Terminate Process` and `Terminate All Processes`. The former is used for stopping a selected process, and the latter to make sure all processes are stopped, for example, in a suite teardown. Both keywords use `subprocess` [http://docs.python.org/2.7/library/subprocess.html#subprocess.Popen.terminate|terminate()] method by default, but can be configured to use [http://docs.python.org/2.7/library/subprocess.html#subprocess.Popen.kill|kill()] instead. Because both `terminate()` and `kill()` methods were added to `subprocess` in Python 2.6, stopping processes does not work with Python or Jython 2.5. Unfortunately at least beta releases of Jython 2.7 [http://bugs.jython.org/issue1898|do not seem to support it either]. Examples: | `Terminate Process` | kill=True | | `Terminate All Processes` | = Result object = `Run Process` and `Wait For Process` keywords return a result object that contains information about the process execution as its attibutes. What is available is documented in the table below. | *Attribute* | *Explanation* | | rc | Return code of the process as an integer. | | stdout | Contents of the standard output stream. | | stderr | Contents of the standard error stream. | | stdout_path | Path where stdout was redirected or `None` if not redirected. | | stderr_path | Path where stderr was redirected or `None` if not redirected. | Example: | ${result} = | `Run Process` | program | | `Should Be Equal As Integers` | ${result.rc} | | | `Should Match` | ${result.stdout} | Some t?xt* | | `Should Be Empty` | ${result.stderr} | | | ${stdout} = | `Get File` | ${result.stdout_path} | | `File Should Be Empty` | ${result.stderr_path} | | | `Should Be Equal` | ${result.stdout} | ${stdout} | = Using with OperatingSystem library = The OperatingSystem library also contains keywords for running processes. They are not as flexible as the keywords provided by this library, and thus not recommended to be used anymore. They may eventually even be deprecated. There is a name collision because both of these libraries have `Start Process` and `Switch Process` keywords. This is handled so that if both libraries are imported, the keywords in the Process library are used by default. If there is a need to use the OperatingSystem variants, it is possible to use `OperatingSystem.Start Process` syntax or use the `BuiltIn` keyword `Set Library Search Order` to change the priority. Other keywords in the OperatingSystem library can be used freely with keywords in the Process library. = Example = | ***** Settings ***** | Library Process | Suite Teardown `Terminate All Processes` kill=True | | ***** Test Cases ***** | Example | `Start Process` program arg1 arg2 alias=First | ${handle} = `Start Process` command.sh arg | command2.sh shell=True cwd=/path | ${result} = `Run Process` ${CURDIR}/script.py | `Should Not Contain` ${result.stdout} FAIL | `Terminate Process` ${handle} | ${result} = `Wait For Process` First | `Should Be Equal As Integers` ${result.rc} 0 """ ROBOT_LIBRARY_SCOPE = 'GLOBAL' ROBOT_LIBRARY_VERSION = get_version() def __init__(self): self._processes = ConnectionCache('No active process.') self._results = {} def run_process(self, command, *arguments, **configuration): """Runs a process and waits for it to complete. See `Specifying command and arguments` and `Process configuration` for more information about the arguments. Returns a `result object` containing information about the execution. This command does not change the `active process`. """ current = self._processes.current try: handle = self.start_process(command, *arguments, **configuration) return self.wait_for_process(handle) finally: self._processes.current = current def start_process(self, command, *arguments, **configuration): """Starts a new process on background. See `Specifying command and arguments` and `Process configuration` for more information about the arguments. Makes the started process new `active process`. Returns an identifier that can be used as a handle to active the started process if needed. """ config = ProcessConfig(**configuration) executable_command = self._cmd(arguments, command, config.shell) logger.info('Starting process:\n%s' % executable_command) logger.debug('Process configuration:\n%s' % config) process = subprocess.Popen(executable_command, stdout=config.stdout_stream, stderr=config.stderr_stream, stdin=subprocess.PIPE, shell=config.shell, cwd=config.cwd, env=config.env, universal_newlines=True) self._results[process] = ExecutionResult(process, config.stdout_stream, config.stderr_stream) return self._processes.register(process, alias=config.alias) def _cmd(self, args, command, use_shell): command = [encode_to_system(item) for item in [command] + list(args)] if not use_shell: return command if args: return subprocess.list2cmdline(command) return command[0] def is_process_running(self, handle=None): """Checks is the process running or not. If `handle` is not given, uses the current `active process`. Returns `True` if the process is still running and `False` otherwise. """ return self._processes[handle].poll() is None def process_should_be_running(self, handle=None, error_message='Process is not running.'): """Verifies that the process is running. If `handle` is not given, uses the current `active process`. Fails if the process has stopped. """ if not self.is_process_running(handle): raise AssertionError(error_message) def process_should_be_stopped(self, handle=None, error_message='Process is running.'): """Verifies that the process is not running. If `handle` is not given, uses the current `active process`. Fails if the process is still running. """ if self.is_process_running(handle): raise AssertionError(error_message) def wait_for_process(self, handle=None): """Waits for the process to complete. If `handle` is not given, uses the current `active process`. Returns a `result object` containing information about the execution. """ process = self._processes[handle] result = self._results[process] logger.info('Waiting for process to complete.') result.rc = process.wait() or 0 logger.info('Process completed.') return result def terminate_process(self, handle=None, kill=False): """Terminates the process. If `handle` is not given, uses the current `active process`. See `Stopping process` for more details. """ process = self._processes[handle] try: terminator = process.kill if kill else process.terminate except AttributeError: raise RuntimeError('Terminating processes is not supported ' 'by this interpreter version.') logger.info('Killing process.' if kill else 'Terminating process.') try: terminator() except OSError: if process.poll() is None: raise logger.debug('Ignored OSError because process was stopped.') def terminate_all_processes(self, kill=True): """Terminates all still running processes started by this library. See `Stopping processes` for more details. """ for handle in range(1, len(self._processes) + 1): if self.is_process_running(handle): self.terminate_process(handle, kill=kill) self.__init__() def get_process_id(self, handle=None): """Returns the process ID (pid) of the process. If `handle` is not given, uses the current `active process`. Returns the pid assigned by the operating system as an integer. Note that with Jython, at least with the 2.5 version, the returned pid seems to always be `None`. The pid is not the same as the identifier returned by `Start Process` that is used internally by this library. """ return self._processes[handle].pid def get_process_object(self, handle=None): """Return the underlying `subprocess.Popen` object. If `handle` is not given, uses the current `active process`. """ return self._processes[handle] def switch_process(self, handle): """Makes the specified process the current `active process`. The handle can be an identifier returned by `Start Process` or the `alias` given to it explicitly. Example: | `Start Process` | prog1 | alias=process1 | | `Start Process` | prog2 | alias=process2 | | # currently active process is process2 | | `Switch Process` | process1 | | # now active process is process 1 | """ self._processes.switch(handle)
The library has a known limitation that it cannot be used with timeouts on Python. Support for IronPython was added in Robot Framework 2.9.2. """ from robot.version import get_version from robot.utils import IRONPYTHON, JYTHON, is_truthy if JYTHON: from .dialogs_jy import MessageDialog, PassFailDialog, InputDialog, SelectionDialog elif IRONPYTHON: from .dialogs_ipy import MessageDialog, PassFailDialog, InputDialog, SelectionDialog else: from .dialogs_py import MessageDialog, PassFailDialog, InputDialog, SelectionDialog __version__ = get_version() __all__ = ["execute_manual_step", "get_value_from_user", "get_selection_from_user", "pause_execution"] def pause_execution(message="Test execution paused. Press OK to continue."): """Pauses test execution until user clicks ``Ok`` button. ``message`` is the message shown in the dialog. """ MessageDialog(message).show() def execute_manual_step(message, default_error=""): """Pauses test execution until user sets the keyword status. User can press either ``PASS`` or ``FAIL`` button. In the latter case execution
# The master toctree document. master_doc = 'index' # General information about the project. project = u'Robot Framework' copyright = u'2008-2014, Nokia Solutions and Networks' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. version = VERSION # The full version, including alpha/beta/rc tags. release = get_version() # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: #today = '' # Else, today_fmt is used as the format for a strftime call. #today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = ['_build']