teuton 2.10.8 → 3.0.0

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.

data/docs/learn/23-test-code.md

@@ -4,10 +4,20 @@
 
 Let's test code using teuton.
 
-**Example:**
+## Exercise
 
-* Ask students to make a program that performs addition and multiplication.
-* Define targets `sum` and `mul`:
+Ask students to make a program that performs addition and multiplication.
+
+Usage:
+```
+$ examples/23-test-code/code/math_1.py 3 4
+Sum = 7
+Mul = 12
+```
+
+## Example
+
+Define targets `sum` and `mul`:
 
 ```ruby
 # File: start.rb
@@ -25,7 +35,7 @@ group "Test code example" do
 end
 ```
 
-* Define config params:
+Define config params:
 
 ```yaml
 # File: config.yaml
@@ -36,14 +46,14 @@ cases:
 - tt_members: student_1
   filename: math_1.py
 - tt_members: student_2
-  filename: math_2b.py
+  filename: math_2.py
 ```
 
-* Put students files into `code` folder.
+* Copy students files into `code` subfolder.
 * Now run Teuton test:
 
 ```
-❯ teuton examples/23-test-code
+$ teuton examples/23-test-code
 
 CASE RESULTS
 +------+-----------+-------+-------+

data/docs/learn/24-test-sql.md

@@ -1,14 +1,15 @@
 [<<back](README.md)
 
-# Test SQL and database
+# Test SQL and database content
 
-**Exercise**
+## Exercise
 
-* Ask students to make a Sqlite Database. Create a table called `characters` with `name` varchar, and `rol` varchar.
-* Database example:
+* Ask students to make a Sqlite Database. 
+* Create a table called `characters` with `name` varchar, and `rol` varchar.
 
+Database example:
 ```
-❯ sqlite3 examples/24-test-sql/database_01.db
+$ sqlite3 examples/24-test-sql/database_01.db
 
 sqlite> .schema characters
 CREATE TABLE characters ( name varchar(255), rol varchar(255));
@@ -17,20 +18,20 @@ sqlite> select * from characters;
 Obiwan|Jedi
 ```
 
-* Query example:
+* Ask students to create SQL queries inside a file. For example: select all Jedi characters.
 
 ```
-❯ cat examples/24-test-sql/query_01.sql
+$ cat examples/24-test-sql/query_01.sql
 
 select * from characters where rol='Jedi';
 ```
 
-**Teuton test**
+## Teuton test
 
-* Define targets:
+Define targets (start.rb file):
 
 ```ruby
-group "Test SQL and database" do
+group "Test SQL and database content" do
   database = "#{get(:folder)}/#{get(:database)}"
   query = "#{get(:folder)}/#{get(:query)}"
 
@@ -44,26 +45,26 @@ group "Test SQL and database" do
 end
 ```
 
-* Configure params:
+Configure params (config.yaml file):
 
 ```yaml
 ---
 global:
   folder: examples/24-test-sql
 cases:
-- tt_members: student_1_name
+- tt_members: student_1
   database: database_01.db
   query: query_01.sql
 ```
 
-**Test output**
+## Run test
 
 ```
-❯ teuton examples/24-test-sql                                   
+$ teuton examples/24-test-sql                                   
 
 CASE RESULTS
-+------+----------------+-------+-------+
-| CASE | MEMBERS        | GRADE | STATE |
-| 01   | student_1_name | 100.0 | ✔     |
-+------+----------------+-------+-------+
++------+-----------+-------+-------+
+| CASE | MEMBERS   | GRADE | STATE |
+| 01   | student_1 | 100.0 | ✔     |
++------+-----------+-------+-------+
 ```

data/docs/learn/25-expect-result.md

@@ -21,6 +21,7 @@
 | expect_exit NUMBER | Exit code is NUMBER |
 | expect_ok          | Exit code 0 |
 | expect_fail        | Exit code > 0 |
+| expect_sequence    | Validates sequences |
 
 > Learn more about [expect](../dsl/expect.md)
 

data/docs/learn/26-expect_sequence.md

@@ -23,8 +23,7 @@ expect /a.*?b.*?c/
 
 > Regular expressions are very powerful but they are also complex to use.
 
-To evaluate the occurrence of a certain sequence that takes place in different lines of the output we will use the new "expect_sequence" instruction.
-
+To evaluate the occurrence of a certain sequence that takes place in different lines of the output we use the "expect_sequence" instruction.
 
 ```ruby
 # Example:
@@ -37,11 +36,13 @@ expect_sequence do
 end
 ```
 
-> NOTE: expect_sequence can be useful for evaluating iptables firewall configurations where permission assignment order is relevant.
+> NOTE: `expect_sequence` can be useful for evaluating iptables firewall configurations where permission assignment order is relevant.
+
+## Usage
 
-## Evaluating different sequences
+### Simple sequence
 
-* **Simple sequence**. Validate sequences where the elements are in order. Use `find` statement to find each element of the sequence.
+Validate sequences where the elements are in order. Use `find` statement to find each element of the sequence.
 
 ```ruby
 # Examples: [A,B,C], [A,s,B,s,C], [x,A,B,s,C,x], etc.
@@ -53,7 +54,9 @@ expect_sequence do
 end
 ```
 
-* **Strict sequence**. validate sequences where the elements are in strict consecutive order. First use `find` to find an element in the sequence and then `next_to` for the next element in strict order.
+### Strict sequence
+
+Validate sequences where the elements are in strict consecutive order. First use `find` to find an element in the sequence and then `next_to` for the next element in strict order.
 
 ```ruby
 # Examples: [A,B,C], [x,A,B,C,x], etc.
@@ -65,7 +68,9 @@ expect_sequence do
 end
 ```
 
-* **Strict sequence with jumps**. Use `ignore N` to indicate that there are N lines between 2 elements of the sequence.
+### Strict sequence with jumps
+
+Use `ignore N` to indicate that there are N lines between 2 elements of the sequence.
 
 ```ruby
 # Examples: [A,B,s,s,C], [x,A,B,s,s,C,x], etc.

data/docs/learn/27-run_script.md

@@ -11,7 +11,7 @@ You know the classic sequence `target/run/expect`, but sometimes you need to run
 
 > Example files at [examples/27-run_file](../../examples/27-run_script)
 
-## Example scripts
+## Example files
 
 Suppose we have the following files:
 ```
@@ -29,11 +29,13 @@ echo $MESSAGE
 exit 0
 ```
 
-## Usage examples
+## Usage
 
 `run_script` is the DSL keyword in charge of uploading the script to the remote computer and executing it. When invoking run_script we have two styles: compact or separate components. Let's see
 
-**Compact invocation**: The "command" to execute contains the interpreter, the script, and the arguments.
+### Compact invocation
+
+The "command" string executed contains the interpreter, the script, and the arguments. Example: `"bash show.sh Hello"`.
 
 ```ruby
 target "Mode 1: Upload script and execute on remote host"
@@ -41,7 +43,9 @@ run_script "bash show.sh Hello", on: :host1
 expect "Hello"
 ```
 
-**Separate components**: pass the name of the script, the interpreter in charge of processing it and its arguments through separate parameters.
+### Separate components
+
+Pass the script name, interpreter, and its arguments using separate parameters.
 
 ```ruby
 target "Mode 2: Upload script and execute on remote host"
@@ -49,12 +53,14 @@ run_script "show.sh", shell: "bash", args: "Hello", on: :host1
 expect "Hello"
 ```
 
+### Separate components and defaut shell
+
 Or setting shell default value:
 
 ```ruby
 set(:shell, "bash")
 
-target "Mode 2: Upload script and execute on remote host"
+target "Mode 3: Upload script and execute on remote host"
 run_script "show.sh", args: "Hello", on: :host1
 expect "Hello"
 ```