teuton 3.2.1 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3516a5e7aa9c634173b9e5eb7861ff1714ee4e583da4bcad3c01ac8400831313
-  data.tar.gz: c551387224c5c47a545c4455a673d7401495b0a2ef000770010c8d0d3926079d
+  metadata.gz: c511c3e1920ec1a32a84db7d3eb244c2b3158cc21f45c6f6992b5b6d3d67cd55
+  data.tar.gz: b888a70c354935e13779f2a548e11f0a352c3ac8cc90db2670b53b0b01e57535
 SHA512:
-  metadata.gz: 320eb8621ce4b42c2f5316a2b8edb7a8a6ea01abf9fc2e42588df583bd3baa10a22b51b9389d829544a1fae82a84934f6e1c82d98624a6bd263a8cafb5db2678
-  data.tar.gz: 80cc780a54d6b2771904475f5cd89b6954b46c9cf9e04a173cc6dc0e996db13eb3bed7dd2c92b252ae8d58faedb16d1f361d4e151fb26f8baab4f812349086c1
+  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
@@ -46,18 +46,13 @@ end
 **Usage**: Run test with `teuton run TESTPATH`.
 
 ```console
-$ teuton run examples/02-target
-------------------------------------
-Started at 2025-12-01 18:14:44 +0000
-F.
-Finished in 0.005 seconds
-------------------------------------
+$ teutonx examples/02-target 
  
-CASE RESULTS
-+------+-----------+-------+-------+
-| CASE | MEMBERS   | GRADE | STATE |
-| 01   | anonymous | 33.0  | ?     |
-+------+-----------+-------+-------+
+ CASE RESULTS
+┌──────┬───────────┬───────┬───────┐
+│ CASE │ MEMBERS   │ GRADE │ STATE │
+│ 01   │ anonymous │ 33.0  │ ?     │
+└──────┴───────────┴───────┴───────┘
 ```
 
 **Output**: reports saved into `var/TESTNAME` folder.
@@ -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,21 +4,23 @@
 
 ```
 $ teuton
+
 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 or run server
-  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 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
 ```
 
 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/check.md

@@ -27,11 +27,12 @@ Alias: `teuton c foo`, `teuton -c foo`, `teuton --check foo`
 ## Example
 
 ```
-$ teuton check examples/02-target
+$ teuton check examples/02-target 
+
+┌────────────────────────────┐
+│ GROUP: Learn about targets │
+└────────────────────────────┘
 
-+----------------------------+
-| GROUP: Learn about targets |
-+----------------------------+
 (001) target      Create user obiwan
       weight      2.0
       run         'id obiwan' on localhost
@@ -42,17 +43,18 @@ $ teuton check examples/02-target
       run         'id vader' on localhost
       expect_fail
 
-+--------------+-------+
-| DSL Stats    | Count |
-+--------------+-------+
-| Groups       | 1     |
-| Targets      | 2     |
-| Runs         | 2     |
-|  * localhost | 2     |
-+--------------+-------+
-[WARN] Configfile not found
-       .../examples/02-target/config.yaml
-[INFO] Recomended content:
+
+┌──────────────┬───────┐
+│ DSL Stats    │ Count │
+├──────────────┼───────┤
+│ Groups       │ 1     │
+│ Targets      │ 2     │
+│ Runs         │ 2     │
+│  * localhost │ 2     │
+└──────────────┴───────┘
+Warn | Configfile not found
+- File: ../examples/02-target/config.yaml
+Info | Recomended content:
 ---
 global:
 cases:

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,25 +13,35 @@ 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 or run server
-  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 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 config`
+**Example**: `teuton help check`
+
 ```
 Usage:
-  teuton config [OPTIONS] DIRECTORY
+  teuton check [OPTIONS] DIRECTORY
 
 Options:
-  [--server], [--no-server], [--skip-server]  
+  [--onlyconfig], [--no-onlyconfig], [--skip-onlyconfig]  
+  [--color], [--no-color], [--skip-color]                 
+  [--cname=CNAME]                                         
+  [--cpath=CPATH]                                         
 
 Description:
-  config DIRECTORY, "Suggest the content of the configuration file based on the test"
+  (1) teuton check PATH/TO/DIR , Check content of start.rb and config.yaml files.
 
-  config --server DIRECTORY, "Init Config Server. Students connect and help to build config file content"
-```
+  (2) teuton check PATH/TO/DIR --cname=demo , Check content of start.rb and demo.yaml files:
+
+  (3) teuton check PATH/TO/DIR --onlyconfig , Only show config file recomendations
+
+  (4) teuton check PATH/TO/DIR/foo.rb , Check content of foo.rb and foo.yaml files.
+
+  (5) teuton check PATH/TO/DIR/foo.rb --cname=demo , Check content of foo.rb and demo.yaml files.```

data/docs/devel/todo.md

@@ -1,19 +1,16 @@
 [<< back](../../README.md)
 
-# Roadmap Teuton v3.0.0 - 2026
+# Roadmap Teuton v3.3.0 - 2026
 
 # 1. Revisar
 
 * Revisar (tests): result.grep(a).grep(b)
-* "Limpiar" las funciones "deprecated"
 * Aplicar las recomendaciones del informe de seguridad de Andrés.
 * verify get(:key) and get('key') works fine!
 * Formatter: xml
-* Revisar la utilidad de action.assets al generar README.
 
 # 2. Documentacion
 
-* Nuevo repo `teuton-book`: para documentación, tutoriales en español.
 * Documentar y hacer videos. Tener foros de la comunidad o presencia en reddit o stackoverflow.... o algo parecido???
 * Snode Dockerfile with SSH server
 * **ngrok**:
@@ -23,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/dsl/target.md

@@ -17,17 +17,3 @@ By default weight is `1.0`, but it's posible specified other values:
 ```ruby
 target "Write here your description", weight: 2.5
 ```
-
-## [DEPRECATED] Alias
-
-`goal` keyword is an alias of `target`. So it's the same:
-
-```ruby
-target "Write here your description"
-```
-
-or
-
-```ruby
-goal "Write here your description"
-```

data/docs/install/t-node.md

@@ -106,24 +106,13 @@ CMD ["/bin/bash"]
 If you want to install Teuton by your own, or there are not installation scripts for your OS, here you have information how to install all the required packages for Teuton.
 
 Manual installation:
-1. Git installation
-    * Install Git.
-    * Run `git --version` to show current version
-1. Ruby installation
-    * Install ruby.
-    * Run `ruby -v` to show current version (2.1.3p242+)
-1. Rake installation
-    * Run `gem install rake`, then
-    * `rake --version` to show current version (10.4.2+).
-1. Download this project
-    * (a) `git clone https://github.com/dvarrui/teuton.git` or
-    * (b) Download and unzip [file](https://github.com/dvarrui/teuton-panel/archive/master.zip).
-1. Move into Teuton folder
-    * Run `cd teuton`
-1. Gems installation.
-    * `rake install`, to install required gems.
-1. Only for developers
-    * Run `rake devel:debian` or
-    * `rake devel:opensuse`, install gem for developers.
-1. Final check
-    * `rake`
+
+1. Install Git. Run `git --version` to show current version
+1. Install ruby. Run `ruby -v` to show current version (3.2.8)
+1. Install Rake (`gem install rake`), then `rake --version` to show current version (13.4.2).
+1. Clone repo `git clone https://github.com/dvarrui/teuton.git` or download and unzip.
+1. Move into Teuton folder: `cd teuton`
+1. Install gems: `rake install`. 
+1. Only Debian OS: `rake devel:debian`.
+1. Obly OpenSUSE OS: `rake devel:opensuse`.
+1. Final check: `rake`

data/docs/learn/01-cmd_new.md

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