teuton 2.10.8 → 2.11.0

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

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.

data/docs/learn/16-include.md

@@ -2,7 +2,9 @@
 
 # include
 
-Use `tt-include` to include several config files into your main config file.
+Use `tt-include` configuration param to include several config files into your main config file.
+
+## Description
 
 Until now, all the examples we have seen use one configuration file (`config.yaml`) that contain all the parameters required by the test. It is possible to save configuration distributed among several files.
 
@@ -18,9 +20,11 @@ Suppose we have the following file structure.
 └── start.rb
 ```
 
-`config.yaml` will be the main config file. We have defined `tt_include` parameter with a folder wich contains more configuration files.
+`config.yaml` will be the main config file. Then we define `tt_include` parameter with a folder wich contains more configuration files.
+
+In this example the contents of all files into `moreconfigfiles` folder will be included when reading the config parameters:
 
-In this example the contents of all files in `moreconfigfiles` folder will be included when reading the config parameters:
+## Config files
 
 ```yaml
 ---
@@ -30,19 +34,6 @@ In this example the contents of all files in `moreconfigfiles` folder will be in
 :cases:
 ```
 
-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   | ?     |
-+------+---------+-------+-------+
-```
-
 Config files into `moreconfigfiles` folder:
 
 ```yaml
@@ -62,3 +53,17 @@ Config files into `moreconfigfiles` folder:
 :tt_members: file03
 :username: vader
 ```
+
+## Output
+
+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   | ?     |
++------+---------+-------+-------+
+```

data/docs/learn/17-alias.md

@@ -1,10 +1,10 @@
 [<< back](README.md)
 
-# Example: 14-alias
+# alias
 
 By using aliases we can adapt a configuration file, so that it can be used with many different tests.
 
-## Exanation
+## Example
 
 Suppose we have a test like the following:
 

data/docs/learn/18-log.md

@@ -1,10 +1,10 @@
 [<< back](README.md)
 
-# 18-log
+# log
 
-* `log TEXT`, save TEXT into output report.
+`log TEXT`, save TEXT into output report.
 
-Example
+## Example
 
 ```ruby
 group "Learning about log messages" do
@@ -21,6 +21,8 @@ group "Learning about log messages" do
 end
 ```
 
+## Output
+
 Content of `var/18-log/case-01.txt` file.
 
 ```

data/docs/learn/19-read_vars.md

@@ -4,7 +4,9 @@
 
 To get paramm values from the configuration file we already have the `get` statement. Example, to read `dirname` we do `get(:dirname)`.
 
-**Example 1:** Using `get` to get values.
+## Example 1: get
+
+Using `get` to get/read values from config file.
 
 ```ruby
   # "get(:dirname)" reads dirname var from config file
@@ -15,7 +17,9 @@ To get paramm values from the configuration file we already have the `get` state
 
 Since the "get" instruction is frequently used, It is good to have a fast path. Let's see another shorter way to read variables using the "_" operator.
 
-**Example 2:** Using `_` to read vars.
+## Example 2: `_VARNAME` 
+
+Using `_VARNAME` to get/read values from config file.
 
 ```ruby
   # "_dirname" is equivalet to "get(:dirname)"
@@ -26,7 +30,7 @@ Since the "get" instruction is frequently used, It is good to have a fast path.
 
 The Teuton language is a DSL built on top of the Ruby programming language, so we can also use variables like any programming language.
 
-**Example 3:** Using variables.
+## Example 3: Using variables
 
 ```ruby
   # "dirname" is a variable

data/docs/learn/20-macros.md

@@ -4,7 +4,7 @@
 
 Macros is a technique to make it easier to write and reuse code.
 
-**Example**
+## Example
 
 * We start from a set of repeated targets.
 
@@ -22,7 +22,7 @@ run "id david"
 expect_one "david"
 ```
 
-* Define a macro with the repeated block:
+* So we define a macro with the repeated block:
 
 ```ruby
 define_macro "user_exists", :name do
@@ -32,7 +32,7 @@ define_macro "user_exists", :name do
 end
 ```
 
-* Replace the previous targets with macro calls. There are 3 ways to invoke the macro:
+* Then replace the previous targets with macro calls.
 
 ```ruby
 user_exists(name: "fran")
@@ -40,7 +40,9 @@ user_exists(name: "root")
 user_exists(name: "david")
 ```
 
-**Notice**: There are 3 ways to invoke the macro:
+## Invoking macros
+
+There are 3 ways to invoke the macro:
 
 ```ruby
 user_exists(name: "fran")

data/docs/learn/21-exit_codes.md

@@ -2,9 +2,9 @@
 
 # Example: exit_codes
 
-`result` stores information from the last command executed by a "run" action. [Offers many functions](../dsl/definition/result.md)) that transforms output data, and also exitcode is captured.
+`result` stores information from the last command executed by a "run" action. [Offers many functions](../dsl/result.md)) that transforms output data, and also exitcode is captured.
 
-## Example
+## Example 1: ok and fail
 
 ```ruby
   target "Exist user root (exit code ok)"
@@ -16,7 +16,7 @@
   expect_exit 1
 ```
 
-## More examples
+## Example 2: range and array
 
 ```ruby
   target "Using a range"

data/docs/learn/22-result.md

@@ -4,7 +4,9 @@
 
 Sometimes it can be useful to look at the information returned by the "run" command. For this we use the **"result" object**.
 
-**Example 1:**  In this example we run the "hostname" command on the machine and capture its output using "result". We'll use that value to make sure there isn't a user named as host name.
+## Example 1
+
+In this example we run the "hostname" command on the machine and capture its output using "result". We'll use that value to make sure there isn't a user named as host name.
 
 ```ruby
 group "Using result object" do
@@ -18,7 +20,9 @@ group "Using result object" do
 end
 ```
 
-**Example 2:** When we are debugging our test and we want to see the content of the "result" object on the screen, we will use `result.debug`.
+## Example 2
+
+When we are debugging our test and we want to see the content of the "result" object on the screen, we will use `result.debug`.
 
 ```ruby
 group "Checking users" do
@@ -33,4 +37,4 @@ group "Checking users" do
 end
 ```
 
-> More information about [result](../dsl/definition/result.md) keyword.
+> More information about [result](../dsl/result.md) keyword.