teuton 2.10.8 → 3.0.0

data/docs/devel/contribute.md

@@ -0,0 +1,52 @@
+[<< back](../../README.md)
+
+# Contributing
+
+List of things to do, classified into 3 sections:
+* (A) I know read and write.
+* (B) I work as IT teacher
+* (C) I want to program using Ruby language
+
+> I write this list without any criteria.
+> Only an unordered list of interesting/usefull things to be done.
+
+## Section A
+
+Documentation
+
+* Revise documentation.
+* Make videos showing how to use this tool
+    * Video about download and install this tool
+    * Test installation scripts
+    * Vídeo with Windows installation.
+    * Video using examples 01 to 05...
+* Write a special documentation for novice
+
+## Section B
+
+* Create your own (simple or complex) teuton tests.
+* Upload your own tests to github.com/teuton-software/challenge repository.
+* Make videos showing how to create our own tests and run it on VMs.
+
+## Section C
+
+Contact with us to help develop this tool.
+
+1. Make sure you have Ruby installed
+1. Fork it and clone it
+1. Create your feature branch (`git checkout -b my-new-feature`)
+1. Commit your changes (`git commit -am 'Add some feature'`)
+1. Push to the branch (`git push origin my-new-feature`)
+1. Create new Pull Request.
+
+> You can also [create issues](https://github.com/teuton-software/teuton/issues) with your requests, incidences or suggestions.
+
+**Development environment installation**
+
+* git clone REPO
+* install ruby-dev or ruby-devel 
+    * debian => sudo apt install ruby-dev build-essential
+    * debian => ssh make gcc ruby-devel
+* gem install bundler
+* bundle install
+* rake

data/docs/devel/todo.md

@@ -0,0 +1,162 @@
+[<< back](../../README.md)
+
+# Roadmap Teuton v3.0.0 - 20260209
+
+**Cambios menores:**
+
+* "Limpiar" las funciones "deprecated"
+* Cambiar "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`
+* Ampliar las estadísticas de salida. 
+    * Improve RESUME report or create stat-report, with stat information.
+    * the worst target/task/case,
+    * the best target/task/case,
+    * the slowest target/task/case,
+    * the fastest target/task/case, etc.
+    * Related targets: group of targets that always have the same state in every case.
+
+**Cambios mayores:**
+
+* Aplicar las recomendaciones del informe de seguridad de Andrés.
+* Crear nueva gema `teuton-panel` (v2) que sustituirá la versión obsoleta actual.
+* Modificar/ampliar las funciones de `teuton config` para facilitar el trabajo a `teuton-panel`.
+    * tt_include
+    * tt_include_params
+    * aplanar/desaplanar config file.
+* Nueva feature "eventos". 
+    * [Propuesta](https://github.com/dvarrui/teuton-book/blob/main/docs/03.eventos/index.md)
+* Nueva gema `teuton-panel`
+* Nuevo repo `teuton-book`: para documentación, tutoriales en español.
+
+**teuton-panel (v2.0.0)**
+
+Consultar en el repostorio `teuton-panel`. EN PROCESO!!!
+
+* config cases IMPORTANTE: 
+    * config/remote: 
+      * accept-remote-config. activar/desactivar configuraciones remotas
+      * Acceptar post formulario y vía get curl con ruta.
+    * config/list: mostrar listado con info de alumnos
+    * Elegir ubicación de almacenamiento de las configuraciones
+* run BAJA PRIORIDAD:
+    * Ejecutar por el profesor
+        * Todos
+        * a una selección
+    * El alumno solicita su propia ejecución vía curl
+    * every: repeticiones en bucle de I iteraciones, cada T tiempo.
+    * Elegir ubicación de almacenamiento de los informes
+    * Al finalizar cada ejecución se muestre un listado con los resultados
+* readme/doc BAJA PRIORIDAD:
+    * activar auto "teuton doc" a página web para los alumnos.
+* config panel:
+    * panel/new: crear fichero de configuración del panel
+    * panel/save: save configuración del panel
+
+---
+
+# TODO list para el FUTURO
+
+## Ideas
+
+Esta es una lista de ideas para que no se me olvide... lo podemos ir ajustando 😊
+
+* **IDEA**. Editor de tests:
+    * Editor de tests ?! .... lo veo complejo... a menos que se empiece por una versión simplificada..
+    * El DSL es tan sencillo que no le veo sentido a un editor de retos.
+    * Pero si podemos aprovechar y crear una" librería " de los módulos más frecuentes?!... una ayuda para facilitar la creación de test... esto se puede emparejar con el editor de test...
+* **SEND**. `send :email_to => :members_emails`... esto requiere que cada caso tenga un email y que además el profesor tenga configurado el acceso a su cuenta de correo... para poder enviar copias de los informes....
+* **HELP**. When students demand help they could recibe some advises. More ideas: bonus, lives, etc.
+* **FEATURE - SAVE STATE**:
+    * Save case state or progress. var/tesname/states.db ¿?
+    * save partial grades. Before play challenge read previous moodle.cvs.
+    * Then play challenge and when creates new moodle.csv... we could preseve old cases(grades) 100% for example.
+    * Create 2 evaluation modes:
+        1. Evaluate targets (current mode): `start eval: :targets`
+        1. Evaluate task: `start eval: :groups` and perhaps add group weight?
+        1. config file with `tt_eval: groups`
+* Propuestas de sdelquin
+    * Docker en vez de vagrant?? → https://www.cloudbees.com/blog/ssh-into-a-docker-container-how-to-execute-your-commands
+    * Tablas "bonitas" en terminal → https://github.com/piotrmurach/tty-markdown#17-table
+    * Documentación en https://readthedocs.org/ ??
+* **DOCUMENTACION**
+    * Snode Dockerfile with SSH server
+    * **PENSAR**: Script to set **static IP**
+* FEATURE: Auto Parse new input format, and detect parse errors
+* **FEATURE - EXPORT**. Sign reports generated with GPG... just to verify autenticity if needed.
+* **ngrok**:
+    * Doc ngrok use. Use cases and tutorial
+    * Doc host1_route combined with ngrok
+* **FEATURE**: Host object so "host(:debian)" return a Host object so
+
+```
+   h = host(:debian)
+   h.ip -> get(:debian_ip)
+   h.username -> get(:debian_username)
+   h.password -> get(:debian_password)
+   h.port
+   h.route
+   h.protocol
+```
+
+* **PENSAR**: Change export to show **command output** into reports.   
+
+## Internal changes
+
+* Implement "scp" over Telnet ¿?
+* Default port values ssh/telnet and default username values (root, Administrator)
+* Use travis
+* `expect_equal "camaleon"`, same as `expect result.equal "camaleon"`.
+* REVISE: verify get(:key) and get('key') works fine!
+* REVISE: Formatter: xml
+* HallOfFame test
+* Rename Laboratory to Checker
+* Unify messages ERROR, INFO, WARN. etc
+* Add tt_label as alias of tt_members
+* **TEST**: actualizar las pruebas con vagrant para la versión actual. Mejora de la calidad del código.
+* **DOCS** PROMOCIONAR.  Documentar y hacer videos. Tener foros de la comunidad o presencia en reddit o stackoverflow.... o algo parecido???
+
+## Docker/podman integration
+
+Host definition example:
+
+```
+  host1_ip:
+  host1_port:
+  host1_username:
+  host1_password:
+
+  host1_docker_image: "debian:latest"
+  host1_docker_name (default value) -> "testname_hostname_case01" as dockername
+  host1_docker_preffix: (Code added to docker name) "idp" -> "idp_hostname_case01"
+
+  host1_docker_vol_rw: "_, _, _"
+  host1_docker_vol_ro: "_, _, _"
+```
+
+* Folders to mount docker volumes
+  Create temp folders for every case/host.
+  but... When create theses folders?
+  (1) While running? This may be done automaticaly at running first step
+      It's easy but temp folders that not exists before running test
+  (2) Before run?    New command as: "teuton create-temp" TESTNAME
+      It's usefull if we need to put files into temp folders (volumes)
+      before running test.
+
+```
+var
+└── test_1
+    └── tmp
+        ├── case01
+        │   ├── host1
+        │   └── host2
+        ├── case02
+        │   ├── host1
+        │   └── host2
+        └── case03
+            ├── host1
+            └── host2
+```

data/docs/dsl/expect.md

@@ -2,7 +2,7 @@
 
 # expect
 
-Compare the obtained result with the expected one. This comparation process is registered into final report.
+Compare the obtained result with the expected one. This result is registered into final report.
 
 ## Example
 
@@ -11,7 +11,7 @@ Let's see some examples:
 ```ruby
 target "Exist user obiwan"
 run "id obiwan"
-expect "obiwan" # Expect run command output will contain "obiwan"
+expect_ok
 ```
 
 ## Simple evaluations
@@ -97,8 +97,10 @@ run    'cat /etc/passwd'
 
 Then we can check result with:
 
-* **expect result.find(/obiwan|kenobi/).count.eq(1)**, expect there exists only 1 line with "obiwan" or "kenobi".
-* **expect result.find(/darth/).find(/vader/).count.gt(2)**, expect there exists more than 2 lines with texts "darth" and "vader".
-* **expect result.not_find('#').find('yoda').count.lt(3)**, expects there exists less than 3 lines with text "yoda" and without "#" symbol.
+```ruby
+expect result.find(/obiwan|kenobi/).count.eq(1)       # only 1 line with "obiwan" or "kenobi".
+expect result.find(/darth/).find(/vader/).count.gt(2) # more than 2 lines with texts "darth" and "vader".
+expect result.not_find('#').find('yoda').count.lt(3)  # less than 3 lines with text "yoda" and without "#" symbol.
+```
 
 Read more about [result](result.md) object.

data/docs/dsl/run.md

@@ -13,83 +13,42 @@ Execute command on localhost and save output into result object.
 run "id COMMAND"
 ```
 
-## Alias
-
-In fact it's the same as doing next:
-
+Alias:
 ```ruby
 run "COMMAND", on: :localhost
-```
-
-```ruby
 run "COMMAND", on: 127.0.0.1
-```
-
-```ruby
 run "COMMAND", on: 'localhost'
 ```
 
-## Example
-
-```ruby
-run "id david"
-```
-
-* This instruction execute "id david" command on local machine, and save results into **result** object.
-* Local machine is where the `Teuton` program is running.
+* This instruction execute "COMMAND" command on local machine, and save results into **result** object.
+* Local machine is where the Teuton program is running.
 
----
 # Remote run
 
 Connect to remote host and executes command. The command output is saved into **result** object.
 
 ```ruby
-run "COMMAND", on: :hostID
-```
-
-* This example connect to remote host identified by `hostID`. Then we execute the command into it and save the output commadn into result object.
-* Label `hostID` identifies specific machine. Host information (ip, username, password, protocol) cames from config file.
-
-## Alias
-
-I know that programers dislike `goto` sentence, but this is diferent. Think of it as english speaker, not as developer.
-
-```ruby
-on :hostID, run: "COMMAND"
-```
-
-```ruby
-goto :hostID, :exec => "COMMAND"
-```
-
-## Examples
-
-Execute `id obiwan` comand into remote host `:linux1`.
-
-```ruby
-run "id obiwan", on: :linux1
+run "COMMAND", on: :HOSTID
 ```
 
-## Deprecated
+* This example connect to remote host identified by `HOSTID`. Then we execute the command into it and save the output commadn into result object.
+* Label `HOSTID` identifies specific machine. Host information (ip, username, password, protocol) cames from config file.
 
+**Example**:
 ```ruby
-run "id obiwan", :on => :linux1
-on :linux1, run: "id obiwan"
-on :linux1, :run => "id obiwan"
-goto :linux1, exec: "id obiwan"
-goto :linux1, :exec => "id obiwan"
+# Execute `id obiwan` comand into remote host `:tatooine`.
+run "id obiwan", on: :tatooine
 ```
 
-## Protocol
+## Protocols
 
-**SSH connection**
+### SSH connection
 
 Invoking `run` sentence, will open SSH session with remote host by default.
-This config files examples do the same:
 
-Sample 1. By default, SSH connection is established with remote host:
+**Example 1**. By default, SSH connection is established with remote host:
 
-```
+```yaml
 ---
 :config:
 ---
@@ -101,9 +60,9 @@ Sample 1. By default, SSH connection is established with remote host:
   :host1_password: secret
 ```
 
-Sample 2. `host1_protocol: ssh` force SSH connection with remote host:
+**Example 2**. `host1_protocol: ssh` force SSH connection with remote host:
 
-```
+```yaml
 ---
 :config:
 ---
@@ -116,11 +75,13 @@ Sample 2. `host1_protocol: ssh` force SSH connection with remote host:
   :host1_protocol: ssh
 ```
 
-**Telnet connection**: Open Telnet remote session.
+### Telnet connection
+
+Open Telnet session with remote host.
 
 `host1_protocol: telnet` force Telnet connection with remote host:
 
-```
+```yaml
 ---
 :global:
 :cases:
@@ -131,23 +92,25 @@ Sample 2. `host1_protocol: ssh` force SSH connection with remote host:
   :host1_protocol: telnet
 ```
 
-**Localhost**: When hostname value is "localhost", or host IP is "127.0.0.X", then
-Teuton will assume that you want to run your command on local system, and no remote session is opened.
-This examples are the same:
+### Localhost
 
+When host is "localhost", or `host_ip: 127.0.0.*` , then Teuton will assume that you want to run your command on local system, and no remote session is opened.
+
+Examples:
 ```
 run "id david"
+run "id david", on: :localhost
+run "id david", on: 'localhost'
 ```
 
-And
+### SSH to localhost
 
-```
-goto :localhost, :exec => "id david"
-```
+Force SSH session to localhost.
 
-**SSH to localhost**: Force SSH session to localhost:
+Iw you need to force SSH connection to localhost, then set param `host1_protocol: ssh`.
 
-```
+Example:
+```yaml
 ---
 :global:
 :cases:

data/docs/install/s-node.md

@@ -1,12 +1,14 @@
-[<< back](README.md)
+[<< back](../../README.md)
 
-# S-NODE installation
+# S-NODE Installation
 
-Install SSH server on every machine with S-NODE role.
+_S-NODE is a host with SSH/Telnet service installed. S-NODE hosts are monitorized by T-NODE host._
 
-**S-node**: Host where SSH server is installed. This hosts are monitorized by T-NODE host.
+S-NODES needs to have the SSH or Telnet service installed.
 
-**GNU/Linux installation**
+## SSH server installation
+
+**SSH GNU/Linux installation**
 
 Run this command as `root` user:
 
@@ -14,7 +16,7 @@ Run this command as `root` user:
 wget -qO- https://raw.githubusercontent.com/teuton-software/teuton/master/install/linux/s-node_install.sh | bash
 ```
 
-**Windows installation**
+**SSH Windows installation**
 
 Requirements:
 * Windows 7+ / Windows Server 2003+
@@ -26,7 +28,7 @@ Run this command on **PowerShell (PS)** as `Administrator` user:
 Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/teuton-software/teuton/master/install/windows/s-node_install.ps1'))
 ```
 
-**Mac OS X installation**
+**SSH Mac OS X installation**
 
 Run this command as `root` user:
 

data/docs/install/t-node.md

@@ -1,20 +1,19 @@
-[<< back](README.md)
+[<< back](../../README.md)
 
 # T-NODE installation
 
-# 1. Recommended
+_T-NODE is a host with Teuton installed. T-NODE monitors one or severals S-NODE hosts._
 
-Installation:
 1. Install Ruby on your system.
 2. `gem install teuton`
 
-Run `teuton version` to check the installed version.
-
 > NOTE:
+> * Show current version: `teuton version`.
+> * Install a specific version: `gem install teuton -v VERSION`. Available versions ([rubygems.org/gems/teuton](https://rubygems.org/gems/teuton/)).
 > * Update: `gem update teuton`.
 > * Uninstall: `gem uninstall teuton`.
 
-# 2. Problems
+## 1. Problems
 
 Sometimes we don't find `teuton` command (OpenSUSE distro, for example), so try this:
 
@@ -26,11 +25,11 @@ Option B:
 * `find /usr/lib64/ruby -name teuton`, to find absolute path to teuton command.
 * `sudo ln -s /PATH/TO/bin/teuton /usr/local/bin/teuton`, to create symbolic link to teuton command.
 
-# 3. Installation scripts
+## 2. Installation scripts
 
 If you don't know how to install Ruby on your system, execute this script to run automatical installation for your OS.
 
-**GNU/Linux installation**
+### 2.1 GNU/Linux installation
 
 Run this command as `root` user:
 
@@ -38,7 +37,7 @@ Run this command as `root` user:
 wget -qO- https://raw.githubusercontent.com/teuton-software/teuton/master/install/linux/t-node_install.sh | bash
 ```
 
-**Windows installation**
+### 2.2 Windows installation
 
 Requirements:
 * Windows 7+ / Windows Server 2003+
@@ -50,7 +49,7 @@ Run this command on **PowerShell (PS)** as `Administrator` user:
 Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/teuton-software/teuton/master/install/windows/t-node_install.ps1'))
 ```
 
-**Mac OS X installation**
+### 2.3 Mac OS X installation
 
 Run this command as admin user (member of `admin` group):
 
@@ -58,11 +57,11 @@ Run this command as admin user (member of `admin` group):
 curl -sL https://raw.githubusercontent.com/teuton-software/teuton/master/install/mac/t-node_install.sh | bash
 ```
 
-# 4. Vagrant and Docker installation
+## 3. Vagrant and Docker installation
 
 Choose this way if you plan to install Teuton into virtual machines or containers, and you are familiar with Vagrant and Docker technologies.
 
-## 4.1 Install using Vagrant
+## 3.1 Install using Vagrant
 
 * First, install `Vagrant` and `VirtualBox` on your host.
 * Create directory for vagrant project. For example, `mkdir teuton-vagrant`.
@@ -70,7 +69,7 @@ Choose this way if you plan to install Teuton into virtual machines or container
 * Choose and download [Vagrantfile](../../install/vagrant).
 * Run `vagrant up` to create your Virtual Machine.
 
-## 4.2 Install using Docker
+## 3.2 Install using Docker
 
 First:
 * Install `docker` on your host.
@@ -79,13 +78,13 @@ Second, choose:
 * Pulling docker image from remote or
 * Rebuild local docker image.
 
-## 4.2 Pulling docker images from remote
+## 3.2 Pulling docker images from remote
 
 Run this command to pull **dvarrui/teuton** image from Docker Hub and create "teuton" container:
 
 `docker run --name teuton -v /home/teuton -i -t dvarrui/teuton /bin/bash`
 
-## 4.2 Rebuild local docker image
+## 3.2 Rebuild local docker image
 
 1. Create Dockerfile like this:
 
@@ -112,7 +111,7 @@ CMD ["/bin/bash"]
 
 > Notice `/home/teuton` folder is persistent volume.
 
-# 5. Source code
+## 4. Source code
 
 If you want to install Teuton by your own, or there are not installation scripts for your OS, and you don't want to use Vagrant then... here you have information how to install all the required packages for Teuton.
 
@@ -132,9 +131,9 @@ Manual installation:
 1. Move into Teuton folder
     * Run `cd teuton`
 1. Gems installation.
-    * `rake install:gems`, to install required gems.
+    * `rake install`, to install required gems.
 1. Only for developers
-    * Run `rake install:debian` or
-    * `rake install:opensuse`, install gem for developers.
+    * Run `rake devel:debian` or
+    * `rake devel:opensuse`, install gem for developers.
 1. Final check
     * `rake`

data/docs/learn/11-export.md

@@ -1,6 +1,6 @@
 [<< back](README.md)
 
-# Export
+# export
 
 [export](../dsl/export.md) keyword generates output reports into diferents formats.
 

data/docs/learn/13-feedback.md

@@ -1,6 +1,6 @@
 [<< back](README.md)
 
-# Feedback
+# feedback
 
 Exporting with false feedback option `export feedback: false`, hide some items from output reports. Hiden items: command, alterations, expected and result.
 

data/docs/learn/14-moodle_id.md

@@ -6,7 +6,7 @@ As a teacher, probably you are using Moodle platform. So, you want to upload the
 
 Teuton generates a file called `moodle.csv` with the grades of each student into CSV format. This file is suitable to import into Moodle platform.
 
-## tt_moodle_id
+## `tt_moodle_id` param
 
 Add a new field called `tt_moodle_id` to each case in "config.yaml". Fill it with the student's Moodle identification. For example, registered email on or ID number on Moodle platform.
 
@@ -21,15 +21,15 @@ cases:
   tt_moodle_id: obiwan@starwars.com
 ```
 
-Now, when after test execution, use "moodle.csv" output file to load students grades and feedback into your Moodle platform.
+After test execution, use "moodle.csv" output file to load students grades and feedback into your Moodle platform.
 
-## tt_moodle_max_score
+## `tt_moodle_max_score` param
 
 By default, teuton evaluates grades from 0 to 100. So grade max score is 100.0 by default. Sometimes teachers configure their moodle tasks with diferents max score, so it is necesary adjust Teuton output grades with Moodle input grades.
 
 We use `tt_moodle_max_score` to customize Moodle max score. So when Teuton export `moodle.csv` values, divides Teuton grades by this value.
 
-Example:
+## Example
 
 ```
 global:

data/docs/learn/15-readme.md

@@ -1,14 +1,16 @@
 [<< back](README.md)
 
-# Example: readme
+# readme
 
 Create README files (with test instructions) from our test definition.
 
-## Definition section
+## Example
 
 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"
 
@@ -26,28 +28,32 @@ end
 
 There exists some `readme` instructions after `group` and `target` lines.
 
-## Execute command
+## Execution
 
 To generate automatically a README file from previous test, execute this:
 
 ```
-teuton readme example/15-readme > example/15-readme/README.md
+$ teuton readme example/15-readme > example/15-readme/README.md
 ```
 
 ## Result
 
-**Let's see the output**: Content of `example/15-readme/README.md` file.
+Content of `example/15-readme/README.md` file.
 
 ---
 
-# 15-readme
+```
+Date   : 2025-11-12 22:11:47 +0000
+Teuton : 2.10.7
+```
+
+# Test: 15-readme
 
 ## Customize readme output
-
 This is our readme example.
 And here we'll see how to use readme keyword
 
 Go to [LOCALHOST](#required-hosts) host, and do next:
-* Create user david.
+* (x1.0) Create user david.
     * Help: you can use 'useradd' command to create users.
     * Remember: Only root is permitted to create new users.