teuton 3.2.1 → 3.4.0

data/docs/learn/13-feedback.md

@@ -1,4 +1,4 @@
-[<< back](README.md)
+[<<back](../../README.md)
 
 # feedback
 
@@ -36,14 +36,15 @@ With `feedback: false` the fields are hidden: command, alterations, expected and
 Executing `teuton run examples/13-feedback`, we get this output:
 
 ```
-GROUPS
-- Hide feedback messages from output
-    01 (1.0/1.0)
-        Description : Service SSH disabled
-        Command     : *********************
-        Output      : *********
-        Duration    : 0.011 (local)
-        Alterations : **********************
-        Expected    : **************
-        Result      : ********
+☰ GROUPS
+ ▶ Hide feedback messages from output
+   ✔ 01 (1.0/1.0)   ┌──
+        Description │ Service SSH disabled
+        Command     │ *********************
+        Output      │ *********
+        Duration    │ 0.145 (local)
+        Alterations │ **********************
+        Expected    │ **************
+        Result      │ ********
+                    └──
 ```

data/docs/learn/14-moodle_id.md

@@ -1,4 +1,4 @@
-[<< back](README.md)
+[<<back](../../README.md)
 
 # Moodle
 
@@ -12,7 +12,7 @@ Add a new field called `tt_moodle_id` to each case in "config.yaml". Fill it wit
 
 Example:
 
-```
+```yaml
 global:
 cases:
 - tt_members: Darth Vader
@@ -31,7 +31,7 @@ We use `tt_moodle_max_score` to customize Moodle max score. So when Teuton expor
 
 ## Example
 
-```
+```yaml
 global:
   tt_moodle_max_score: 10
 cases:

data/docs/learn/15-readme.md

@@ -1,4 +1,4 @@
-[<< back](README.md)
+[<<back](../../README.md)
 
 # readme
 
@@ -11,12 +11,12 @@ Take a look at our test definition section (Group):
 ```ruby
 group "Customize readme output" do
 
-  readme "This is our README example."
-  readme "And here we'll see how to use readme keyword"
+  doc "This is our README example."
+  doc "And here we'll see how to use readme keyword"
 
   target "Create user david."
-  readme "Help: you can use 'useradd' command to create users."
-  readme "Remember: Only root is permitted to create new users."
+  doc "Help: you can use 'useradd' command to create users."
+  doc "Remember: Only root is permitted to create new users."
 
   run "id david"
   expect "david"
@@ -26,30 +26,30 @@ end
 
 > In this example, localhost's OS must be GNU/Linux (any other compatible OS) because the command used is `id david`.
 
-There exists some `readme` instructions after `group` and `target` lines.
+There exists some `doc` instructions after `group` and `target` lines.
 
 ## Execution
 
-To generate automatically a README file from previous test, execute this:
+To generate automatically a Markdown file from previous test, execute this:
 
 ```
-$ teuton readme example/15-readme > example/15-readme/README.md
+$ teuton doc example/15-doc > example/15-doc/README.md
 ```
 
 ## Result
 
-Content of `example/15-readme/README.md` file.
+Content of `example/15-doc/README.md` file.
 
 ---
 
 ```
-Date   : 2025-11-12 22:11:47 +0000
-Teuton : 2.10.7
+Date   : 2026-10-21 21:54:49 +0100
+Teuton : 3.2.1
 ```
 
 # Test: 15-readme
 
-## Customize readme output
+## Customize doc output
 This is our readme example.
 And here we'll see how to use readme keyword
 

data/docs/learn/16-include.md

@@ -1,4 +1,4 @@
-[<< back](README.md)
+[<<back](../../README.md)
 
 # include
 
@@ -58,12 +58,12 @@ Config files into `moreconfigfiles` folder:
 
 If we execute the test we will see that 3 cases are processed. Which are defined in the files `file01.yaml`, `02/file02.yaml` and `file03.yml`.
 
-```
-CASE RESULTS
-+------+---------+-------+-------+
-| CASE | MEMBERS | GRADE | STATE |
-| 01   | file02  | 0.0   | ?     |
-| 02   | file01  | 100.0 | ✔     |
-| 03   | file03  | 0.0   | ?     |
-+------+---------+-------+-------+
+``` 
+ ☰ CASE RESULTS
+┌──────┬────────────┬───────┬───────┐
+│ CASE │ MEMBERS    │ GRADE │ STATE │
+│ 01   │ student_02 │ 0.0   │ ?     │
+│ 02   │ student_01 │ 100.0 │ ✔     │
+│ 03   │ student_03 │ 0.0   │ ?     │
+└──────┴────────────┴───────┴───────┘
 ```

data/docs/learn/17-alias.md

@@ -1,4 +1,4 @@
-[<< back](README.md)
+[<<back](../../README.md)
 
 # alias
 
@@ -50,4 +50,4 @@ cases:
   username: obiwan
 ```
 
-Now our test will work correctly. Calling `get(:super)` will return the same value as doing `get(:superuser).
+Now our test will work correctly. Calling `get(:super)` will return the same value as doing `get(:superuser)`.

data/docs/learn/18-log.md

@@ -1,4 +1,4 @@
-[<< back](README.md)
+[<<back](../../README.md)
 
 # log
 
@@ -53,49 +53,51 @@ end
 Content of `var/18-log/case-01.txt` file.
 
 ```txt
-CONFIGURATION
-+----------------+-----------------------------------+
-| tt_config_path | examples/18-log/config.yaml       |
-| tt_members     | TOCHANGE                          |
-| tt_script_path | examples/18-log/start.rb          |
-| tt_sequence    | false                             |
-| tt_skip        | false                             |
-| values1        | ["A1", "B1", "C1"]                |
-| values2        | {:p1=>"A2", :p2=>"B2", :p3=>"C2"} |
-+----------------+-----------------------------------+
+$ cat var/18-log/case-01.txt 
+
+ CONFIGURATION
+┌────────────────┬───────────────────────────────────┐
+│ tt_config_path │ examples/18-log/config.yaml       │
+│ tt_members     │ TOCHANGE                          │
+│ tt_script_path │ examples/18-log/start.rb          │
+│ tt_sequence    │ false                             │
+│ tt_skip        │ false                             │
+│ values1        │ ["A1", "B1", "C1"]                │
+│ values2        │ {:p1=>"A2", :p2=>"B2", :p3=>"C2"} │
+└────────────────┴───────────────────────────────────┘
 
 LOGS
-    [22:35:04]  INFO: Using log messages.
-    [22:35:04]  INFO: uid=1000(david) gid=1000(david) grupos=1000(david),478(wheel),464(vboxusers),108(libvirt),107(qemu),462(vagrant),460(docker),452(ollama)
-    [22:35:04] ERROR: Problem detected!
-    [22:35:04] WARN!: This is a warning
-    [22:35:04]  INFO: Hi, there!
-    [22:35:04]  INFO: -------------
-    [22:35:04]  INFO: Array values : ["A1", "B1", "C1"]
-    [22:35:04]  INFO: Hash values  : {:p1=>"A2", :p2=>"B2", :p3=>"C2"}
-
-GROUPS
-- Learning about log messages
-    01 (1.0/1.0)
-        Description : Create user david
-        Command     : id david
-        Output      : uid=1000(david) gid=1000(david) grupos=1000(david),478(wheel),464(vboxusers),108(libvirt),107(qemu),462(vagrant),460(docker),452(ollama)
-        Duration    : 0.005 (local)
-        Alterations : find(david) & count
-        Expected    : Greater than 0
-        Result      : 1
-
-RESULTS
-+--------------+---------------------------+
-| unique_fault | 0                         |
-| case_id      | 01                        |
-| start_time   | 2026-10-12 22:35:04 +0100 |
-| finish_time  | 2026-10-12 22:35:04 +0100 |
-| duration     | 0.004786563               |
-| max_weight   | 1.0                       |
-| good_weight  | 1.0                       |
-| fail_weight  | 0                         |
-| fail_counter | 0                         |
-| grade        | 100                       |
-+--------------+---------------------------+
+   [22:00:21]  INFO| Using log messages.
+   [22:00:21]  INFO| uid=1000(david) gid=1000(david) grupos=1000(david),478(wheel),464(vboxusers),108(libvirt),107(qemu),462(vagrant),460(docker),452(ollama)
+   [22:00:21] ERROR| Problem detected!
+   [22:00:21]  WARN| This is a warning
+   [22:00:21]  INFO| Hi, there!
+   [22:00:21]  INFO| -------------
+   [22:00:21]  INFO| Array values : ["A1", "B1", "C1"]
+   [22:00:21]  INFO| Hash values  : {:p1=>"A2", :p2=>"B2", :p3=>"C2"}
+
+ GROUPS
+ ▶ Learning about log messages
+   ✔ 01 (1.0/1.0)   ┌──
+        Description │ Create user david
+        Command     │ id david
+        Output      │ uid=1000(david) gid=1000(david) grupos=1000(david),478(wheel),464(vboxusers),108(libvirt),107(qemu),462(vagrant),460(docker),452(ollama)
+        Duration    │ 0.005 (local)
+        Alterations │ find(david) & count
+        Expected    │ Greater than 0
+        Result      │ 1
+                    └──
+ RESULTS
+┌──────────────┬───────────────────────────┐
+│ unique_fault │ 0                         │
+│ case_id      │ 01                        │
+│ start_time   │ 2026-10-21 21:57:57 +0100 │
+│ finish_time  │ 2026-10-21 21:57:57 +0100 │
+│ duration     │ 0.005315073               │
+│ max_weight   │ 1.0                       │
+│ good_weight  │ 1.0                       │
+│ fail_weight  │ 0                         │
+│ fail_counter │ 0                         │
+│ grade        │ 100                       │
+└──────────────┴───────────────────────────┘
 ```

data/docs/learn/19-read_vars.md

@@ -1,4 +1,4 @@
-[<< back](README.md)
+[<<back](../../README.md)
 
 # Read vars
 

data/docs/learn/20-macros.md

@@ -1,4 +1,4 @@
-[<< back](README.md)
+[<<back](../../README.md)
 
 # Macros
 

data/docs/learn/21-exit_codes.md

@@ -1,4 +1,4 @@
-[<< back](README.md)
+[<<back](../../README.md)
 
 # Example: exit_codes
 

data/docs/learn/22-result.md

@@ -1,4 +1,4 @@
-[<< back](README.md)
+[<<back](../../README.md)
 
 # result
 

data/docs/learn/23-test-code.md

@@ -1,4 +1,4 @@
-[<<back](README.md)
+[<<back](../../README.md)
 
 # Test code
 
@@ -43,22 +43,25 @@ Define config params:
 global:
   folder: examples/23-test-code/code
 cases:
-- tt_members: student_1
+- tt_members: student_1_python
   filename: math_1.py
-- tt_members: student_2
+- tt_members: student_2_python
   filename: math_2.py
+- tt_members: student_3_ruby
+  filename: math_3.rb
 ```
 
 * Copy students files into `code` subfolder.
 * Now run Teuton test:
 
 ```
-$ teuton examples/23-test-code
-
-CASE RESULTS
-+------+-----------+-------+-------+
-| CASE | MEMBERS   | GRADE | STATE |
-| 01   | student_1 | 100.0 | ✔     |
-| 02   | student_2 | 100.0 | ✔     |
-+------+-----------+-------+-------+
+$ teuton examples/23-test-code 
+ 
+ CASE RESULTS
+┌──────┬──────────────────┬───────┬───────┐
+│ CASE │ MEMBERS          │ GRADE │ STATE │
+│ 01   │ student_1_python │ 100.0 │ ✔     │
+│ 02   │ student_2_python │ 100.0 │ ✔     │
+│ 03   │ student_3_ruby   │ 100.0 │ ✔     │
+└──────┴──────────────────┴───────┴───────┘
 ```

data/docs/learn/24-test-sql.md

@@ -1,4 +1,4 @@
-[<<back](README.md)
+[<<back](../../README.md)
 
 # Test SQL and database content
 
@@ -62,9 +62,9 @@ cases:
 ```
 $ teuton examples/24-test-sql                                   
 
-CASE RESULTS
-+------+-----------+-------+-------+
-| CASE | MEMBERS   | GRADE | STATE |
-| 01   | student_1 | 100.0 | ✔     |
-+------+-----------+-------+-------+
+ CASE RESULTS
+┌──────┬────────────────┬───────┬───────┐
+│ CASE │ MEMBERS        │ GRADE │ STATE │
+│ 01   │ student_1_name │ 100.0 │ ✔     │
+└──────┴────────────────┴───────┴───────┘
 ```

data/docs/learn/25-expect-result.md

@@ -1,4 +1,4 @@
-[<<back](README.md)
+[<<back](../../README.md)
 
 # expect vs result
 

data/docs/learn/26-expect_sequence.md

@@ -1,4 +1,4 @@
-[<<back](README.md)
+[<<back](../../README.md)
 
 # DSL: expect_sequence
 
@@ -8,7 +8,7 @@ Evaluate the occurrence of a certain sequence that takes place in different line
 
 ## Description
 
-In the classic target/run/expect, the expect statement works by locating lines from the output of the previous command that meet certain criteria.
+In the classic "target/run/expect", the expect statement works by locating lines from the output of the previous command that meet certain criteria.
 
 We can even (using regular expressions) detect if there is any line in the output where a certain sequence appears.
 

data/docs/learn/27-run_script.md

@@ -1,4 +1,4 @@
-[<<back](README.md)
+[<<back](../../README.md)
 
 # DSL: run_script
 
@@ -90,8 +90,11 @@ CONN ERRORS
 +------+---------+-------+------------------+
 ```
 
-Meaning of progress symbols:
-* `.`: check ok
-* `F`: check fail
-* `!`: connection fail
-* `u`: upload ok
+**Meaning of progress symbols**
+
+| Symbol | Description     |
+| ------ | --------------- |
+| `.`    | check ok        |
+| `F`    | check fail      |
+| `!`    | connection fail |
+| `u`    | upload ok       |

data/docs/learn/28-upload.md

@@ -1,9 +1,11 @@
-[<<back](README.md)
+[<<back](../../README.md)
 
 # DSL: upload
 
 `upload` is a dsl instruction, whose purpose is to upload files to the remote host.
 
+> **Recommendation**: Use this function as little as possible, to minimize any modifications, changes, or alterations to the remote device.
+
 ```ruby
   upload "FILENAME", to: :host1
 ```

data/docs/learn/31-event-stop.md

@@ -0,0 +1,134 @@
+[<<back](../../README.md)
+
+# Event: stop
+
+Sometimes it may be necessary to trigger an action when a specific condition occurs; for this, we can use events.
+
+Events are defined with the following structure:
+
+```ruby
+event on: OBJECT, when: CONDITION do
+  ACTION
+end
+```
+
+Where
+* OBJECT can be `:last_target`
+* CONDITION can be `:failed`
+* And ACTION can be `stop`, `scores_to_zero`, or both.
+
+## Example
+
+In this example, we have 4 targets, all of which will function correctly except for target 3.
+
+```ruby
+group "Events: stop" do
+  target "Target 1: ok"
+  run "id root"
+  expect_ok
+
+  target "Target 2: ok"
+  run "id root"
+  expect_ok
+
+  target "Target 3: fail"
+  run "id vader"
+  expect_ok
+
+  event on: :last_target, when: :failed do
+    stop
+  end
+
+  target "Target 4: ok"
+  run "id root"
+  expect_ok
+end
+```
+
+An event is defined to trigger the `stop` action when the last target (target 3) fails.
+
+The "stop" action halts the test, setting the number of targets yet to be evaluated to zero, while the rest retain their current assessment.
+
+## Report output
+
+```
+$ teuton examples/31-event-stop 
+ 
+ 🗹 CASE RESULTS
+┌──────┬──────────┬───────┬───────┐
+│ CASE │ MEMBERS  │ GRADE │ STATE │
+│ 01   │ TOCHANGE │ 50.0  │       │
+└──────┴──────────┴───────┴───────┘
+```
+
+Process:
+* target 1 is Ok.
+* target 2 is Ok.
+* target 3 fails so the `stop` action is triggered.
+* target 4 is not evaluated because test was stopped.
+
+```
+$ cat var/31-event-stop/case-01.txt
+
+ ⚒ CONFIGURATION
+┌────────────────┬────────────────────────────────────┐
+│ tt_config_path │ examples/31-event-stop/config.yaml │
+│ tt_members     │ TOCHANGE                           │
+│ tt_script_path │ examples/31-event-stop/start.rb    │
+│ tt_sequence    │ false                              │
+│ tt_skip        │ false                              │
+└────────────────┴────────────────────────────────────┘
+
+ 🛈 LOGS
+   [16:27:43]  INFO| Event[0] triggered because target[3] failed
+   [16:27:43]  INFO| Test STOPPED!
+
+ ☰ GROUPS
+ ▶ Events: stop
+   ✔ 01 (1.0/1.0)   ┌──
+        Description │ Target 1: ok
+        Command     │ id root
+        Output      │ uid=0(root) gid=0(root) grupos=0(root)
+        Duration    │ 0.002 (local)
+        Alterations │ Read exit code
+        Expected    │ 0
+        Result      │ 0
+   ✔ 02 (1.0/1.0)   ├──
+        Description │ Target 2: ok
+        Command     │ id root
+        Output      │ uid=0(root) gid=0(root) grupos=0(root)
+        Duration    │ 0.001 (local)
+        Alterations │ Read exit code
+        Expected    │ 0
+        Result      │ 0
+   ✖ 03 (0.0/1.0)   ├──
+        Description │ Target 3: fail
+        Command     │ id vader
+        Output      │ id: «vader»: no existe ese usuario
+        Duration    │ 0.002 (local)
+        Alterations │ Read exit code
+        Expected    │ 0
+        Result      │ 1
+   ✖ 04 (0.0/1.0)   ├──
+        Description │ TEST STOPPED!
+        Command     │ 
+        Output      │ 
+        Duration    │ ? (?)
+        Alterations │ 
+        Expected    │ 
+        Result      │ 
+                    └──
+ 🗹 RESULTS
+┌──────────────┬───────────────────────────┐
+│ unique_fault │ 0                         │
+│ case_id      │ 01                        │
+│ start_time   │ 2026-10-30 16:27:43 +0000 │
+│ finish_time  │ 2026-10-30 16:27:43 +0000 │
+│ duration     │ 0.006686742               │
+│ max_weight   │ 4.0                       │
+│ good_weight  │ 2.0                       │
+│ fail_weight  │ 2.0                       │
+│ fail_counter │ 2                         │
+│ grade        │ 50                        │
+└──────────────┴───────────────────────────┘
+```