Robot Framework 时间格式完全指南：数字、时间字符串与计时器字符串详解

Robot Framework 时间格式完全指南数字、时间字符串与计时器字符串详解【免费下载链接】robotframeworkGeneric automation framework for acceptance testing and RPA项目地址: https://gitcode.com/gh_mirrors/ro/robotframeworkRobot Framework 拥有一套自有的、既灵活又易读的时间格式被内置库关键字如 BuiltIn 的Sleep、Wait Until Keyword Succeeds、DateTime 标准库以及测试与关键字超时机制共同使用。本文基于用户指南附录 TimeFormat.rst 及仓库源码系统讲解三种时间表示形式数字、时间字符串、计时器字符串的语法规则、解析原理与实战用法读完即可在任何需要时间参数的场景中准确书写并调试时间表达式。时间格式的适用场景在 Robot Framework 中凡是接受时间作为参数的地方几乎都遵循本文描述的统一时间格式。典型场景包括等待与重试类关键字Sleep、Wait Until Keyword Succeeds、Repeat Keyword内置库 BuiltIn.py时间转换关键字DateTime 库中的Convert Time、Add Time To Date、Subtract Time From Date等超时设置测试用例Test、任务Task与关键字Keyword的timeout设置以及Wait Until Keyword Succeeds的retry_interval参数WHILE循环的limit、Wait Until Created系列关键字等其他接受时间参数的内置功能。在 BuiltIn.py 中Sleep的文档明确写道timemay be either a number or a time string……they are fully explained in an appendix of Robot Framework User Guide即指向本文所在的附录章节。一、Time as number数字即秒最简单的时间表示方式就是直接给出一个普通数字此时它被解释为秒。整数、浮点数均可既可以是真实的数字也可以是包含数值的字符串。Sleep 1 # 睡 1 秒 Sleep 1.5 # 睡 1.5 秒 Sleep 0.25 # 睡 0.25 秒字符串形式的数值同样有效在源码 robottime.py 中_number_to_secs通过float(number)尝试把输入直接转换为秒数配合科学计数法字符串如1e2也有效单元测试 test_robottime.py 验证了1、42、1.1、-1.5e3、1e2等输入均能正确解析。注意在某些上下文中纯数字会被解释成其他含义而非时间。例如在WHILE循环中整数形式的limit表示最大迭代次数而不是秒数。相关说明见控制结构文档中 Limiting WHILE loop iterations 一节。二、Time as time string可读的时间字符串时间字符串形式形如2 minutes 42 seconds通常比纯秒数更直观。例如4200秒很难一眼看出是多久而1 hour 10 minutes则一目了然。基本语法规则基本结构是先一个数字后一个表示单位的文本数字可以是整数或浮点数整个格式不区分大小写、不区分空格1 MINUTE、1minute、1 minute等价可以通过-前缀表示负时间如- 10 seconds。可用时间单位一览单位完整拼写单数 / 复数缩写对应秒数周week / weeksw60 × 60 × 24 × 7天day / daysd60 × 60 × 24小时hour / hoursh60 × 60分钟minute / minutesmins、min、m60秒second / secondssecs、sec、s1毫秒millisecond / millisecondsmillis、ms0.001微秒microsecond / microsecondsus、μs0.000001纳秒nanosecond / nanosecondsns0.000000001从源码 robottime.py 的_normalize_timestr看实际实现还额外接受millisec、msec等毫秒别名millisec、msec及其复数形式比文档列出的拼写更宽松。此外微秒与纳秒支持自 Robot Framework 6.0 起周weeks的支持自 Robot Framework 7.1 起。合法示例文档给出的完整示例1 min 30 secs 1.5 minutes 90 s 1 day 2 hours 3 minutes 4 seconds 5 milliseconds 6 microseconds 7 nanoseconds 8 weeks 7 days 6 hours 5 minutes 4 seconds 3 milliseconds 2 microseconds 1 nanosecond 1d 2h 3m 4s 5ms 6μs 7 ns 8w 7d 6h 5m 4s 3ms 2μs 1ns - 10 seconds注意最后一行-与数字之间可以存在空格负号对整个时间表达式生效。解析原理归一化 字母扫描从源码看_time_string_to_secsrobottime.py的解析分为两步归一化_normalize_timestr先把所有别名替换为单字母标记——n纳秒、u微秒、M毫秒、s秒、m分钟、h小时、d天、w周字母扫描逐字符扫描遇到上述标记字母时把此前累积的数字字符串转换为对应单位的数值并累加最终按公式nanos/1E9 micros/1E6 millis/1000 secs mins*60 hours*3600 days*86400 weeks*604800计算总秒数负数先取符号。因此10DAY10H10M10SEC、1day 23h 46min 7s 666ms这类写法都能正确解析为秒数——这一行为在 test_robottime.py 中有大量断言佐证。三、Time as timer string计时器格式时间还可以用类似计时器的格式hh:mm:ss.mil表示mil为毫秒。该格式有两个自由度小时部分和毫秒部分都是可选的mm:ss、hh:mm:ss均可无意义的首尾零可以省略如01:02:03可写成1:2:300:00:01可写成00:01或1取决于对齐方式通过-前缀表示负时间。计时器格式与时间字符串的等价对照文档给出的完整对照表如下TimerTime string00:00:011 second01:02:031 hour 2 minutes 3 seconds1:00:001 hour100:00:00100 hours00:022 seconds42:0042 minutes00:01:02.0031 minute 2 seconds 3 milliseconds00:01.51.5 seconds-01:02.345- 1 minute 2 seconds 345 milliseconds解读几个容易困惑的点00:02中省略了小时与毫秒02落在分钟位上因此是 2 秒42:00中42落在分钟位等于 42 分钟此时42可理解为42 分 00 秒100:00:00的小时位允许超过 23100 小时00:01.5的毫秒位是5结合分钟位01即1.5秒负号写法-01:02.345等价于- 1 minute 2 seconds 345 milliseconds。解析原理正则匹配源码 robottime.py 定义了计时器格式的匹配正则_timer_re re.compile(r^([-])?(\d:)?(\d):(\d)(\.\d)?$)其分组依次为符号/-可选、小时段含冒号可选、分钟段、秒段、毫秒段可选。_timer_to_secsrobottime.py随后将各段换算为秒并求和seconds float(minutes) * 60 float(seconds)存在小时段时再加上float(hours) * 3600存在毫秒段时按小数位数换算例如.1234→0.1234秒解析后按默认精度舍入前缀为-时取反。正因为有该正则约束01:02:03:04四段、01:02:03foo尾部带字母等均会被判定为非法抛出ValueError——详见测试 test_robottime.py。四、三种格式的统一入口与精度细节timestr_to_secs统一解析入口所有时间参数最终都汇聚到 timestr_to_secs。它按顺序尝试三个转换器converters [_number_to_secs, _timer_to_secs, _time_string_to_secs]即先按数字解析失败再按计时器最后按时间字符串。只要有一个返回非None即作为结果返回全部失败则抛出ValueError(fInvalid time string {timestr}.)。几个值得注意的细节默认舍入round_to3即结果默认保留 3 位小数毫秒级精度传入round_toNone可关闭舍入保留完整精度。DateTime 库的Convert Time就使用了timestr_to_secs(time, round_toNone)见 DateTime.pytimedelta支持自 RF 6.0.1 起timedelta实例也可直接作为输入返回total_seconds()银行家舍入Python 的round采用银行家舍入偶数舍入测试 test_robottime.py 专门验证了timestr_to_secs(0.5, 0)得0、timestr_to_secs(1.5, 0)得2无效输入、foo、1min 2y未知单位、1sec 42 millis 3尾部残留数字等都会抛出ValueError。反向转换secs_to_timestrsecs_to_timestrrobottime.py把秒数转换回人类可读的时间字符串遵循两条规则零值部分不输出如3 minutes 4 seconds而非0 days 0 hours 3 minutes 4 seconds小时最大 23、分钟与秒最大 59如1 minute 40 seconds而非100 seconds传compactTrue时使用紧凑后缀1d 2h 3min 4s 5ms。例如secs_to_timestr(171967.667)输出1 day 23 hours 46 minutes 7 seconds 667 milliseconds紧凑模式输出1d 23h 46min 7s 667ms测试见 test_robottime.py。五、在真实场景中的落地BuiltIn 关键字Sleep接受数字或时间字符串reason参数会连同实际睡眠时长一并记入日志Wait Until Keyword Succeedsretry既可以是时间时间格式如1 minute、2 min 3 s、4.5也可以是次数如3xretry_interval则始终是时间内部通过timestr_to_secs(retry_interval)换算见 BuiltIn.pyRepeat Keywordrepeat传数字表示执行次数传时间字符串如1 minute表示按时长重复注意单独的数字在此处会被当作次数这正是前文纯数字可能被解释为其他含义的又一实例见 BuiltIn.py。Wait Until Keyword Succeeds 2 min 5 sec My keyword argument ${result} Wait Until Keyword Succeeds 3x 200ms My keyword Sleep 0.5s测试 / 关键字超时在超时实现 timeouts/init.py 中replace_variables会把设置文件或命令行传入的 timeout 字符串做一次归一化self.secs timestr_to_secs(self.string) self.string secs_to_timestr(self.secs)即先解析为秒再重新格式化为规范字符串因此无论在 testcase 的[Timeout]设置 中写1 minute 30 seconds还是90s最终日志里都会显示为统一格式。超时粒度按 1ms 计算time_left()中round(..., 3)并区分测试超时与关键字超时。DateTime 库DateTime.py 中的Convert Time支持verbosesecs_to_timestr全称形式、compact紧凑形式与timer三种输出格式与本文讨论的时间格式体系完全一致。六、延伸同一模块中的时间解析工具附录主题聚焦于时间段格式但承载它的 robottime.py 模块同时提供与时间字符串一脉相承的辅助函数理解它们有助于举一反三parse_timerobottime.py用于解析时刻而非时长支持 epoch 数字、ISO 风格时间戳、NOW、UTC以及NOW - 1 day、UTC 1 hour 30 min等相对时间表达式其中相对时间的加减量部分正是复用timestr_to_secs解析的parse_timestamprobottime.py自 RF 7.0 起宽松解析 ISO 8601 风格时间戳elapsed_time_to_stringrobottime.py将耗时转换为hh:mm:ss.mil计时器格式与本文第三节的计时器字符串互相对应。小结掌握 Robot Framework 时间格式只需记住三个要点纯数字是秒、时间字符串是数字 单位且大小写空格不敏感、计时器字符串是hh:mm:ss.mil且小时与毫秒可选。底层由 robottime.py 的timestr_to_secs统一解析超时、Sleep、等待重试、DateTime 转换等场景全部共用这套规则。写作时间参数时优先使用可读性强的1 minute 30 seconds或90s必要时用-前缀表达负时间就能在几乎所有内置功能中无缝复用。【免费下载链接】robotframeworkGeneric automation framework for acceptance testing and RPA项目地址: https://gitcode.com/gh_mirrors/ro/robotframework创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考