teuton 2.4.1 → 2.4.3

data/docs/learn/05-use.md

@@ -1,39 +1,28 @@
 [<< back](README.md)
 
-# Example: 05-use
+# use
 
-Learn how to:
-* Organize huge amount of groups/targets into several files.
-* Checking Windows OS infrastructure (host1).
+`use` keyword allow us organize huge amount of groups/targets into several files.
 
-1. [Tree directory](#tree-directory)
-2. [Execution section](#execution-section)
-3. [Users file](#users-file)
-4. [Network file](#network-file)
+## Example
 
-## Tree directory
-
-This example has more files:
+> This example requires Windows OS on remote machine.
 
 ```bash
-> tree example/04-use
-
-example/04-require
+❯ tree examples/05-use
+examples/05-use
+├── lib
+│   ├── network.rb
+│   └── users.rb
 ├── config.yaml
-├── network.rb
-├── README.md
-├── start.rb
-└── users.rb
+└── start.rb
 ```
 
-## Execution section
-
-Previous `start.rb` file is now splited in: start.rb, users.rb and network.rb.
-
-Let's see current `start.rb` file:
+* `start.rb` file is now splited into: `start.rb`, `users.rb` and `network.rb`.
 
 ```ruby
-use 'users'
+# File: start.rb
+use 'lib/users'
 use 'network'
 
 play do
@@ -42,40 +31,31 @@ play do
 end
 ```
 
-* `use`, indicates external rb file that will be included/imported into main rb file. It's a good idea to organize project files, when the number of groups/targets is high.
-
-## Users file
-
-> Require Windows OS on remote machine.
+* `use`, indicates that we require external file, that will be imported into our start.rb file.
+* Notice that you can specify relative route `use 'lib/users'`, or only filename `use 'network'`. In the second case, teuton will search a file with that name into project folders.
 
-Let's see `users.rb` file
+> It's a good idea to organize project files, when the number of groups/targets is high.
 
 ```ruby
-group "Use file: User configuration" do
+# File: users.rb
 
-  target "Create user #{gett(:username)}"
+group "Using file: users" do
+  target "Create user #{get(:username)}"
   run "net user", on: :host1
   expect get(:username)
-
 end
 ```
 
-## Network file
-
-> Require Windows OS on remote machine.
-
-Let's see `network.rb` file:
-
 ```ruby
-group "Use file: Network configuracion" do
+# File: network.rb
 
-  target "Update computer name with #{gett(:host1_hostname)}"
+group "Using file: network" do
+  target "Update computer name with #{get(:hostname)}"
   run "hostname", on: :host1
-  expect_one get(:host1_hostname)
+  expect_one get(:hostname)
 
   target "Ensure DNS Server is working"
-  run "nslookup www.google.es", on: :host1
-  expect "Nombre:"
-
+  run "host www.google.es", on: :host1
+  expect "www.google.es has address "
 end
 ```

data/docs/learn/06-cmd_check.md

@@ -0,0 +1,50 @@
+
+[<< back](README.md)
+
+# check test
+
+Check Teuton test syntax and show statistics.
+
+```
+❯ teuton check examples/05-use
+
++--------------------------+
+| GROUP: Using file: users |
++--------------------------+
+(001) target      Create user get(username)
+      weight      1.0
+      run         'id get(username)' on host1
+      expect      get(username) (String)
+
++----------------------------+
+| GROUP: Using file: network |
++----------------------------+
+(002) target      Update computer name with get(hostname)
+      weight      1.0
+      run         'hostname' on host1
+      expect_one  get(hostname) (String)
+
+(003) target      Ensure DNS Server is working
+      weight      1.0
+      run         'host www.google.es' on host1
+      expect      www.google.es has address  (String)
+
++-------------+-------+
+| DSL Stats   | Count |
++-------------+-------+
+| Groups      | 2     |
+| Targets     | 3     |
+| Runs        | 3     |
+|  * host1    | 3     |
+| Uniques     | 0     |
+| Logs        | 0     |
+|             |       |
+| Gets        | 5     |
+|  * username | 3     |
+|  * hostname | 2     |
+| Sets        | 0     |
++-------------+-------+
++----------------------+
+| Revising CONFIG file |
++----------------------+
+```

data/docs/learn/07-target_weight.md

@@ -0,0 +1,44 @@
+[<< back](README.md)
+
+# Target weight
+
+* Changing default target weight:
+
+```ruby
+# File: network.rb
+
+group "Using file: network" do
+  target "Update computer name with #{get(:hostname)}"
+  run "hostname", on: :host1
+  expect_one get(:hostname)
+
+  target "Ensure DNS Server is working", weight: 2.0
+  run "host www.google.es", on: :host1
+  expect "www.google.es has address "
+end
+```
+
+```
+❯ teuton check examples/07-target_weight
+
++--------------------------+
+| GROUP: Using file: users |
++--------------------------+
+(001) target      Create user get(username)
+      weight      1.0
+      run         'id get(username)' on host1
+      expect      get(username) (String)
+
++----------------------------+
+| GROUP: Using file: network |
++----------------------------+
+(002) target      Update computer name with get(hostname)
+      weight      1.0
+      run         'hostname' on host1
+      expect_one  get(hostname) (String)
+
+(003) target      Ensure DNS Server is working
+      weight      2.0
+      run         'host www.google.es' on host1
+      expect      www.google.es has address  (String)
+```

data/docs/learn/08-unique_values.md

@@ -0,0 +1,70 @@
+[<< back](README.md)
+
+# Unique value
+
+* `unique NAME, VALUE` keyword defines unique values.
+* All cases that do not comply with this requirement will obtain a score of 0 and it will be reflected in the reports.
+
+Example:
+
+```ruby
+# File: lib/unique.rb
+
+group "Unique value: hostname" do
+  run "hostname -f", on: :host1
+
+  unique "Host name", result.value
+end
+```
+
+Cheking test:
+
+```
+❯ teuton check examples/08-unique_values
+
++--------------------------+
+| GROUP: Using file: users |
++--------------------------+
+(001) target      Create user get(username)
+      weight      1.0
+      run         'id get(username)' on host1
+      expect      get(username) (String)
+
++----------------------------+
+| GROUP: Using file: network |
++----------------------------+
+(002) target      Update computer name with get(hostname)
+      weight      1.0
+      run         'hostname' on host1
+      expect_one  get(hostname) (String)
+
+(003) target      Ensure DNS Server is working
+      weight      2.0
+      run         'host www.google.es' on host1
+      expect      www.google.es has address  (String)
+
++-------------------------------+
+| GROUP: Unique value: hostname |
++-------------------------------+
+      run         'hostname -f' on host1
+    ! Unique      value for <Host name>
+
++-------------+-------+
+| DSL Stats   | Count |
++-------------+-------+
+| Groups      | 3     |
+| Targets     | 3     |
+| Runs        | 4     |
+|  * host1    | 4     |
+| Uniques     | 1     |
+| Logs        | 1     |
+|             |       |
+| Gets        | 5     |
+|  * username | 3     |
+|  * hostname | 2     |
+| Sets        | 0     |
++-------------+-------+
++----------------------+
+| Revising CONFIG file |
++----------------------+
+```

data/docs/learn/09-send.md

@@ -0,0 +1,20 @@
+[<< back](README.md)
+
+# Send
+
+* [export](../dsl/export.md) keyword generate reports into diferents formats:
+* [send](../dsl/send.md) keyword send report copies to every remote host.
+
+## Example
+
+```ruby
+play do
+  show
+  export
+  send copy_to: :host1
+end
+```
+
+* `show`, show process log on screen.
+* `export`, create reports with `txt` format.
+* `send copy_to: :host1`, copy output report into remote machine (host1).

data/docs/learn/10-debug.md

@@ -0,0 +1,45 @@
+[<< back](README.md)
+
+# debug
+
+* Debug your tests.
+
+```
+> tree examples/10-debug
+
+examples/10-debug
+├── config.yaml
+├── external.rb
+├── internal.rb
+└── start.rb
+```
+
+Tests grows and becames huge, with a lot of targets (That isn't a problem). Then, we organize them spliting into several files and invoke `use` keywork from our main rb file to load other files (That's good idea).
+
+Sometimes we need to verify or check rb file consistency and syntax, and we will do it with `teuton check PATH/TO/PROJECT/FOLDER`.
+
+## Debug
+
+Every time we invoke `run` keywork, an OS command is executed. The output is showed on screen and saved into **result** internal object.
+
+We could debug it invoking `result.debug` into our tests. Let's see an example from `external.rb` file:
+
+```ruby
+# File: external.rb
+
+group "Windows: external configuration from localhost" do
+
+  target "From localhost, check if exist connectivity with #{get(:windows_ip)}"
+  run    "ping #{get(:windows_ip)} -c 1"
+  result.debug
+  expect_one "0% packet loss"
+  result.debug
+
+  target "From localhost, check if Netbios-ssn service working on #{get(:windows_ip)}"
+  run    "nmap -Pn #{get(:windows_ip)}"
+  expect "139/tcp", "open"
+
+end
+```
+
+`result.debug` it's usefull when you are verifying command output captured by Teuton.

data/docs/learn/11-export.md

@@ -0,0 +1,35 @@
+[<< back](README.md)
+
+# Export
+
+* [export](../dsl/export.md) keyword generate reports into diferents formats:
+
+Example
+```ruby
+play do
+  show
+  export format: :txt
+  export format: :html
+  export format: :json
+end
+```
+
+* `show`, show process on screen.
+* `export format: :txt`, create reports with `txt` format.
+* `export format: :html`, create reports with `html` format.
+* `export format: :json`, create reports with `json` format.
+
+Firs run `teuton examples/11-export`, then we have:
+
+```
+❯ tree var/11-export
+
+var/11-export
+├── case-01.html
+├── case-01.json
+├── case-01.txt
+├── moodle.csv
+├── resume.html
+├── resume.json
+└── resume.txt
+```

data/docs/learn/{17-hide-feedback.md → 13-feedback.md}

@@ -1,12 +1,22 @@
 [<< back](README.md)
 
-# Example: 17-hide-feedback
+# Feedback
 
-When exporting with `feedback: false` option we hide some items from exported reports. Hiden items: command, alterations, expected and result.
+Exporting with false feedback option `export feedback: false`, hide some items from output reports. Hiden items: command, alterations, expected and result.
 
 > More information about [export](../dsl/execution/export.md) keyword.
 
-## Explanation
+Example
+
+```ruby
+play do
+  show
+  export feedback: false
+  export format: "html", feedback: false
+end
+```
+
+## Description
 
 Every time teuton is run, all cases are evaluated and when exporting the results, by default, all the information collected during the evaluation process is logged.
 
@@ -20,33 +30,20 @@ Each "target" contains the following fields:
 Some of these fields should always be visible, such as: id, description, check, score, and weight. And others, more related to the process that perform teuton for verification can be hidden using the "feedback: false" parameter.
 
 With "feedback: false" the fields are hidden: command, alterations, expected and result.
-Más información sobre este texto de origen
-Para obtener más información sobre la traducción, se necesita el texto de origen
-Enviar comentarios
-Paneles laterales
 
-## Execution section
-
-Take a look at our test execution section (Play):
-```ruby
-play do
-  show
-  export feedback: false
-end
-```
 
-## Result
+## Results
 
-Executing `teuton run example/17-hide-feedback`:
+Executing `teuton run examples/13-feedback`, we get this output:
 
 ```
 GROUPS
-- Hide feedback from reports
+- Preserve output reports
     01 (1.0/1.0)
-        Description : Exits user root
-        Command     : *******
+        Description : Exits user david
+        Command     : ********
         Duration    : 0.002 (local)
-        Alterations : ******************
+        Alterations : *******************
         Expected    : ************** (String)
-        Result      : * (Integer)
+        Result      : ******** (String)
 ```

data/docs/learn/14-moodle_id.md

@@ -0,0 +1,24 @@
+[<< back](README.md)
+
+# Moodle
+
+As a teacher, probably you are using Moodle platform. So, you want to upload the results of the evaluation carried out by Teuton into Moodle.
+
+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
+
+Add a new field called `tt_moodle_id` to each case in "config.yaml". Fill it with the student's identification (For example, the email registered on the Moodle, or ID number, etc.).
+
+Example:
+
+```
+global:
+cases:
+- tt_members: Darth Vader
+  tt_moodle_id: vader@starwars.com
+- tt_members: Obiwan Kenobi
+  tt_moodle_id: obiwan@starwars.com
+```
+
+Now, when running test "moodle.csv" will be generated with all student grades.

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

@@ -4,10 +4,6 @@
 
 Create README files (with test instructions) from our test definition.
 
-1. [Definition section](#definition-section)
-2. [Execute command](#execute-command)
-3. [Result](#result)
-
 ## Definition section
 
 Take a look at our test definition section (Group):
@@ -35,23 +31,23 @@ There exists some `readme` instructions after `group` and `target` lines.
 To generate automatically a README file from previous test, execute this:
 
 ```
-teuton readme example/08-readme > example/08-readme/README.md
+teuton readme example/15-readme > example/15-readme/README.md
 ```
 
 ## Result
 
-**Let's see the output**: Content of `example/08-readme/README.md` file.
+**Let's see the output**: Content of `example/15-readme/README.md` file.
 
 ---
-# 08-readme
+
+# 15-readme
 
 ## Customize readme output
 
-This is our README example.
+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.
     * Help: you can use 'useradd' command to create users.
     * Remember: Only root is permitted to create new users.
----

data/docs/learn/{13-include.md → 16-include.md}

@@ -1,11 +1,9 @@
 [<< back](README.md)
 
-# Example: 13-include
+# include
 
 Use `tt-include` to include several config files into your main config file.
 
-## Explanation
-
 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.
 
 Suppose we have the following file structure.

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

@@ -1,33 +1,27 @@
 [<< back](README.md)
 
-# Example: 07-log
+# 18-log
 
-Let's learn how to create log messages.
+* `log TEXT`, save TEXT into output report.
 
-1. [Definition section](#definition-section)
-2. [Run test](#execution-section)
-3. [Result](#result)
+Example
 
-## Definition section
-
-Test definition section (Group):
 ```ruby
 group "Learning about log messages" do
-  log 'Using log messages...'
+  log "Using log messages."
 
   target "Create user david"
-  run    "id david"
+  run "id david"
+  log result.value
   expect "david"
 
-  log 'Problem detected!', :error
+  log "Problem detected!", :error
+  log "This is a warning", :warn
+  log "Hi, there!", :info
 end
 ```
 
-> In this example, localhost's OS must be GNU/Linux (any other compatible OS) because the command used is `id david`.
-
-## Result
-
-**Let's see example**: Content of `var/07-log/case-01.txt` file.
+Content of `var/18-log/case-01.txt` file.
 
 ```
 CONFIGURATION
@@ -35,12 +29,15 @@ CONFIGURATION
 | tt_members  | anonymous |
 | tt_sequence | false     |
 | tt_skip     | false     |
-| tt_testname | 07-log    |
+| tt_testname | 18-log    |
 +-------------+-----------+
 
 LOGS
-    [13:45:02] : Using log messages...
-    [13:45:02] ERROR: Problem detected!
+    [09:14:22]  INFO: Using log messages.
+    [09:14:22]  INFO: uid=1000(david) gid=1000(david) grupos=495(cdrom),493(disk),487(video),474(wheel),464(wireshark),459(docker),456(vboxusers),1000(david)
+    [09:14:22] ERROR: Problem detected!
+    [09:14:22] WARN!: This is a warning
+    [09:14:22]  INFO: Hi, there!
 
 GROUPS
 - Learning about log messages
@@ -55,9 +52,9 @@ GROUPS
 RESULTS
 +--------------+---------------------------+
 | case_id      | 01                        |
-| start_time   | 2022-12-24 13:45:02 +0000 |
-| finish_time  | 2022-12-24 13:45:02 +0000 |
-| duration     | 0.001900685               |
+| start_time   | 2023-01-26 09:14:22 +0000 |
+| finish_time  | 2023-01-26 09:14:22 +0000 |
+| duration     | 0.002012326               |
 | unique_fault | 0                         |
 | max_weight   | 1.0                       |
 | good_weight  | 1.0                       |
@@ -65,4 +62,3 @@ RESULTS
 | fail_counter | 0                         |
 | grade        | 100                       |
 +--------------+---------------------------+
-```

data/docs/learn/{12-get_vars.md → 19-read_vars.md}

@@ -1,10 +1,10 @@
 [<< back](README.md)
 
-# Example: 12-get_vars
+# Read vars
 
-To read the variables from the configuration file we already have the `get` statement. Example, to read `dirname` we do `get(:dirname)`.
+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 read vars.
+**Example 1:** Using `get` to get values.
 
 ```ruby
   # "get(:dirname)" reads dirname var from config file

data/docs/learn/20-macros.md

@@ -0,0 +1,49 @@
+[<< back](README.md)
+
+# Macros
+
+Macros is a technique to make it easier to write and reuse code.
+
+**Example**
+
+* We start from a set of repeated targets.
+
+```ruby
+target "Exist user fran"
+run "id fran"
+expect_one "root"
+
+target "Exist user root"
+run "id root"
+expect_one "root"
+
+target "Exist user david"
+run "id david"
+expect_one "david"
+```
+
+* Define a macro with the repeated block:
+
+```ruby
+define_macro "user_exists", :name do
+  target "Exist user #{get(:name)}"
+  run "id #{get(:name)}"
+  expect_one get(:name)
+end
+```
+
+* Replace the previous targets with macro calls. There are 3 ways to invoke the macro:
+
+```ruby
+user_exists(name: "fran")
+user_exists(name: "root")
+user_exists(name: "david")
+```
+
+**Notice**: There are 3 ways to invoke the macro:
+
+```ruby
+user_exists(name: "fran")
+macro "user_exists", name: "fran"
+macro_user_exists(name: "fran")
+```