teuton 3.3.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ffb8159388474653ba97b292becba216b9dc0d1361c5669c1c6c3ce8fd5b678
-  data.tar.gz: 7215fb1ca9e5b350c7e46498323bca0f51cc0ad2dfcbfc517ac3f2175183dbbf
+  metadata.gz: c511c3e1920ec1a32a84db7d3eb244c2b3158cc21f45c6f6992b5b6d3d67cd55
+  data.tar.gz: b888a70c354935e13779f2a548e11f0a352c3ac8cc90db2670b53b0b01e57535
 SHA512:
-  metadata.gz: 53b34316e0dc1e8c7a2a8a042ef1694accb3ca89f3e9d193c8471104fd89de00c123f1f6a8ccbd8e2c1335e0446b11f6dcc328e7a6c28da4d7b4f89f26e1245a
-  data.tar.gz: 42fec6d0b1846cfcc73fef79731aa98966220705a76ed81a76ae3f4e9cc01a2eaa4f7e3b97c13a334b7bcf892d1947314b16417927024976623546ca41a88a33
+  metadata.gz: 4e0d923a83e0d8befa87a779e64ca9dfddf46b2e50f36761a51f63563e23983ee8883d92e3df3a29bb6fdfbc4eea9984c113fcb5de97406cd4d5ad168e3c694f
+  data.tar.gz: f4624afd770821f062673edb9736e580738e8c2ee7ca5ef686a58a838ea1aee8055f8ee29c0874147ef015b8c8a5d571e9ff5bc32ae8b74f46bcf6e60533bd49

data/README.md

@@ -1,12 +1,12 @@
 
 # TEUTON
 
-[![Gem Version](https://badge.fury.io/rb/teuton.svg)](https://badge.fury.io/rb/teuton)
+[![Gem Version](https://badge.fury.io/rb/teuton.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/teuton)
 ![GitHub](https://img.shields.io/github/license/dvarrui/teuton)
 
-_Test your infrastructure as code._
+_Test your infrastructure as code._ 
 
-![logo](./docs/images/logo.png)
+![logo](./docs/images/logo-v3-128x128.png)
 
 The infrastructure test is useful for:
 * Sysadmin teachers who want to evaluate students remote machines.
@@ -27,12 +27,12 @@ gem install teuton
 
 ```ruby
 # File: examples/02-target/start.rb 
-group "Learn about targets" do
-  target "Create user obiwan", weight: 2
+group "Practicing targets" do
+  target "Create user obiwan"
   run "id obiwan"
   expect ["uid=", "(obiwan)", "gid="]
 
-  target "Delete user vader"
+  target "Delete user vader", weight: 2
   run "id vader"
   expect_fail
 end
@@ -47,11 +47,6 @@ end
 
 ```console
 $ teutonx examples/02-target 
-------------------------------------
-Started at 2026-10-21 17:05:49 +0100
-F.
-Finished in 0.005 seconds
-------------------------------------
  
  CASE RESULTS
 ┌──────┬───────────┬───────┬───────┐
@@ -89,11 +84,11 @@ Consult the generated [output files](examples/02-target/output.d/)
 2. Teuton commands
     * [teuton config](docs/commands/config.md): suggest config file.
     * [teuton check](docs/commands/check.md): check test syntax.
+    * [teuton doc](docs/commands/doc.md): generate test documentation.
     * [teuton help](docs/commands/help.md): show command help.
     * [teuton new](docs/commands/new.md): create new test.
-    * [teuton readme](docs/commands/readme.md): generate test documentation.
     * [teuton run](docs/commands/run.md): run test.
-3. [Learning guide](docs/learn/README.md). Learn writing your own tests. [Examples](examples).
+3. Learning guide: Learn writing tests. [Examples](examples).
     * [Create NEW test](docs/learn/01-cmd_new.md)
     * [Evaluate TARGET](docs/learn/02-target.md)
     * [Check REMOTE HOSTS](docs/learn/03-remote_hosts.md)
@@ -108,7 +103,7 @@ Consult the generated [output files](examples/02-target/output.d/)
     * [PRESERVE old reports](docs/learn/12-preserve.md)
     * [Hide FEEDBACK from reports](docs/learn/13-feedback.md)
     * [MOODLE](docs/learn/14-moodle_id.md)
-    * [Build README from test](docs/learn/15-readme.md)
+    * [Build DOC from test](docs/learn/15-doc.md)
     * [INCLUDE more configuration files](docs/learn/16-include.md)
     * [ALIAS](docs/learn/17-alias.md)
     * [LOG messages](docs/learn/18-log.md)
@@ -122,10 +117,13 @@ Consult the generated [output files](examples/02-target/output.d/)
     * [EXPECT_SEQUENCE](docs/learn/26-expect_sequence.md)
     * [RUN_SCRIPT](docs/learn/27-run_script.md)
     * [UPLOAD](docs/learn/28-upload.md)
+    * [EVENT stop](docs/learn/31-event-stop.md)
+    * [EVENT scores to zero](docs/learn/32-event-zero.md)
 4. [Configuration file](docs/config_file.md): Reserved params, configure hosts, etc.
 5. [Language reference](docs/dsl/README.md). DSL used to define tests.
     * [expect](docs/dsl/expect.md): check run output with expectations.
     * [export](docs/dsl/export.md): save evaluation reports.
+    * [event](docs/dsl/event.md): execute action when conditions are met.
     * [get](docs/dsl/get.md): read config params.
     * [group](docs/dsl/group.md): group targets.
     * [play](docs/dsl/play.md): starts main execution.

data/docs/commands/README.md

@@ -4,13 +4,14 @@
 
 ```
 $ teuton
+
 Commands:
   teuton [run] [OPTIONS] DIRECTORY  # Run test from directory
   teuton check [OPTIONS] DIRECTORY  # Check test and config file content
   teuton config DIRECTORY           # Suggest configuration.
+  teuton doc DIRECTORY              # Display practice exercise statement
   teuton help [COMMAND]             # Describe available commands or one specific command
   teuton new DIRECTORY              # Create skeleton for a new project
-  teuton readme DIRECTORY           # Show README extracted from test contents
   teuton tree                       # Print a tree of all available commands
   teuton version                    # Show the program version
 ```
@@ -19,7 +20,7 @@ Available command functions:
 1. [run](run.md)
 2. [check](check.md)
 3. [config](config.md)
-4. [help](help.md)
-5. [new](new.md)
-6. [readme](readme.md)
+4. [doc](doc.md)
+5. [help](help.md)
+6. [new](new.md)
 7. **version**: _Show current version_. Usage: `teuton version`.

data/docs/commands/{readme.md → doc.md}

@@ -5,13 +5,11 @@
 _Show test info as README file. Useful for create a readme file for the exercise._
 
 Usage:
-* `teuton readme DIRPATH`
-* `teuton readme DIRPATH > README.md`
+* `teuton doc DIRPATH`
+* `teuton doc DIRPATH > README.md`
 
 This function reads test and config files, and generate Markdown output with guidelines and target descriptions about the exercise.
 
-Alias: `teuton r DIRPATH`, `teuton -r DIRPATH`, `teuton --readme DIRPATH`
-
 ## Example
 
 Test content:
@@ -34,7 +32,7 @@ play do
 end
 ```
 
-Generate test documentation: `teuton readme examples/02-target`
+Generate test documentation: `teuton doc examples/02-target`
 
 ---
 ```

data/docs/commands/help.md

@@ -13,14 +13,14 @@ Alias: `teuton h`,`teuton -h`, `teuton --help`
 **Example**: `teuton help`
 ```
 Commands:
-  teuton [run] [OPTIONS] DIRECTORY   # Run test from directory
-  teuton check [OPTIONS] DIRECTORY   # Check test and config file content
-  teuton config [OPTIONS] DIRECTORY  # Suggest configuration.
-  teuton help [COMMAND]              # Describe available commands or one specific command
-  teuton new DIRECTORY               # Create skeleton for a new project
-  teuton readme DIRECTORY            # Show README extracted from test contents
-  teuton tree                        # Print a tree of all available commands
-  teuton version                     # Show the program version
+  teuton [run] [OPTIONS] DIRECTORY  # Run test from directory
+  teuton check [OPTIONS] DIRECTORY  # Check test and config file content
+  teuton config DIRECTORY           # Suggest configuration.
+  teuton doc DIRECTORY              # Display practice exercise statement
+  teuton help [COMMAND]             # Describe available commands or one specific command
+  teuton new DIRECTORY              # Create skeleton for a new project
+  teuton tree                       # Print a tree of all available commands
+  teuton version                    # Show the program version
 ```
 
 **Example**: `teuton help check`

data/docs/devel/todo.md

@@ -20,11 +20,8 @@
 
 # 3. Features
 
-## 3.1. teuton readme -> teuton doc
+## 3.1. teuton doc
 
-* Renombrar "teuton readme" por "teuton doc".
-    * Modificar código, documentación y los ejemplos
-    * Modificar los ejemplos de dvarrui/teuton-tests
 * Añadir opciones de lenguaje a `teuton doc`.
     * Por defecto se usará `--lang=en`.
     * Pero poder especificar el idioma usando el paráemetro `lang`. Por ejemplo :`teuton doc --lang=es`

data/docs/dsl/README.md

@@ -12,19 +12,20 @@ Types:
 
 ## Keyword table
 
-| DSL                 | Type       | Descripción                       |
-| :------------------ | :--------: | :-------------------------------- |
+| DSL                 | Type       | Descripción                                 |
+| :------------------ | :--------: | :------------------------------------------ |
 | [expect](expect.md) | Definition | Check the obtained result with the expected value. |
 | [export](export.md) | Execution  | Make reports with the results of every evaluation. |
-| [get](get.md)       | Settings   | Read param value from configuration file. |
-| [group](group.md)   | Definition | Define a group of items to check. |
-| [play](play.md)     | Execution  | Run the challenge.                |
+| [event](./event.md) | Definition | Execute action when conditions are met      |
+| [get](get.md)       | Settings   | Read param value from configuration file.   |
+| [group](group.md)   | Definition | Define a group of items to check.           |
+| [play](play.md)     | Execution  | Run the challenge.                          |
 | [result](result.md) | Definition | Contain the output of previous `run` order. |
-| [run](run.md)| Definition | Execute command into remote host or localhost. |
+| [run](run.md)| Definition | Execute command into remote host or localhost.     |
 | [target](target.md) | Definition | Define a target. This is the item to be checked. |
-| [send](send.md)     | Execution  | Send copy of report file to remote host. |
+| [send](send.md)     | Execution  | Send copy of report file to remote host.    |
 | [set](set.md)       | Settings   | Set new param value for running configuration. |
-| [show](show.md)     | Execution  | Show the results on screen.       |
+| [show](show.md)     | Execution  | Show the results on screen.                 |
 
 ### Programming language
 

data/docs/dsl/event.md

@@ -0,0 +1,172 @@
+[<< back](../README.md)
+
+# event
+
+Sometimes it may be necessary to trigger an action when a specific condition occurs; for this, we can use events.
+
+Events are defined using 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
+
+```ruby
+  event on: :last_target, when: :failed do
+    stop
+  end
+```
+
+An event is defined to trigger the `stop` action when the last target 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.
+
+
+# Events
+
+Events are used to define actions that are triggered only when specific conditions are met.
+
+Syntax:
+
+```ruby
+event on: OBJECT, when: CONDITION do ACTIONS end
+```
+
+Events consist of three parts:
+
+* `on: OBJECT` - defines the object for which the event is being set. 
+* `when: CONDITION` - defines the condition that must be met by the OBJECT to trigger the action(s). 
+* `do ACTIONS end` – defines the action(s) to be executed when the event is triggered.
+
+In the initial version, the following are available:
+
+| Type      | Element        | Description                             | Status |
+| --------- | -------------- | --------------------------------------- | ------ |
+| OBJECT    | last_target    | Applies to the last evaluated target    |        |
+| OBJECT    | every_target   | Applies to each individual target       | TODO   |
+| OBJECT    | all_targets    | Applies to all targets collectively     | TODO   |
+| CONDITION | failed         | The object's state is "failed"          |        |
+| CONDITION | passed         | The object's state is "correct"         |        |
+| ACTION    | scores_to_zero | Resets all points earned so far to zero |        |
+| ACTION    | stop           | Stops the test for this case            |        |
+
+## Example 1: "stop" action
+
+Example:
+
+```ruby
+group "Target with an exit condition" do
+  target "User 'root' exists"
+  run "id root"
+  expect_ok
+
+  target "User 'vader' exists", when_fails: :stop
+  run "id vader"
+  expect_ok
+
+  event on: :last_target, when: :failed, do
+    stop
+  end
+
+  target "User 'mail' exists"
+  run "id mail"
+  expect_ok
+end
+```
+
+The test is executed as follows:
+
+* target 1: Evaluated and scored. 
+* target 2: Evaluated and scored. 
+* event:
+    * on: :last_target – based on the result of the last target:
+    * when: :failed
+        * If the result is a failure, the test ends here (for this case).
+        * If the result is successful, the process continues normally with target 3.
+* Upon completion:
+    * The remaining "targets" are left unevaluated. 
+    * The final score is derived from both the evaluated and unevaluated targets.
+
+## Example 2: "grades_to_zero" action
+
+Example:
+
+```ruby
+group "Target with an exit condition" do
+  target "User 'root' exists"
+  run "id root"
+  expect_ok
+
+  target "User 'vader' exists"
+  run "id vader"
+  expect_ok
+
+  event on: :last_target, when: :failed, do
+    scores_to_zero
+  end
+
+  target "User 'mail' exists"
+  run "id mail"
+  expect_ok
+end
+```
+
+This test is executed as follows:
+
+* target 1: Executed and evaluated. 
+* target 2: Executed and evaluated. 
+* event:
+    * on: :last_target — based on the result of the last target:
+    * when: :failed
+        * If the result is a failure, all "targets" evaluated up to that point are set to zero. 
+        * If the result is successful, the process continues normally. 
+* Upon completion:
+    * The remaining unevaluated "targets" are processed. 
+    * The final score is derived from both the evaluated and unevaluated targets.
+
+## Example 3: Combining two actions
+
+Example:
+
+```ruby
+group "Target with an exit condition" do
+  target "User 'root' exists"
+  run "id root"
+  expect_ok
+
+  target "User 'vader' exists"
+  run "id vader"
+  expect_ok
+
+  event on: :last_target, when: :failed, do
+    log "Test stopped due to failure of target 2"
+    scores_to_zero
+    stop
+  end
+
+  target "User 'mail' exists"
+  run "id mail"
+  expect_ok
+end
+```
+
+This test is executed as follows:
+
+* target 1: Executed and evaluated. Target 2: Executed and evaluated. 
+* event
+    * on: :last_target — based on the outcome of the last target, the following actions are taken:
+    * when: :failed
+        * If the result is a failure:
+            * A message is recorded in the report log. 
+            * All targets evaluated up to this point are reset to zero,
+            * and the test is terminated. 
+            * In this case, the final score will be zero. 
+        * If the result is successful, the process continues as normal.

data/docs/learn/01-cmd_new.md

@@ -1,5 +1,5 @@
 
-[<< back](README.md)
+[<<back](../../README.md)
 
 # New test
 

data/docs/learn/02-target.md

@@ -1,4 +1,4 @@
-[<< back](README.md)
+[<<back](../../README.md)
 
 # Target
 
@@ -62,12 +62,12 @@ end
 Execute this command to run the test:
 
 ```
-$ teuton examples/02-target 
+$ teuton examples/02-target       
  
- CASE RESULTS
+ ☰ CASE RESULTS
 ┌──────┬───────────┬───────┬───────┐
 │ CASE │ MEMBERS   │ GRADE │ STATE │
-│ 01   │ anonymous │ 33.0  │ ?     │
+│ 01   │ anonymous │ 67.0  │       │
 └──────┴───────────┴───────┴───────┘
 ```
 
@@ -84,9 +84,9 @@ var
 Let's see one report:
 
 ```
-$ cat var/02-target/case-01.txt
+$ cat var/02-target/case-01.txt 
 
- CONFIGURATION
+ ⚒ CONFIGURATION
 ┌────────────────┬────────────────────────────────┐
 │ tt_config_path │ examples/02-target/config.yaml │
 │ tt_members     │ anonymous                      │
@@ -95,9 +95,9 @@ $ cat var/02-target/case-01.txt
 │ tt_skip        │ false                          │
 └────────────────┴────────────────────────────────┘
 
- GROUPS
- ▶ Learn about targets
-   ✖ 01 (0.0/2.0)   ┌──
+ ☰ GROUPS
+ ▶ Practicing targets
+   ✖ 01 (0.0/1.0)   ┌──
         Description │ Create user obiwan
         Command     │ id obiwan
         Output      │ id: «obiwan»: no existe ese usuario
@@ -105,7 +105,7 @@ $ cat var/02-target/case-01.txt
         Alterations │ find(uid=) & find((obiwan)) & find(gid=) & count
         Expected    │ Greater than 0
         Result      │ 0
-   ✔ 02 (1.0/1.0)   ├──
+   ✔ 02 (2.0/2.0)   ├──
         Description │ Delete user vader
         Command     │ id vader
         Output      │ id: «vader»: no existe ese usuario
@@ -114,17 +114,17 @@ $ cat var/02-target/case-01.txt
         Expected    │ Greater than 0
         Result      │ 1
                     └──
- RESULTS
+ 🗹 RESULTS
 ┌──────────────┬───────────────────────────┐
 │ unique_fault │ 0                         │
 │ case_id      │ 01                        │
-│ start_time   │ 2026-10-21 21:32:24 +0100 │
-│ finish_time  │ 2026-10-21 21:32:24 +0100 │
-│ duration     │ 0.004153712               │
+│ start_time   │ 2026-10-26 12:20:01 +0000 │
+│ finish_time  │ 2026-10-26 12:20:01 +0000 │
+│ duration     │ 0.003806668               │
 │ max_weight   │ 3.0                       │
-│ good_weight  │ 1.0                       │
-│ fail_weight  │ 2.0                       │
+│ good_weight  │ 2.0                       │
+│ fail_weight  │ 1.0                       │
 │ fail_counter │ 1                         │
-│ grade        │ 33                        │
+│ grade        │ 67                        │
 └──────────────┴───────────────────────────┘
-```
+```

data/docs/learn/03-remote_hosts.md

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

data/docs/learn/04-config.md

@@ -1,4 +1,4 @@
-[<< back](README.md)
+[<<back](../../README.md)
 
 # config
 
@@ -7,6 +7,8 @@ Our tests use config file to write dinamic data into separated file.
 By default, `config.yaml` is our config file. Example:
 
 ```yaml
+# File: config.yaml
+# Desc: configuration file
 global:
   tt_output_dir: var/04-config/default
 cases:
@@ -36,8 +38,8 @@ end
 
 ```
 $ teuton examples/04-config 
- 
- CASE RESULTS
+  
+ ☰ CASE RESULTS
 ┌──────┬───────────┬───────┬───────┐
 │ CASE │ MEMBERS   │ GRADE │ STATE │
 │ 01   │ student_1 │ 100.0 │ ✔     │
@@ -60,7 +62,7 @@ Let's see case 01 report.
 ```
 $ cat var/04-config/default/case-01.txt
 
- CONFIGURATION
+ ⚒ CONFIGURATION
 ┌────────────────┬────────────────────────────────┐
 │ tt_config_path │ examples/04-config/config.yaml │
 │ tt_members     │ student_1                      │
@@ -71,24 +73,24 @@ $ cat var/04-config/default/case-01.txt
 │ username       │ david                          │
 └────────────────┴────────────────────────────────┘
 
- GROUPS
+ ☰ GROUPS
  ▶ Reading params from config file
    ✔ 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.004 (local)
+        Duration    │ 0.012 (local)
         Alterations │ find(uid=) & find((david)) & find(gid=) & count
         Expected    │ Greater than 0
         Result      │ 1
                     └──
- RESULTS
+ 🗹 RESULTS
 ┌──────────────┬───────────────────────────┐
 │ unique_fault │ 0                         │
 │ case_id      │ 01                        │
-│ start_time   │ 2026-10-21 21:36:41 +0100 │
-│ finish_time  │ 2026-10-21 21:36:41 +0100 │
-│ duration     │ 0.004390772               │
+│ start_time   │ 2026-10-26 12:22:36 +0000 │
+│ finish_time  │ 2026-10-26 12:22:36 +0000 │
+│ duration     │ 0.012505538               │
 │ max_weight   │ 1.0                       │
 │ good_weight  │ 1.0                       │
 │ fail_weight  │ 0                         │
@@ -110,7 +112,7 @@ Execute the same test but using diferents config files. Config files available:
 ```
 $ teuton examples/04-config         
  
- CASE RESULTS
+ ☰ CASE RESULTS
 ┌──────┬───────────┬───────┬───────┐
 │ CASE │ MEMBERS   │ GRADE │ STATE │
 │ 01   │ student_1 │ 100.0 │ ✔     │
@@ -123,7 +125,7 @@ $ teuton examples/04-config
 ```
 $ teuton run --cname=starwars examples/04-config
  
- CASE RESULTS
+ ☰ CASE RESULTS
 ┌──────┬────────────┬───────┬───────┐
 │ CASE │ MEMBERS    │ GRADE │ STATE │
 │ 01   │ Yoda       │ 0.0   │ ?     │
@@ -136,7 +138,7 @@ $ teuton run --cname=starwars examples/04-config
 ```
 $ teuton run --cpath=examples/04-config/rock.yaml examples/04-config
  
- CASE RESULTS
+ ☰ CASE RESULTS
 ┌──────┬────────────┬───────┬───────┐
 │ CASE │ MEMBERS    │ GRADE │ STATE │
 │ 01   │ AC/DC band │ 0.0   │ ?     │

data/docs/learn/05-use.md

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

data/docs/learn/06-cmd_check.md

@@ -1,9 +1,9 @@
 
-[<< back](README.md)
+[<<back](../../README.md)
 
 # check test
 
-`teuton check DIRPATH` is a command function that checks syntax and show statistics.
+`teuton check DIRPATH` is a command function that checks syntax and show statistics. It is very useful for locating syntax errors in test files.
 
 ## Example
 

data/docs/learn/07-target_weight.md

@@ -1,4 +1,4 @@
-[<< back](README.md)
+[<<back](../../README.md)
 
 # Target weight
 
@@ -24,8 +24,9 @@ group "Using file: network" do
 end
 ```
 
-Output:
 ```
+$ teuton check example/07-target-weight
+...
 ┌────────────────────────────┐
 │ GROUP: Using file: network │
 └────────────────────────────┘
@@ -38,4 +39,5 @@ Output:
       weight      2.0
       run         'host www.google.es' on host1
       expect      www.google.es has address  (String)
+...
 ```

data/docs/learn/08-unique_values.md

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

data/docs/learn/09-send.md

@@ -1,6 +1,6 @@
-[<< back](README.md)
+[<<back](../../README.md)
 
-# Send
+# send
 
 `send` is a keyword used to copy the output report into remote host.