teuton 2.1.8 → 2.1.9

data/docs/dsl/README.md

@@ -1,5 +1,12 @@
+[<< back](../../README.md)
+
+# Teuton language
 
 To define and run our activity test we use the next DSL keywords:
+1. [Definition instructions](#definition-instructions)
+2. [Execution instructions](#execution-instructions)
+3. [Setting instructions](#setting-instructions)
+4. [Ruby language](#ruby-language)
 
 ## Definition instructions
 
@@ -9,13 +16,11 @@ These are the main DSL key words, usefull to define items to be evaluated.
 | :----------------------------- | :---------- |
 | [group](definition/group.md)   | Define a group of items to check. |
 | [target](definition/target.md) | Define a target. This is the item to be checked. |
-| [goto](definition/goto.md)     | Execute command into remote host. |
-| [run](definition/run.md)       | Execute command into localhost. |
+| Remote [run](definition/run_remote.md)| Execute command into remote host. |
+| Local [run](definition/run_local.md)  | Execute command into local host. |
 | [result](definition/result.md) | Contain the output of previous `goto` order. |
 | [expect](definition/expect.md) | Check the obtained result with the expected value. |
 
----
-
 ## Execution instructions
 
 DSL key word related with reports and information.
@@ -27,8 +32,6 @@ DSL key word related with reports and information.
 | [export](execution/export.md) | Make reports with the results of every evaluation. |
 | [send](execution/send.md)     | Send copy of report file to remote host. |
 
----
-
 ## Setting instructions
 
 | DSL                   | Descripción                                    |
@@ -36,10 +39,9 @@ DSL key word related with reports and information.
 | [get](setting/get.md) | Read param value from configuration file.      |
 | [set](setting/set.md) | Set new param value for running configuration. |
 
----
 ## Ruby language
 
-It is possible to use ruby language programming structures, in the definition of challenges (iterators, arrays, etc.). Very useful when we have repetitive lines.
+It is possible to use ruby language programming structures, in the definition of our test (iterators, arrays, etc.). Useful when we have repetitive lines, etc.
 
 Example, how to create 4 target evaluation using an Array:
 ```ruby
@@ -47,7 +49,7 @@ users = ['Obiwan', 'Yoda', 'Maul', 'Vader']
 
 users.each do |user|
   target "Exist user #{user}"
-  goto :host1, :exec => "id #{user}"
+  run "id #{user}", on: :host1
   expect_one user
 end
 ```

data/docs/dsl/definition/expect.md

@@ -1,3 +1,10 @@
+[<< back](../README.md)
+
+1. [Description](#description)
+2. [Usage](#usage)
+3. [Example](#example)
+4. [Basic](#basic)
+5. [Advanced](#advanced)
 
 ## Description
 
@@ -23,34 +30,31 @@ run 'id obiwan'
 expect 'obiwan' # Expect previous command output contains obiwan text
 ```
 
-## Other uses
-
-| Command                      | Description                         |
-| ---------------------------- | ----------------------------------- |
-| expect 'obiwan'              | Expect line/s with obiwan |
-| expect ['obiwan', 'kenobi' ] | Expect line/s with obiwan and kenobi|
-| expect_one 'obiwan'          | Expect one line with obiwan |
-| expect_one ['obiwan','kenobi'] | Expect 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 |
+## 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.
 
----
-
-## Expert mode
+## Advanced
 
-After every execution keyword (`goto`, or `run`), we get command outputs and save it into `result` object. So we can ask to `result` to create more complex evaluations.
+After every execution keyword (`run`, `on` or `goto`), command outputs is saved by **result** object. Use **result** to create more complex evaluations.
 
 For example, if we have this execution
+
 ```ruby
 target 'Exist user vader'
-run 'cat /etc/passwd'
+run    'cat /etc/passwd'
 ```
 
-Then we check result with
-```ruby
-expect result.find("vader").count.eq(1)
-expect result.find(/Darth|darth/).find(/Vader|vader/).count.eq(1)
-expect result.not_find('#').find(/vader).count.eq(1)
-```
+Then we check result with:
+
+* **expect result.find("vader").count.eq(1)**, expect there exists only 1 line with "vader" text.
+* **expect result.find(/Darth|darth/).find(/Vader|vader/).count.gt(2)**, expect there exists more than 2 lines with texts "Darth" and "Vader".
+* **expect result.not_find('#').find('vader').count.lt(3)**, expects there exists less than 3 lines with text "vader" and without "#" symbol.
+
+Read [result](result.md) documentation.

data/docs/dsl/definition/group.md

@@ -1,3 +1,7 @@
+[<< back](../README.md)
+
+1. [Description](#description)
+2. [Usage](#usage)
 
 ## Description
 
@@ -6,7 +10,7 @@ Groups targets/goals.
 ## Usage
 
 ```ruby
-group "group_name" do
+group "Group name" do
 	...
 end
 ```

data/docs/dsl/definition/result.md

@@ -1,26 +1,59 @@
+[<< back](../README.md)
+
+1. [Description](#description)
+2. [Example 1](#example-1)
+3. [Example 2](#example-2)
+4. [Functions](#functions)
 
 ## Description
 
-`result` saves the output from previous execution.
+**result** object saves the output from previous execution.
 It is usefull to build advanced `expect result...` sentences.
 
-* After every execution (For example, `goto :host1, :exec => "whoami"`), Teuton gets output and saves it into `result` object.
-* Use `result` object to read or filter that output.
+After every execution (For example, `run "whoami", on: :host1`), Teuton gets output and saves it into **result** object. Then use **result** object to read or filter previous command output.
+
+## Example 1
 
-## Usage 
+This example:
+1. get `/etc/passwd` file from `host1`, then
+2. filter lines without `#` and with `/bin/bash`.
+3. count lines number and
+4. expect it to be greater that 6.
 
-This example get /etc/passwd file from host1, then filter lines without '#' and with '/bin/bash'.
-Count lines number and expect it to be greater that 6.
+Let's see:
 
 ```
-target "Active users number configured with bash > 6"
-goto :host1, :exec => "cat /etc/passwd"
+target "Active users with bash > 6"
+run   "cat /etc/passwd", on: :host1
 expect result.grep_v('#').grep('/bin/bash').count.gt 6
 ```
 
-## Examples
+## Example 2
+
+It's posible contenate a sequence of several results orders. Examples:
+
+Supose we execute this:
+```
+run "cat /etc/passwd", on: :host1
+```
+
+And then we could do:
+* Get all lines that dosn't contain "nologin" and contain "/bin/bash"
+```
+result.grep_v("nologin").grep("/bin/bash")
+```
+* Count all lines that dosn't contain "nologin" and contain "/bin/bash"
+```
+result.grep_v("nologin").grep("/bin/bash").count
+```
+* Return true if the number when count all lines that dosn't contain "nologin" and contain "/bin/bash" is greater than 0
+```
+result.grep_v("nologin").grep("/bin/bash").count.gt 0
+```
 
-Boolean functions:
+## Functions
+
+**Boolean functions:**
 
 | Function            | Description               |
 | ------------------- | ------------------------- |
@@ -31,7 +64,7 @@ Boolean functions:
 | `result.lt(VALUE)`  | Result lesser than VALUE  |
 | `result.le(VALUE)`  | Result equal or lesser than VALUE |
 
-Filtering functions:
+**Filtering functions:**
 
 | Function             | VALUE type  | Description                           |
 | -------------------- | ----------- | ------------------------------------- |
@@ -44,7 +77,7 @@ Filtering functions:
 | `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:
+**Information functions:**
 
 | Function             | Description |
 | -------------------- | --------------------------------- |
@@ -52,25 +85,3 @@ Information functions:
 | `result.content`     | Return all output lines         |
 | `result.alterations` | Return transformations applied to the output |
 | `result.debug`       | Print the result content on screen. Usefull for debugging process |
-
-## Expert use
-
-It's posible contenate a sequence of several results orders. Examples:
-
-Supose we execute this:
-```
-goto :host1, :exec => "cat /etc/passwd"
-```
-And then we could do:
-* Get all lines that dosn't contain "nologin" and contain "/bin/bash"
-```
-result.grep_v("nologin").grep("/bin/bash")
-```
-* Count all lines that dosn't contain "nologin" and contain "/bin/bash"
-```
-result.grep_v("nologin").grep("/bin/bash").count
-```
-* Return true if the number when count all lines that dosn't contain "nologin" and contain "/bin/bash" is greater than 0
-```
-result.grep_v("nologin").grep("/bin/bash").count.gt 0
-```

data/docs/dsl/definition/run_local.md

@@ -0,0 +1,34 @@
+[<< back](../README.md)
+
+1. [Description](#description)
+2. [Usage](#usage)
+3. [Alias](#alias)
+4. [Example](#example)
+
+## Description
+
+Execute command on localhost and save output into result object.
+
+## Usage
+
+```ruby
+run "id COMMAND"
+```
+
+## Alias
+
+In fact it's the same as doing next:
+
+```ruby
+run "COMMAND", on: :localhost
+run "COMMAND", :on => :localhost
+```
+
+## Example
+
+```ruby
+run "id david"
+```
+
+* This instruction execute "id david" command on local machine, and save results into **result** object.
+* Local machine is where the `Teuton` program is running.

data/docs/dsl/definition/run_remote.md

@@ -0,0 +1,119 @@
+[<< back](../README.md)
+
+1. [Description](#description)
+2. [Usage](#usage)
+3. [Examples](#examples)
+4. [Protocol](#protocol)
+
+## Description
+
+Connect to remote host and executes command. The command output is saved into **result** object.
+
+## Usage
+
+```ruby
+run "COMMAND", on: :hostID
+on :hostID, run: "COMMAND"
+goto :hostID, :exec => "COMMAND"
+```
+> ADVISE: I know that programers dislike `goto` sentence, but this is diferent. Think of it as english speaker, not as developer.
+
+* This example connect to remote host identified by `hostID`. Then we execute the command into it and save the output commadn into result object.
+* Label `hostID` identifies specific machine. Host information (ip, username, password, protocol) cames from config file.
+
+## Examples
+
+Execute `id obiwan` comand into remote host `:linux1`.
+
+```Ruby
+run "id obiwan", on: :linux1
+run "id obiwan", :on => :linux1
+on :linux1, run: "id obiwan"
+on :linux1, :run => "id obiwan"
+goto :linux1, exec: "id obiwan"
+goto :linux1, :exec => "id obiwan"
+```
+
+Execute `id yoda` command into `localhost`.
+
+```Ruby
+run "id yoda"
+run "id yoda", on: :localhost
+run "id yoda", :on => :localhost
+on :localhost, run: "id yoda"
+on :localhost, :run => "id yoda"
+goto :localhost, :exec => "id yoda"
+goto :localhost, :execute => "id yoda"
+```
+
+## Protocol
+
+**SSH connection**
+
+Invoking `run` or `goto` sentence, Teuton opens SSH remote session by default. This config files examples do the same:
+
+Sample 1:
+```
+---
+:config:
+---
+:global:
+:cases:
+- :tt_members: Student1
+  :host1_ip: 1.1.1.1
+  :host1_username: student
+  :host1_password: secret
+```
+
+Sample 2:
+```
+---
+:config:
+---
+:global:
+:cases:
+- :tt_members: Student1
+  :host1_ip: 1.1.1.1
+  :host1_username: student
+  :host1_password: secret
+  :host1_protocol: ssh
+```
+
+**Telnet connection**: Open Telnet remote session.
+
+For example:
+```
+---
+:global:
+:cases:
+- :tt_members: Student2
+  :host1_ip: 2.2.2.2
+  :host1_username: student
+  :host1_password: secret
+  :host1_protocol: telnet
+```
+
+**Localhost**: When hostname is localhost, or host IP is 127.0.0.X, then Teuton will assume that you want to run your command on local system, and no session is opened. This examples are the same:
+
+```
+run "id david"
+```
+
+And
+
+```
+goto :localhost, :exec => "id david"
+```
+
+**SSH to localhost**: Force SSH session to localhost, then:
+
+```
+---
+:global:
+:cases:
+- :tt_members: Student3
+  :host1_ip: 127.0.0.1
+  :host1_username: student
+  :host1_password: secret
+  :host1_protocol: ssh
+```

data/docs/dsl/definition/target.md

@@ -1,3 +1,9 @@
+[<< back](../README.md)
+
+1. [Description](#description)
+2. [Usage](#usage)
+3. [Alias](#alias)
+4. [Weight](#weight)
 
 ## Description
 

data/docs/dsl/execution/export.md

@@ -1,7 +1,13 @@
+[<< back](../../README.md)
+
+1. [Description](#description)
+2. [Usage](#usage)
+3. [Example](#example)
+4. [Formats](#formats)
 
 ## Description
 
-Create reports and save then into `var/CHALLENGE-NAME` folder.
+Create reports and save then into `var/TEST-NAME` folder.
 
 ## Usage
 
@@ -11,29 +17,31 @@ play do
 end
 ```
 
+## Example
+
+Run export and build reports using txt output format by default:
+
+```ruby
+play do
+  export
+end
+```
+
+Run test and build reports using `html` output format:
+
+```ruby
+play do
+  export :format => :html
+end
+```
 
-## Other
+## Formats
 
 | Command                  | Description |
 | ------------------------ | ----------- |
 | `export`                 | Export report files using default ouput format |
 | `export :format => :txt` | Export file using TXT ouput format |
-| `export :format => :colored_text` | Export file using colored TXT ouput format |
+| `export :format => :html` | Export file using HTML ouput format |
 | `export :format => :yaml` | Export file using YAML ouput format |
 | `export :format => :json` | Export file using JSON ouput format |
-
-## Examples
-
-Run challenge and build reports using default output format:
-```
-    play do
-      export
-    end
-```
-
-Run challenge and build reports using `colored_text` output format:
-```
-    play do
-      export :format => :colored_text
-    end
-```
+| `export :format => :colored_text` | Export file using colored TXT ouput format |