teuton 2.4.0 → 2.4.2

data/docs/learn/03-remote_hosts.md

@@ -1,121 +1,93 @@
 [<< back](README.md)
 
-# Example: 03-remote-hosts
+# Remote hosts
 
-Summary:
-* Check a group of remote hosts.
-* Export reports using other output formats.
-* Checking remote machine (host1) with Windows OS.
+To run test on remote host we have to define them into config file.
 
-1. [Config file](#config-file)
-2. [Definition section](#definition-section).
-3. [Execution section](#execution-section).
-4. [Results](#results).
-
-## Config file
-
-This configuration file contains:
-* 2 global params denitions.
-* 3 cases.
-* 4 specific case params definitions.
+Let's see an example with:
+* 1 global param.
+* 3 cases with 3 params.
 
 ```yaml
 ---
 global:
   host1_username: root
-  host1_password: profesor
 cases:
-- tt_members: Darth Maul
+- tt_members: student_1
   host1_ip: 192.168.1.201
-  host1_hostname: siths
-  username: maul
-- tt_members: R2D2
+  host1_password: secret_1
+- tt_members: student_2
   host1_ip: 192.168.1.202
-  host1_hostname: robots
-  username: r2d2
-- tt_members: Obiwan Kenobi
-  host1_ip: 192.168.1.203
-  host1_hostname: jedis
-  username: obiwan
+  host1_password: secret_2
+- tt_members: student_3
+  host1_ip: 127.0.0.1
+  host1_password: secret_3
 ```
 
-## Definition section
-
-Define 3 targets (items to be checked):
+Every remote host definition require some params:
 
-```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)
-
-  target "Ensure network DNS configuration is working"
-  run "nslookup www.google.es", on: :host1
-  expect "Nombre:"
-
-  target "Create user #{gett(:username)}"
-  run "net user", on: :host1
-  expect get(:username)
-end
-```
+| Param | Description    | Default value |
+| ----- | -------------- | ------------- |
+| ip    | Remote host IP | |
+| port  | Remote host port | 22 |
+| username | Remote user account | Not required with public SSH id |
+| password | Remote user pasword | Not required with public SSH id |
+| protocol | SSH or Telner | SSH |
+| route | Defines host2 used as gateway to reach host | |
 
-> NOTE: This example requires Windows OS on remote machine (host1).
+## Definition section
 
-## Execution section
+Define 1 target (item to be checked):
 
 ```ruby
-play do
-  show
-  # export using other output formats
-  export format: :txt
-  export format: :html
-  send copy_to: :host1
+group "Remote hosts" do
+  target "Create user david"
+  run "id david", on: :host1
+  expect "david"
 end
 ```
 
-* `show`, show process log on screen.
-* `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).
+> NOTE: This example requires GNU/Linux OS on remote machine (host1).
 
-## Screen output
+Execution:
 
 ```
+> teuton run examples/03-remote_hosts
+
 CASE RESULTS
-+------+---------------+-------+-------+
-| CASE | MEMBERS       | GRADE | STATE |
-| 01   | Darth Maul    | 0.0   | ?     |
-| -    | -             | 0.0   |       |
-| 03   | Obiwan Kenobi | 0.0   | ?     |
-+------+---------------+-------+-------+
++------+-----------+-------+-------+
+| CASE | MEMBERS   | GRADE | STATE |
+| 01   | student_1 | 0.0   | ?     |
+| 02   | student_2 | 0.0   | ?     |
+| 03   | student_3 | 100.0 | ✔     |
++------+-----------+-------+-------+
 
 CONN ERRORS
-+------+---------------+-------+------------------+
-| CASE | MEMBERS       | HOST  | ERROR            |
-| 01   | Darth Maul    | host1 | host_unreachable |
-| 03   | Obiwan Kenobi | host1 | host_unreachable |
-+------+---------------+-------+------------------+
++------+-----------+-------+------------------+
+| CASE | MEMBERS   | HOST  | ERROR            |
+| 01   | student_1 | host1 | host_unreachable |
+| 02   | student_2 | host1 | host_unreachable |
++------+-----------+-------+------------------+
 ```
 
-## Results
+Notice that case-03 is 100% and conection works. It is running on localhost because has localhost IP (127.0.0.1)
+
+Results:
 
 ```
-var
-└── 03-remote-hosts
-    ├── case-01.json
-    ├── case-01.txt
-    ├── case-03.json
-    ├── case-03.txt
-    ├── moodle.csv
-    ├── resume.json
-    └── resume.txt
+❯ tree var/03-remote_hosts
+
+var/03-remote_hosts
+├── case-01.txt
+├── case-02.txt
+├── case-03.txt
+├── moodle.csv
+└── resume.txt
 ```
 
-* `case-01`, report with details about case 01 (maul)
-* Case 02 (r2ds) is skipped. So there are no report `case-02`.
-* `case-03`, report with details about case 03 (obiwan)
-* `resume`, report with global resumed information about all cases.
-* `moodle.csv`, CVS file with required fields to upload grades into Moodle eLearning platform.
+## tt_skip param
+
+To disable a case, add skip param `tt_skip: true`.
+* `tt_skip` it is true by default.
+* `tt_skip: false` ignore this case.
+* `tt_skip: true`, evaluate this case.

data/docs/learn/04-config.md

@@ -0,0 +1,147 @@
+[<< back](README.md)
+
+# config
+
+_It's good idea save dinamic data into config file._
+
+By default, `config.yaml` is our config file. Example:
+
+```yaml
+global:
+cases:
+- tt_members: name_student_1
+  username: david
+- tt_members: name_student_2
+  username: fran
+```
+
+> **How to choose another config file?** Read this [document](../commands/example_run.md#3-choosing-config-file).
+
+By default, `start.rb` it's our main execution file. Example:
+
+```ruby
+group "Reading params from config file" do
+
+  target "Create user #{get(:username)}"
+  run "id #{get(:username)}"
+  expect get(:username)
+
+end
+```
+
+* [get](../dsl/get.md) keyword read params from configuration file. It's posible personalize tests with diferent values for every case.
+
+## Example
+
+```console
+> teuton run examples/04-config
+
+CASE RESULTS
++------+----------------+-------+-------+
+| CASE | MEMBERS        | GRADE | STATE |
+| 01   | name_student_1 | 100.0 | ✔     |
+| 02   | name_student_2 | 0.0   | ?     |
++------+----------------+-------+-------+
+```
+
+Reports:
+
+```
+var/04-config
+├── case-01.txt
+├── case-02.txt
+├── moodle.csv
+└── resume.txt
+```
+
+Let's see case 01 report.
+
+```
+> more var/04-config/case-01.txt
+
+CONFIGURATION
++-------------+----------------+
+| tt_members  | name_student_1 |
+| tt_sequence | false          |
+| tt_skip     | false          |
+| tt_testname | 04-config      |
+| username    | david          |
++-------------+----------------+
+
+GROUPS
+- Reading params from config file
+    01 (1.0/1.0)
+        Description : Create user david
+        Command     : id david
+        Duration    : 0.002 (local)
+        Alterations : find(david) & count
+        Expected    : Greater than 0 (String)
+        Result      : 1 (Integer)
+
+RESULTS
++--------------+---------------------------+
+| case_id      | 01                        |
+| start_time   | 2023-01-25 20:46:13 +0000 |
+| finish_time  | 2023-01-25 20:46:13 +0000 |
+| duration     | 0.001778546               |
+| unique_fault | 0                         |
+| max_weight   | 1.0                       |
+| good_weight  | 1.0                       |
+| fail_weight  | 0.0                       |
+| fail_counter | 0                         |
+| grade        | 100                       |
++--------------+---------------------------+```
+```
+
+## Using differents configuration files
+
+Example with 3 config files (yaml files):
+
+```
+❯ tree examples/04-config
+
+examples/04-config
+├── config.yaml
+├── rock.yaml
+├── start.rb
+└── starwars.yaml
+```
+
+Usign default config file (`config.yaml`):
+
+```
+❯ teuton run examples/04-config
+
+CASE RESULTS
++------+----------------+-------+-------+
+| CASE | MEMBERS        | GRADE | STATE |
+| 01   | name_student_1 | 100.0 | ✔     |
+| 02   | name_student_2 | 0.0   | ?     |
++------+----------------+-------+-------+
+```
+
+Using `example/04-config/starwars.yaml`:
+
+```
+❯ teuton run --cname=starwars examples/04-config
+
+CASE RESULTS
++------+------------+-------+-------+
+| CASE | MEMBERS    | GRADE | STATE |
+| 01   | Yoda       | 0.0   | ?     |
+| 02   | Darth Maul | 0.0   | ?     |
++------+------------+-------+-------+
+```
+
+Using `example/04-config/rock.yaml`:
+
+```
+❯ teuton run --cpath=examples/04-config/rock.yaml examples/04-config
+
+CASE RESULTS
++------+------------+-------+-------+
+| CASE | MEMBERS    | GRADE | STATE |
+| 01   | AC/DC band | 0.0   | ?     |
+| 02   | Muse band  | 0.0   | ?     |
++------+------------+-------+-------+
+```

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.