feat: add #SLEEP keyword mkorpela#592 mkorpela#500

- Fixed initial implementation
- Updated documentation

README.md

@@ -265,6 +265,51 @@ There different possibilities to influence the execution:
 --test robotTest.1 Scalar.Test With Arguments and Return Values
 --test robotTest.3 Dictionary.Test with Dictionaries as Arguments
 --test robotTest.3 Dictionary.Test with FOR loops and Dictionaries #DEPENDS robotTest.1 Scalar.Test Case with Return Values
+```
+
+  * By using the command `#SLEEP X`, where `X` is an integer in the range [0-3600] (in seconds), you can define a startup delay for each subprocess.
+
+- `#SLEEP` affects the next line unless the next line starts a group with `{`, in which case the delay applies to the entire group.
+- If the next line begins with `--test` or `--suite`, the delay is applied to that specific item.
+- Any other occurrences of `#SLEEP` are ignored.
+
+The following example clarifies the behavior:
+
+```sh
+pabot --process 2 --ordering order.txt data_1
+```
+
+where order.txt is:
+
+```
+#SLEEP 1
+{
+#SLEEP 2
+--suite Data 1.suite A
+#SLEEP 3
+--suite Data 1.suite B
+#SLEEP 4
+}
+#SLEEP 5
+#SLEEP 6
+--suite Data 1.suite C
+#SLEEP 7
+--suite Data 1.suite D
+#SLEEP 8
+```
+
+prints something like this:
+
+```
+2025-02-15 19:15:00.408321 [0] [ID:1] SLEEPING 6 SECONDS BEFORE STARTING Data 1.suite C
+2025-02-15 19:15:00.408321 [1] [ID:0] SLEEPING 1 SECONDS BEFORE STARTING Group_Data 1.suite A_Data 1.suite B
+2025-02-15 19:15:01.409389 [PID:52008] [1] [ID:0] EXECUTING Group_Data 1.suite A_Data 1.suite B
+2025-02-15 19:15:06.409024 [PID:1528] [0] [ID:1] EXECUTING Data 1.suite C
+2025-02-15 19:15:09.257564 [PID:52008] [1] [ID:0] PASSED Group_Data 1.suite A_Data 1.suite B in 7.8 seconds
+2025-02-15 19:15:09.259067 [1] [ID:2] SLEEPING 7 SECONDS BEFORE STARTING Data 1.suite D
+2025-02-15 19:15:09.647342 [PID:1528] [0] [ID:1] PASSED Data 1.suite C in 3.2 seconds
+2025-02-15 19:15:16.260432 [PID:48156] [1] [ID:2] EXECUTING Data 1.suite D
+2025-02-15 19:15:18.696420 [PID:48156] [1] [ID:2] PASSED Data 1.suite D in 2.4 seconds
 ```
 
 ### Programmatic use

src/pabot/execution_items.py

@@ -290,18 +290,17 @@ class SleepItem(ExecutionItem):
 
     def __init__(self, time):
         try:
-            3600 >= int(time) >= 0  # 1h max.
+            assert 3600 >= int(time) >= 0  # 1 h max.
+            self.name = time
+            self.sleep = int(time)
         except ValueError:
-            raise ValueError("#SLEEP value %s is not integer or in between 0 and 3600" % self.name)
-        self.name = time
+            raise ValueError("#SLEEP value %s is not integer" % time)
+        except AssertionError:
+            raise ValueError("#SLEEP value %s is not in between 0 and 3600" % time)
 
     def line(self):
         return "#SLEEP " + self.name
 
-    def get_time_from_sleep_item(self):
-        # type: () -> int
-        return int(self.name)  # This is already check as integer when parsing
-
 
 class GroupStartItem(ExecutionItem):
     type = "group"

src/pabot/pabot.py

@@ -532,7 +532,7 @@ def _run(
     timestamp = datetime.datetime.now()
     if sleep_before_start > 0:
         _write(
-            "%s [%s] [ID:%s] SLEEPING %s second before starting %s"
+            "%s [%s] [ID:%s] SLEEPING %s SECONDS BEFORE STARTING %s"
             % (timestamp, pool_id, item_index, sleep_before_start, item_name),
         )
         time.sleep(sleep_before_start)
@@ -2101,10 +2101,10 @@ def _set_sleep_times(ordering_arg):
     in_group = False
     output = copy.deepcopy(ordering_arg)
     if output is not None:
-        if len(output) > 2:
+        if len(output) >= 2:
             for i in range(len(output) - 1):
                 if isinstance(output[i], SleepItem):
-                    set_sleep_value = output[i].get_time_from_sleep_item()
+                    set_sleep_value = output[i].get_sleep()
                 else:
                     set_sleep_value = 0
                 if isinstance(output[i], GroupStartItem):