teuton 2.1.8 → 2.1.9

data/docs/learn/README.md

@@ -1,26 +1,33 @@
 
 [<< back](../../README.md)
 
+1. [Learning](#learning)
+2. [Examples](#examples)
+3. [Videos](#videos)
+
 # Learning
 
-Learn how to write your own tests reading examples.
-- [Quick demo](quick-demo.md)
+Learn how to use Teuton language to write your own tests:
 - [Example 01 - Target](example-01-target.md)
-- [Example 02 - Config file](example-02-configfile.md)
+- [Example 02 - Config file](example-02-config.md)
 - [Example 03 - Remote hosts](example-03-remote-hosts.md)
 - [Example 04 - Use](example-04-use.md)
 - [Example 05 - Debug](example-05-debug.md)
+- [Example 06 - Log](example-06-log.md)
+- Example 07 - Preserve
+- Example 08 - Readme
+- Example 09 - Macros
+- Example 10 - Alias
 - [Example 11 - Create your first test](example-11-first-test.md)
 - [Videos](videos.md)
 
----
-# More examples
+# Examples
 
+More examples
 * Let's see examples at [teuton-challenges](https://github.com/teuton-software/teuton-challenges) GitHub repository.
 * Ask us by email at `teuton.software@protonmail.com` or Twitter at `@SoftwareTeuton`.
 * [CHAPI19 - Spanish Teuton demo](https://github.com/dvarrui/proyectos-de-ejemplo/tree/master/charlas/teuton)
 
----
 # Videos
 
 By now there are no English videos. We are sorry!

data/docs/learn/example-01-target.md

@@ -1,5 +1,10 @@
 [<< back](README.md)
 
+1. [Definition section](#definition-section)
+2. [Execution section](#execution-section)
+3. [Run test](#run-test)
+4. [Output reports](#output-reports)
+
 # Example: learn-01-target
 
 Let's learn how to create our first target.
@@ -7,26 +12,29 @@ A target is a feature you want to measure or check.
 
 > This example is on GitHub repository at `examples/learn-01-target/`.
 
-## Definitions (Group section)
+## Definition section
 
+Test definition section (Group):
 ```ruby
-group "learn-01-target" do
+group "Learn about targets" do
 
-  target "Exist <david> user"
+  target "Create user david"
   run "id david"
   expect "david"
 
 end
 ```
 
-We define targets using these words:
-* **target**: Description of the goal to be tested.
-* **run**: Execute a command `id david` on localhost machine.
-* **expect**: Evaluate if the result contains expected value.
+Define targets using these lines:
+* **target**: Description of the element to be tested.
+* **run**: Execute a command `id david` on localhost.
+* **expect**: Ensure the result contains expected value.
 
 > In this example, localhost's OS must be GNU/Linux (any other compatible OS) because the command used is `id david`.
 
-## Main execution block (Play section)
+## Execution section
+
+Test execution section (Play):
 
 ```ruby
 play do
@@ -35,81 +43,90 @@ play do
 end
 ```
 
-Runing this example:
+DSL keywords:
+* **show**: display process information on screen.
+* **export**: build output reports.
+
+## Run test
+
+**Let's see example**: Executing ` teuton run examples/learn-01-target` command.
 
 ```bash
- $ teuton learn/learn-01-target
-[INFO] ScriptPath => /home/david/proy/repos/teuton.d/challenges/learn/learn-01-target/start.rb
-[INFO] ConfigPath => /home/david/proy/repos/teuton.d/challenges/learn/learn-01-target/config.yaml
+[INFO] ScriptPath => examples/learn-01-target/start.rb
+[INFO] ConfigPath => examples/learn-01-target/config.yaml
+[INFO] Pwd        => /mnt/home/leap/proy/repos/teuton.d/teuton
 [INFO] TestName   => learn-01-target
+
 ==================================
-Executing [teuton] (version 2.0.0)
-[INFO] Running in parallel (2019-06-20 01:37:57 +0100)
+Executing [teuton] (version 2.1.9)
+[INFO] Running in parallel (2020-04-18 21:32:16 +0100)
 .
-[INFO] Duration = 0.013580866 (2019-06-20 01:37:58 +0100)
-
-
+[INFO] Duration = 0.003    (2020-04-18 21:32:16 +0100)
 ==================================
+
 INITIAL CONFIGURATIONS
-+---------------+------------------------------------------------------------------------------+
-| tt_title      | Executing [teuton] (version 2.0.0)                                           |
-| tt_scriptname | /home/david/proy/repos/teuton.d/challenges/learn/learn-01-target/start.rb    |
-| tt_configfile | /home/david/proy/repos/teuton.d/challenges/learn/learn-01-target/config.yaml |
-| tt_testname   | learn-01-target                                                              |
-| tt_sequence   | false                                                                        |
-+---------------+------------------------------------------------------------------------------+
++---------------+-------------------------------------------+
+| tt_title      | Executing [teuton] (version 2.1.9)        |
+| tt_scriptname | examples/learn-01-target/start.rb         |
+| tt_configfile | examples/learn-01-target/config.yaml      |
+| tt_pwd        | /mnt/home/leap/proy/repos/teuton.d/teuton |
+| tt_testname   | learn-01-target                           |
+| tt_sequence   | false                                     |
++---------------+-------------------------------------------+
+
 CASE RESULTS
-+---------+-------------+-----------+
-| Case ID | % Completed | Members   |
-| Case_01 | 100%        | anonymous |
-+---------+-------------+-----------+
++------+-----------+-------+-------+
+| CASE | MEMBERS   | GRADE | STATE |
+| 01   | anonymous | 100.0 |       |
++------+-----------+-------+-------+
+
 FINAL VALUES
 +-------------+---------------------------+
-| start_time  | 2019-06-20 01:37:57 +0100 |
-| finish_time | 2019-06-20 01:37:58 +0100 |
-| duration    | 0.013580866               |
+| start_time  | 2020-04-18 21:32:16 +0100 |
+| finish_time | 2020-04-18 21:32:16 +0100 |
+| duration    | 0.003310235               |
 +-------------+---------------------------+
 ```
 
-## Results
+## Output reports
 
-Output reports are saved into `var/learn-01-target/` directory.
+**Output directory**: reports created into `var/learn-01-target/` output directory.
 
 ```bash
-var/learn-01-targets
-├── case-01.txt
-└── resume.txt
+var
+└── learn-01-target
+    ├── case-01.txt
+    ├── moodle.csv
+    └── resume.txt
 ```
 
-Let's see `export` keyword output.
+**Let's see example**: Executing `more var/learn-01-target/case-01.txt` command.
 
 ```bash
-$ more var/learn-01-target/case-01.txt
-
-CONFIGURATIONS
-+------------+-----------+
-| tt_members | anonymous |
-| tt_skip    | false     |
-+------------+-----------+
-
-TEST
-======================
-
-GROUP: learn-01-target
-
-  01 (1.0/1.0)
-  		Description : Exist <david> user
-  		Command     : id david
-  		Duration    : 0.004 (local)
-  		Alterations : find(david) & count
-  		Expected    : Greater than 0 (String)
-  		Result      : 1 (Integer)
+CONFIGURATION
++-------------+-----------------+
+| tt_members  | anonymous       |
+| tt_sequence | false           |
+| tt_skip     | false           |
+| tt_testname | learn-01-target |
++-------------+-----------------+
+
+GROUPS
+- Learn about targets
+    01 (1.0/1.0)
+        Description : Create user david
+        Command     : id david
+        Duration    : 0.003 (local)
+        Alterations : find(david) & count
+        Expected    : Greater than 0 (String)
+        Result      : 1 (Integer)
+
 RESULTS
 +--------------+---------------------------+
-| case_id      | 1                         |
-| start_time_  | 2019-06-20 12:27:50 +0100 |
-| finish_time  | 2019-06-20 12:27:50 +0100 |
-| duration     | 0.004641837               |
+| case_id      | 01                        |
+| start_time   | 2020-04-18 21:32:16 +0100 |
+| finish_time  | 2020-04-18 21:32:16 +0100 |
+| duration     | 0.002835857               |
 | unique_fault | 0                         |
 | max_weight   | 1.0                       |
 | good_weight  | 1.0                       |

data/docs/learn/example-02-config.md

@@ -0,0 +1,152 @@
+[<< back](README.md)
+
+1. [Config file](#config-file).
+2. [Definition section](#definition-section).
+3. [Execution section](#execution-section).
+4. [Results](#results).
+
+# Example: learn-02-config
+
+This example is on GitHub repository at `examples/learn-02-config`.
+
+* Learn how to use config file.
+* Tests use params defined into config files.
+* It's good idea save variable data separated into external config file.
+
+## Config file
+
+By default, `config.yaml` is our config file. Let's an example:
+
+```yaml
+---
+:global:
+:cases:
+- :tt_members: Student-name-1
+  :username: root
+- :tt_members: Student-name-2
+  :username: vargas
+```
+
+## Definition section
+
+By default, `start.rb` it's our main execution file.
+
+```ruby
+group "Reading params from config file" do
+
+  target "Create user #{gett(:username)}"
+  run "id #{get(:username)}"
+  expect get(:username)
+
+end
+```
+
+In this section we define targets using keywords: target, run, expect and get.
+
+* **get** keyword is used to read params from configuracion file. It's posible personalize tests with diferent values for every case.
+
+> NOTE: In this example, we assume GNU/Linux as localhost's OS.
+
+## Execution section
+
+Main execution block:
+```ruby
+play do
+  show
+  export
+end
+```
+
+Runing this example and see `show` keyword output:
+
+```bash
+> teuton run --no-color examples/learn-02-config
+[INFO] ScriptPath => examples/learn-02-config/start.rb
+[INFO] ConfigPath => examples/learn-02-config/config.yaml
+[INFO] Pwd        => /mnt/home/leap/proy/repos/teuton.d/teuton
+[INFO] TestName   => learn-02-config
+
+==================================
+Executing [teuton] (version 2.1.9)
+[INFO] Running in parallel (2020-04-18 21:46:38 +0100)
+id: «vargas»: no existe ese usuario
+.F
+[INFO] Duration = 0.004    (2020-04-18 21:46:38 +0100)
+==================================
+
+INITIAL CONFIGURATIONS
++---------------+-------------------------------------------+
+| tt_title      | Executing [teuton] (version 2.1.9)        |
+| tt_scriptname | examples/learn-02-config/start.rb         |
+| tt_configfile | examples/learn-02-config/config.yaml      |
+| tt_pwd        | /mnt/home/leap/proy/repos/teuton.d/teuton |
+| tt_testname   | learn-02-config                           |
+| tt_sequence   | false                                     |
++---------------+-------------------------------------------+
+
+CASE RESULTS
++------+----------------+-------+-------+
+| CASE | MEMBERS        | GRADE | STATE |
+| 01   | Student-name-1 | 100.0 |       |
+| 02   | Student-name-2 | 0.0   | ?     |
++------+----------------+-------+-------+
+
+FINAL VALUES
++-------------+---------------------------+
+| start_time  | 2020-04-18 21:46:38 +0100 |
+| finish_time | 2020-04-18 21:46:38 +0100 |
+| duration    | 0.003665655               |
++-------------+---------------------------+
+```
+
+## Results
+
+Output reports are saved into `var/learn-02-config/` directory. Detail output report is created for every case.
+
+```
+var/learn-02-config
+├── case-01.txt
+├── case-02.txt
+├── moodle.csv
+└── resume.txt
+```
+
+Let's see `export` keyword output for case 01.
+
+```
+> more var/learn-02-config/case-01.txt
+CONFIGURATION
++-------------+-----------------+
+| tt_members  | Student-name-1  |
+| tt_sequence | false           |
+| tt_skip     | false           |
+| tt_testname | learn-02-config |
+| username    | root            |
++-------------+-----------------+
+
+GROUPS
+- Using config file values
+    01 (1.0/1.0)
+        Description : Create user root (username)
+        Command     : id root
+        Duration    : 0.003 (local)
+        Alterations : find(root) & count
+        Expected    : Greater than 0 (String)
+        Result      : 1 (Integer)
+
+RESULTS
++--------------+---------------------------+
+| case_id      | 01                        |
+| start_time   | 2020-04-18 21:46:38 +0100 |
+| finish_time  | 2020-04-18 21:46:38 +0100 |
+| duration     | 0.002899065               |
+| unique_fault | 0                         |
+| max_weight   | 1.0                       |
+| good_weight  | 1.0                       |
+| fail_weight  | 0.0                       |
+| fail_counter | 0                         |
+| grade        | 100                       |
++--------------+---------------------------+
+```
+
+> **How to choose another config file?** Read this [document](../commands/example_run.md#3-choosing-config-file).

data/docs/learn/example-03-remote-hosts.md

@@ -1,18 +1,25 @@
-
 [<< back](README.md)
 
+1. [Config file](#config-file)
+2. [Definition section](#definition-section).
+3. [Execution section](#execution-section).
+4. [Results](#results).
+
 # Example: learn-03-remote-hosts
 
-Learn how to:
+This example is on GitHub repository at `examples/learn-03-remote-hosts`.
+
+Summary:
 * Check a group of remote hosts.
 * Export reports using other output formats.
 * Checking remote machine (host1) with Windows OS.
 
-> This example is on GitHub repository at `examples/learn-03-remote-hosts`.
-
 ## Config file
 
-`config.yaml` file:
+This configuration file contains:
+* 2 global params denitions.
+* 3 cases.
+* 4 specific case params definitions.
 
 ```yaml
 ---
@@ -34,37 +41,37 @@ Learn how to:
   :username: obiwan
 ```
 
-## Definitions (group section)
+## Definition section
 
 Define 3 targets (items to be checked):
 
 ```ruby
-group "learn 03 remote hosts" do
+group "How to test remote Windows hosts" do
 
-  target "Hostname is <#{get(:host1_hostname)}>"
-  goto   :host1, :exec => "hostname"
+  target "Update hostname with #{gett(:host1_hostname)}"
+  run "hostname", on: :host1
   expect_one get(:host1_hostname)
 
-  target "DNS Server OK"
-  goto   :host1, :exec => "nslookup www.google.es"
+  target "Ensure network DNS configuration is working"
+  run "nslookup www.google.es", on: :host1
   expect "Nombre:"
 
-  target "Exist user <#{get(:username)}>"
-  goto   :host1, :exec => "net user"
+  target "Create user #{gett(:username)}"
+  run "net user", on: :host1
   expect get(:username)
 
 end
 ```
 
-> Remote machine (host1) OS must be Windows.
+> NOTE: This example requires Windows OS on remote machine (host1).
 
-## Execution (play section)
+## Execution section
 
 ```ruby
 play do
   show
   # export using other output formats
-  export :format => :colored_text
+  export :format => :txt
   export :format => :json
   send :copy_to => :host1
 end
@@ -74,23 +81,22 @@ end
 * `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).
 
-## Output reports
+## Results
 
 ```
- $ tree var
 var
 └── learn-03-remote-hosts
-    ├── case-01.colored_text
     ├── case-01.json
-    ├── case-02.colored_text
-    ├── case-02.json
-    ├── case-03.colored_text
+    ├── case-01.txt
     ├── case-03.json
-    ├── resume.colored_text
-    └── resume.json
+    ├── case-03.txt
+    ├── moodle.csv
+    ├── resume.json
+    └── resume.txt
 ```
 
 * `case-01`, report with details about case 01 (maul)
-* `case-02`, report with details about case 02 (r2d2)
+* 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.