teuton 2.3.6 → 2.3.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a57c245ece6497c75d1132e50cfaa722be5fae7df918ffa8b0af4e109f600cee
-  data.tar.gz: 8159ac8b86278ada1e0fac691d91b37d146cb5c336ec2f4babe729d8150063ae
+  metadata.gz: '0873f32e05d17fdf4c3903594c5e7fa63746afe919b186900ca5e123358ebb08'
+  data.tar.gz: fba17dd71e723d555eeca03a671cb2b171a00b4c874d763325e0dd5921162da4
 SHA512:
-  metadata.gz: 28594d840fe733c4fbc0d28b6d81610ccea3011c5d8713ac279b85280ece74b74f37670125edab21eae0a1f93c740a882784757c81c792a2327336f03c995233
-  data.tar.gz: 7f19810c16c1d3ad78b41de32a2b3a6f85dbff280972b9f6193d5b4ab86f470662357c7a29d2f5ae310246b7b6c3dfec3da95f2aab927c6f10e775bed8e0cb77
+  metadata.gz: e05506134ae1dc7a4a64b0c519221a466c35ac50b15770bde019cae780f940d244ba522f5a8932791c415ab37e0530741c5f9f894320b148be417a62d2a8dced
+  data.tar.gz: 40b76d2fb4de366748e261eb5d8350038ed3bdc7d5d2c2d63c2ce3f81b86886dcd39686c911e75c331c090ddeaadf383136509ed8e3e73b9ff9513265ca0d5f4

data/README.md

@@ -1,7 +1,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/teuton.svg)](https://badge.fury.io/rb/teuton)
 ![GitHub](https://img.shields.io/github/license/dvarrui/teuton)
-![Gem](https://img.shields.io/gem/dv/teuton/2.3.1)
+![Gem](https://img.shields.io/gem/dv/teuton/2.3.7)
 
 # TEUTON
 
@@ -22,8 +22,8 @@ Teuton allow us:
 # Documentation
 
 * [Installation](https://github.com/teuton-software/teuton/tree/master/docs/install/README.md)
-    1. Install Ruby on your system.
-    1. Install Teuton with `gem install teuton`.
+    * Install Ruby on your system.
+    * Install Teuton as normal user: `gem install --user-install teuton` (or install as superuser `gem install teuton`).
 * [Videos, blogs, news](docs/videos.md)
 * [Learning](docs/learn/README.md)
 * [Commands](docs/commands/README.md)
@@ -39,4 +39,3 @@ Teuton allow us:
 # Contact
 
 * **Email**: `teuton.software@protonmail.com`
-* **Twitter**: `@SoftwareTeuton`

data/bin/teuton

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
 
-require 'teuton/cli'
+require "teuton/cli"
 
 CLI.start(ARGV)

data/docs/CHANGELOG.md

@@ -0,0 +1,8 @@
+[<< back](../README.md)
+
+# Changelog
+
+* [version 2.4](changelog/v2.4.md)
+* [version 2.2](changelog/v2.2.md)
+* [version 2.1](changelog/v2.1.md)
+* [version 2.0](changelog/v2.0.md)

data/docs/changelog/v2.4.md

@@ -0,0 +1,16 @@
+
+## [2.4.0]
+
+New features:
+- Add new DSL keyword: expect_last, expect_fisrt
+- New doc and example: learn-15-exit_codes
+- Remove os gem.
+- Change test output colors to green as use others test tools.
+
+Bug fixed:
+- All "expect*" keywords must require 2 arguments. The second is optional.
+
+Revise
+- Remove colors to log text
+- teuton readme: macros, getvars, expect_last, expect_first
+- Formatter: xml, csv, list, etc.

data/docs/dsl/definition/expect.md

@@ -32,13 +32,17 @@ expect 'obiwan' # Expect previous command output contains obiwan text
 
 ## Basic
 
-* **expect 'obiwan'**, expect line/s with "obiwan".
-* **expect ['obiwan', 'kenobi'**, expect line/s with "obiwan" and kenobi".
-* **expect_one 'obiwan'**, expect only one line with "obiwan".
-* **expect_one ['obiwan','kenobi']**, expect only one line with "obiwan" and "kenobi".
-* **expect_none 'obiwan'**, expect no line with "obiwan".
-* **expect_none ['obiwan', 'kenobi']**, expect no line with "obiwan" and "kenobi".
-* **expect /Obiwan|obi-wan/**, Expect line/s with Obiwan or obi-wan. This example uses regular expresions.
+| Command | Description |
+| ------- | ----------- |
+| expect "yoda" or expect_any "yoda" | one or more line/s with "yoda" |
+| expect ["obiwan", "kenobi"] | one or more line/s with "obiwan" and kenobi" |
+| expect_first "episode" | the first line with "episode" |
+| expect_last "episode" | the last line with "episode" |
+| expect_one "rogue" | only one line with "rogue" |
+| expect_one ["obiwan","kenobi"] | only one line with "obiwan" and "kenobi" |
+| expect_none "vader"| no line with "vader" |
+| expect_none ["darth", "vader"] | no line with "darth" and "vader" |
+| expect /Obiwan\|obi-wan/ | one or more line/s with Obiwan or obi-wan. This example uses regular expresions. |
 
 ## Advanced
 

data/docs/dsl/definition/result.md

@@ -68,21 +68,22 @@ result.grep_v("nologin").grep("/bin/bash").count.gt 0
 
 | Function             | VALUE type  | Description                           |
 | -------------------- | ----------- | ------------------------------------- |
+| `result.count`       |             | Count lines from result and save this number into result object. |
+| `result.first` | | Remove all lines except first one.|
 | `result.find(VALUE)` | String      | Filter lines that contains VALUE text |
 |                      | RegExp      | Filter lines that match VALUE regexp. For example `/?ello]`, filter lines with "Hello" or "hello" |
 |                      | Array       | Apply filter to every array element. For example `["Hi","Hello"]`, filter lines with "Hi" or "Hello". |
-| `result.grep(VALUE)` |             | Same as find |
+| `result.grep(VALUE)` | String, RegExp, Array | Same as find |
+| `result.grep_v(VALUE)` | String, RegExp, Array | Same as not_find |
+| `result.last` | | Remove all lines except last one.|
 | `result.not_find(VALUE)` |         | Filter lines that not contains VALUE. VALUE may be String, Regular Expresion or an Array. |
-| `result.grep_v(VALUE)` |           | Same as not_find |
-| `result.count`       |             | Count lines from result and save this number into result object. |
 | `result.restore`     |             | Restore result data. After every filtering action result is modified, but this function restore data to their original state. |
 
 **Information functions:**
 
 | Function             | Description |
 | -------------------- | --------------------------------- |
-| `result.exitstatus`  | Return exit code from the last command executed by run statement |
-| `result.value`       | Return first output line or value |
-| `result.content`     | Return all output lines         |
 | `result.alterations` | Return transformations applied to the output |
+| `result.content`     | Return all output lines         |
 | `result.debug`       | Print the result content on screen. Usefull for debugging process |
+| `result.value`       | Return first output line or value |

data/docs/dsl/definition/run_local.md

@@ -21,7 +21,6 @@ In fact it's the same as doing next:
 
 ```ruby
 run "COMMAND", on: :localhost
-run "COMMAND", :on => :localhost
 ```
 
 ## Example

data/docs/dsl/definition/target.md

@@ -22,7 +22,7 @@ target "Write here your description"
 By default weight is 1.0, but it's posible specified other value:
 
 ```ruby
-target "Write here your description", :weight => 2.5
+target "Write here your description", weight: 2.5
 ```
 
 ## [DEPRECATED] Alias

data/docs/dsl/execution/export.md

@@ -23,7 +23,7 @@ Run test and build reports using `html` output format:
 
 ```ruby
 play do
-  export :format => :html
+  export format: :html
 end
 ```
 
@@ -37,18 +37,16 @@ end
 |    | Command                  | Description |
 | -- | ------------------------ | ----------- |
 | 01 | `export`                 | Export report files using default ouput format |
-| 02 | `export :format => :txt` | Export file using TXT ouput format |
-| 03 | `export :format => :html` | Export file using HTML ouput format |
-| 04 | `export :format => :yaml` | Export file using YAML ouput format |
-| 05 | `export :format => :json` | Export file using JSON ouput format |
-| 06 | `export :format => :colored_text` | Export file using colored TXT ouput format |
-| 07 | `export :preserve => true` | Same as 01 example buy preserving report copies |
-| 08 | `export :format => :html, :preserve => true` | Same as 03 example but preserving report copies |
-| 09 | `export format: :html, preserve: true` | Same as 08 example |
-| 12 | `export format: "txt"` | Same as 02 |
-| 13 | `export format: "html"` | Same as 03 |
-| 14 | `export format: "yaml"` | Same as 04 |
-| 15 | `export format: "json"` | Same as 05 |
-| 16 | `export format: "colored_text"` | Same as 06 |
-| 17 | `export preserve: true` | Same as 07 |
-| 18 | `export format: "html", preserve: true` | Same as 08 |
+| 02 | `export format: :txt` | Export file using TXT ouput format |
+| 03 | `export format: :html` | Export file using HTML ouput format |
+| 04 | `export format: :yaml` | Export file using YAML ouput format |
+| 05 | `export format: :json` | Export file using JSON ouput format |
+| 06 | `export format: :colored_text` | Export file using colored TXT ouput format |
+| 07 | `export preserve: true` | Same as 01 example buy preserving report copies |
+| 08 | `export format: :html, preserve: true` | Same as 03 example but preserving report copies |
+| 09 | `export format: "txt"` | Same as 02 |
+| 10 | `export format: "html"` | Same as 03 |
+| 11 | `export format: "yaml"` | Same as 04 |
+| 12 | `export format: "json"` | Same as 05 |
+| 13 | `export format: "colored_text"` | Same as 06 |
+| 14 | `export format: "html", preserve: true` | Same as 08 |

data/docs/dsl/execution/send.md

@@ -14,7 +14,7 @@
 ```ruby
 start do
   export
-  send :copy_to => :host1
+  send copy_to: :host1
 end
 ```
 

data/docs/dsl/setting/get.md

@@ -37,16 +37,16 @@ Supossing we are **case 01**, then:
 **Writting example**: We also can create new temporal params:
 
 ```ruby
-set(:greet, "Hello")
-var = get(:greet)
+set(:name, "Obiwan")
+var = get(:name)
 ```
 
-So `var` value is "Hello".
+So `var` value is "Obiwan".
 
 **Simpler reading example**: Other ways or reading param values:
 
 ```ruby
-var = greet?
+var = _name
 ```
 
-So `var` value is "Hello" too. `greet?` is an alias of `get(:greet)`.
+So `var` value is "Obiwan" too. `_name` is an alias of `get(:name)`.

data/docs/es/exit_code.md

@@ -0,0 +1,59 @@
+
+# Exit code
+
+## Introducción
+
+Exit code o código de salida es un valor numérico que devuelven los programas cuando terminan su ejecución. Por defecto, el valor 0 indica que el programa/comando ha terminado correctamente. Un valor distinto de cero indica que ha ocurrido alguna situación inesperada o error, y su significado dependerá de cada programa concreto.
+
+En SO GNU/Linux para consultar por terminal este valor hacemos `echo $?`. Veamos dos ejemplos:
+
+* Ejemplo que termina correctamente:
+```
+> id root
+uid=0(root) gid=0(root) grupos=0(root)
+> echo $?
+0
+```
+
+* Ejemplo que termina con error:
+```
+> id vader
+id: «vader»: no existe ese usuario
+> echo $?
+1
+```
+
+## Solicitud de nueva feature
+
+Se nos ha solicitado incorporar en `Teuton` la opción de leer no sólo la salida del comando que se ejecuta con la instrucción `run`, sino también el valor devuelto por el **exit code** del mismo.
+
+De momento no está implementado porque la forma de leer el valor exit code es diferente en cada SO, y `Teuton` (de momento) no tiene capacidad de "adivinar" el SO del host que se está monitorizando/evaluando.
+
+> NOTA: Estamos trabajando en adivinar el SO de host con la nueva herramienta [guess_os](https://rubygems.org/gems/guess_os), pero todavía está un poco "verde".
+
+_¿Cómo solucionamos el problema de leer el exit code en Teuton?_
+
+## Propuesta
+
+De momento hacemos la siguiente propuesta (hay varias formas de afrontarlo) para leer el exit code con `Teuton`.
+
+> NOTA: Para hacerlo todo más sencillo hemos creado dos instrucciones nuevas `expect_last` y `expect_first`.
+
+* Veamos un ejemplo que devuelve 0:
+```ruby
+  target "Exist user root"
+  run "id root;echo $?"
+  expect_last "0"
+```
+* Veamos un ejemplo que devuelve 1:
+```ruby
+  target "Exist user vader"
+  run "id vader;echo $?"
+  expect_last "1"
+```
+
+> https://github.com/teuton-software/teuton/blob/master/docs/learn/example-15-exit_codes.md
+
+## Observaciones
+
+Estos ejemplos se probaron en GNU/Linux pero para que sirvan en Windows, etc, hay que cambiar `echo $?` por su equivalente en cada SO.

data/docs/es/guess_os.md

@@ -0,0 +1,28 @@
+
+# guess_os: Adivinar el sistema operativo
+
+## Situación actual
+
+Cuando usamos `Teuton`, escribimos comandos que se ejecutarán en el host que deseamos monitorizar/evaluar. Estos comandos sabemos cómo escribirlos porque conocemos de antemano el SO de nuestro host.
+
+`Teuton` (de momento) no tiene la capacidad de "adivinar" el SO del host, ni aún conociéndolo, tampoco tiene el conocimiento para saber qué comandos son válidos para cada SO, ni cómo convertir comandos de un SO en otro.
+
+## Propuesta
+
+A pesar de todo, al recibir solicitudes en esta línea nos hemos puesto a trabajar en un módulo para intentar "adivinar" el SO de una máquina local o remota(SSH), y hemos creado [guess_os](https://rubygems.org/gems/guess_os).
+
+Es la primera versión y de momento sólo reconoce correctamente algunos SO/versiones pero no todos. Tiene mucho que mejorar y por este motivo les pedimos un poco de colaboración (sólo te llevará unos minutos).
+
+1. Instalar `guess_os` en tu equipo (`gem install --user-install guess_os`).
+2. Ejecutar el comando `guess_os`.
+3. Pulsar ENTER en la pregunta de IP, para adivinar el SO de la máquina local (localhost).
+    * Si el resultado devuelto coincide con la realidad ¡Estupendo! Ya puedes desintalar la gema si quieres (`gem uninstall guess_os`) o la puedes seguir probando y reportarnos fallos/ideas/mejoras/etc.
+    * Si el resultado devuelto NO coincide con lo que debe salir... entonces envíanos los datos de tu sistema y los que devuelve `guess_os` para ir mejorando esta herramienta.
+
+¡Gracias!
+
+```
+Contacto
+  email    : teuton.software@protonmail.com
+  Telegram : @TeutonSoftware
+```

data/docs/learn/{example-01-target.md → 01-target.md}

@@ -1,8 +1,6 @@
 [<< back](README.md)
 
-# Example: learn-01-target
-
-> This example is on GitHub repository at `examples/learn-01-target/`.
+# Example: 01-target
 
 Let's learn how to create our first target.
 A target is a feature you want to measure or check.

data/docs/learn/{example-02-config.md → 02-config.md}

@@ -1,8 +1,6 @@
 [<< back](README.md)
 
-# Example: learn-02-config
-
-> This example is on GitHub repository at `examples/learn-02-config`.
+# Example: 02-config
 
 * Learn how to use config file.
 * Use params defined into config files.

data/docs/learn/{example-03-remote-hosts.md → 03-remote_hosts.md}

@@ -1,8 +1,6 @@
 [<< back](README.md)
 
-# Example: learn-03-remote-hosts
-
-> This example is on GitHub repository at `examples/learn-03-remote-hosts`.
+# Example: 03-remote-hosts
 
 Summary:
 * Check a group of remote hosts.
@@ -47,7 +45,6 @@ Define 3 targets (items to be checked):
 
 ```ruby
 group "How to test remote Windows hosts" do
-
   target "Update hostname with #{gett(:host1_hostname)}"
   run "hostname", on: :host1
   expect_one get(:host1_hostname)
@@ -59,7 +56,6 @@ group "How to test remote Windows hosts" do
   target "Create user #{gett(:username)}"
   run "net user", on: :host1
   expect get(:username)
-
 end
 ```
 
@@ -71,15 +67,19 @@ end
 play do
   show
   # export using other output formats
-  export :format => :txt
-  export :format => :json
-  send :copy_to => :host1
+  export format: :txt
+  export format: :html
+  send copy_to: :host1
 end
 ```
 
 * `show`, show process log on screen.
-* `export :format => :json`, create output reports into `var/learn-03-remote-host/` directory. We can use diferents format to export: txt, colored_text, json and yaml.
-* `send :copy_to => :host1` keyword copy output report into remote machine (host1).
+* `export format: :txt`, create output reports files into `var/learn-03-remote-host/` directory using `txt` format.
+* `export format: :html`, create output reports into `var/learn-03-remote-host/` directory using `html` format.
+
+> Several output formats available: txt, colored_text, html, json and yaml.
+
+* `send copy_to: :host1` keyword copy output report into remote machine (host1).
 
 ## Results
 

data/docs/learn/{example-04-new-test.md → 04-new_test.md}

@@ -1,9 +1,7 @@
 
 [<< back](README.md)
 
-# Example: learn-04-new-test
-
-> This example is on GitHub repository at `examples/learn-04-new-test`.
+# Example: 04-new_test
 
 Steps:
 1. Create skeleton
@@ -41,12 +39,10 @@ This command will create:
 Write your own targets using the keywords: `target`, `run` and `expect`. Let's see:
 
 ```ruby
-group "Demo group" do
-
-	target "Exist </home/david> directory"
-	run "file /home/david", :on => :host1
-	expect ["/home/david", "directory"]
-
+group "Create new test" do
+  target "Exist </home/vader> directory"
+  run "file /home/vader", on: :host1
+  expect_none "No such file or directory"
 end
 ```
 
@@ -54,12 +50,10 @@ The above example checks if exists '/home/david' directory, into *host1* device.
 
 > Let's see the keywords used:
 >
-> * `target "Exist </home/david> directory"`, Describe the target with our words, so every one could easily understand what we are trying
+> * `target "Exist </home/vader> directory"`, Describe the target with our words, so every one could easily understand what we are trying
 to check.
-> * `run "file /home/david", :on => :host1`, : Execute the command into the remote machine (host1).
-> * `expect ["/home/david", "directory"]`: Compare command ouput with our expectations.
-
----
+> * `run "file /home/vader", on: :host1`, : Execute the command into the remote machine (host1).
+> * `  expect_none "No such file or directory"`: Compare command ouput with our expectations.
 
 ## STEP 3: Personalize Configfile
 
@@ -82,8 +76,6 @@ Use a YAML file (`foo/config.yaml`) or JSON for your own configurations. In this
 
 > The above file configures 2 differents cases with their own params. The script use this information when execute every case.
 
----
-
 ## STEP 4: run the challenge
 
 Now we only have to run the challenge:

data/docs/learn/{example-05-use.md → 05-use.md}

@@ -1,8 +1,6 @@
 [<< back](README.md)
 
-# Example: learn-05-use
-
-> This example is on GitHub repository at `examples/learn-05-use`.
+# Example: 05-use
 
 Learn how to:
 * Organize huge amount of groups/targets into several files.

data/docs/learn/{example-06-debug.md → 06-debug.md}

@@ -1,9 +1,7 @@
 
 [<< back](README.md)
 
-# Example: learn-06-debug
-
-> This example is on GitHub repository at `examples/learn-06-debug`.
+# Example: 06-debug
 
 Learn how to:
 * Check test syntax.

data/docs/learn/{example-07-log.md → 07-log.md}

@@ -1,8 +1,6 @@
 [<< back](README.md)
 
-# Example: learn-07-log
-
-> This example is on GitHub repository at `examples/learn-06-log/`.
+# Example: 07-log
 
 Let's learn how to create log messages.
 

data/docs/learn/{example-08-readme.md → 08-readme.md}

@@ -1,8 +1,6 @@
 [<< back](README.md)
 
-# Example: learn-07-readme
-
-> This example is on GitHub repository at `examples/learn-08-readme/`.
+# Example: 07-readme
 
 Create README files (with test instructions) from our test definition.
 

data/docs/learn/{example-09-preserve.md → 09-preserve.md}

@@ -1,10 +1,10 @@
 [<< back](README.md)
 
-# Example: learn-09-preserve
+# Example: 09-preserve
 
-> This example is on GitHub repository at `examples/learn-09-preserve/`.
+Every time we run teuton test, older output report files are overwritten with new reports. if you want to preserve old versions then use `preserve`.
 
-Older output report files are overwritten with new reports, every time we run teuton test. With `preserve` option we keep copies.
+With `preserve` option we keep older copies.
 
 1. [Execution section](#execution-section)
 2. [Result](#result)
@@ -20,6 +20,7 @@ end
 ```
 
 > More information about [export](../dsl/execution/export.md) keyword.
+
 ## Result
 
 Example, executing `teuton run example/learn-09-preserve` twice:
@@ -31,7 +32,7 @@ var
     │   ├── case-01.txt
     │   ├── moodle.csv
     │   └── resume.txt
-    ├── 20200520-113039
+    ├── 20200519-123039
     │   ├── case-01.txt
     │   ├── moodle.csv
     │   └── resume.txt
@@ -39,3 +40,5 @@ var
     ├── moodle.csv
     └── resume.txt
 ```
+
+* The first time test was launched at 11:30, and second at 12:30 the same day.

data/docs/learn/10-result.md

@@ -0,0 +1,36 @@
+[<< back](README.md)
+
+# Example: 10-result
+
+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.
+
+```ruby
+group "Using result object" do
+  # Capturing hostname value
+  run "hostname"
+  hostname = result.value
+
+  target "No #{hostname} user"
+  run "id hostname"
+  expect_none hostname
+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`.
+
+```
+group "Checking users" do
+  users = ["root", "vader"]
+
+  users.each do |name|
+    target "Exists username #{name}"
+    run "id #{name}"
+    result.debug
+    expect "(#{name})"
+  end
+end
+```
+
+> More information about [result](../dsl/definition/result.md) keyword.

data/docs/learn/11-moodle_id.md

@@ -0,0 +1,19 @@
+[<< back](README.md)
+
+# Example: 11-moodle_id
+
+If you are a teacher and are using the Moodle platform, probably you will want to upload the results of the evaluation carried out by Teuton in Moodle.
+
+Teuton generates a file called "moodle.csv" with the grades of each student. Only have to import the file into Moodle.
+
+In the configuration file "config.yaml" add a field called "moodle_id" to each case. Fill it with the student's identification (For example, the email registered on the Moodle).
+
+Example:
+```
+global:
+cases:
+- tt_members: Darth Vader
+  tt_moodle_id: vader@starwars.com
+- tt_members: Obiwan Kenobi
+  tt_moodle_id: obiwan@starwars.com
+```

data/docs/learn/12-get_vars.md

@@ -0,0 +1,37 @@
+[<< back](README.md)
+
+# Example: 12-get_vars
+
+To read the variables from the configuration file we already have the `get` statement. Example, to read `dirname` we do `get(:dirname)`.
+
+**Example 1:** Using `get` to read vars.
+
+```ruby
+  # "get(:dirname)" reads dirname var from config file
+  target "Exist #{get(:dirname)} directory"
+  run "file #{get(:dirname)}"
+  expect_none "No such file or directory"
+```
+
+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.
+
+```ruby
+  # "_dirname" is equivalet to "get(:dirname)"
+  target "Exist #{_dirname} directory"
+  run "file #{_dirname}"
+  expect_none "No such file or directory"
+```
+
+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.
+
+```ruby
+  # "dirname" is a variable
+  dirname = get(:dirname)
+  target "Exist #{dirname} directory"
+  run "file #{dirname}"
+  expect_none "No such file or directory"
+```