teuton 2.1.1 → 2.1.2

data/docs/dsl/definition/run.md

@@ -0,0 +1,23 @@
+
+## Description
+
+Execute command on localhost and save output into result object.
+
+**Alias**: In fact it's the same as doing `goto :localhost, :execute => "COMMAND"`.
+
+> Then, why have another instruction? Because there are people who like doing this way.
+
+## Usage
+
+```ruby
+run "id david"
+```
+
+## 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/target.md

@@ -0,0 +1,35 @@
+
+## Description
+
+`target` instruction is used to begin new target/goal definition, and sets its description.
+
+## Usage
+
+```ruby
+target "Write here your description"
+```
+
+* Define target description. Use your own words to describe it, so everybody could understand what is going to be measured.
+* This text will be shown into reports to help us understand output information easily.
+
+## Alias
+
+`goal` keyword is an alias of `target`. So it's the same:
+
+```ruby
+target "Write here your description"
+```
+
+or
+
+```ruby
+goal "Write here your description"
+```
+
+## Weight
+
+By default weight is 1.0, but it's posible specified other value:
+
+```ruby
+target "Write here your description", :weight => 2.5
+```

data/docs/dsl/execution/export.md

@@ -0,0 +1,39 @@
+
+## Description
+
+Create reports and save then into `var/CHALLENGE-NAME` folder.
+
+## Usage
+
+```ruby
+play do
+    export
+end
+```
+
+
+## Other
+
+| 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 => :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
+```

data/docs/dsl/execution/play.md

@@ -0,0 +1,16 @@
+
+## Description
+
+DSL keyword that starts the execution of all targets/goals (defined into groups). We put this instruction at the end of every script, so it begin running the tests over the machines.
+
+## Usage
+
+```ruby
+play do
+	...
+end
+```
+
+* Write this block at the end of the rb script, to indicate that it's the moment to start the evaluation process.
+* The `group/target` instructions defines the tests we want to do, but `play` instruction is used to begin execution of all the groups/targets into every remote hosts of every case.
+* If you don't write this instruccion, your tests will never be executed.

data/docs/dsl/execution/send.md

@@ -0,0 +1,54 @@
+
+## Description
+
+`send` is used to copy Teuton reports into remote machines.
+
+## Usage
+
+```ruby
+start do
+  export
+  send :copy_to => :host1
+end
+```
+
+* `send` instruction must be execute after `export`. Reports must be generated before send them, of course.
+* `host1`, it' the label that identified remote host. This information must be configured into config file.
+* `send :copy_to => :host1`, copy every case resport file into temp directory on remote host `host1`.
+
+## Other uses
+
+| Action | Description |
+| ------ | ----------- |
+| `send :copy_to => :host1, :remote_dir => "/home/david"` | Reports will be saved into "/home/david" directory in remote machine `host1`. |
+| `send :copy_to => :host1, :prefix => "samba_"` | Case report will be save into temp directory on every host `host1`, named as `samba_case-XX.txt`. |
+
+> Teuton version 2.0.x
+> * By default, `send` only works when remote OS type is UNIX base, like GNU/Linux, MACOS, BSD, etc.
+> * For Windows OS we must specified `:remote_dir`. Example: `send :copy_to => :host1, :remote_dir => "C:\\"`. This example will copy files on directory c:\ of host1 machine.
+
+## How to send several output files
+
+If you export several files using differents output formats, you will use several `export` orders. Then when invoke `send` order, this will send the last exported file.
+
+In this example we export json and txt files, but only send txt to remote hosts:
+```ruby
+start do
+  export :format => :json
+  export :format => :txt
+
+  send :copy_to => :host1
+end
+```
+
+If you want to send every exported output file, then do like this:
+
+```ruby
+start do
+  export :format => :json
+  send :copy_to => :host1
+
+  export :format => :txt
+  send :copy_to => :host1
+end
+```

data/docs/dsl/execution/show.md

@@ -0,0 +1,21 @@
+
+## Description
+
+When tests ends, `show` instruction shows on screen information about final results.
+
+## Usage
+
+```ruby
+start do
+    show
+end
+```
+
+## Other uses
+
+| Action          | Description                             |
+| --------------- | --------------------------------------- |
+| `show`          | Same as `show :resume`. Default option. |
+| `show :resume`  | Show resumed information on screen.     |
+| `show :details` | Show details from every cases on screen.|
+| `show :all`     | Same as `show :resume` and `show :details`. |

data/docs/dsl/keywords.md

@@ -0,0 +1,53 @@
+
+To define and run our activity test we use the next DSL keywords:
+
+## Definition instructions
+
+These are the main DSL key words, usefull to define items to be evaluated.
+
+| DSL                            | Description |
+| :----------------------------- | :---------- |
+| [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. |
+| [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.
+
+| DSL                           | Descripción                              |
+| :---------------------------- | :--------------------------------------- |
+| [play](execution/play.md)     | Run the challenge.                       |
+| [show](execution/show.md)     | Show the results on screen.              |
+| [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                                    |
+| :-------------------- | :--------------------------------------------- |
+| [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.
+
+Example, how to create 4 target evaluation using an Array:
+```ruby
+users = ['Obiwan', 'Yoda', 'Maul', 'Vader']
+
+users.each do |user|
+  target "Exist user #{user}"
+  goto :host1, :exec => "id #{user}"
+  expect_one user
+end
+```

data/docs/dsl/setting/get.md

@@ -0,0 +1,36 @@
+
+## Description
+
+`get` read param value from configuration file.
+
+## Usage
+
+```ruby
+get(:param1)
+```
+
+## Example
+
+Suppose we have this `config.yaml` content:
+```yaml
+---
+:global:
+  :host1_username: root
+  :host1_password: secret
+:cases:
+- :tt_members: Obiwan
+  :host1_ip: 192.168.1.201
+  :host1_hostname: jedis
+  :username: obiwan
+```
+
+Then:
+* `get(:username)` returns `obiwan`.
+* `get(:host1_username)`, returns `root`.
+
+We also can create new temporal params:
+```ruby
+set(:new_param, "Hello")
+var = get(:new_param)
+```
+So `var` value will be "Hello".

data/docs/dsl/setting/set.md

@@ -0,0 +1,18 @@
+
+## Description
+
+`set` create new temporaly param value for running configuration.
+
+## Usage
+
+```ruby
+set(:param1, 'value')
+```
+
+## Example
+
+```ruby
+set(:new_param, "Hello")
+var = get(:new_param)
+```
+So `var` value will be "Hello".

data/docs/install/install.md

@@ -0,0 +1,32 @@
+
+> We recommend you, start reading about [Modes of use](modes_of_use.md), and learn the differences between T-node and S-node before installation.
+
+---
+# Installation
+
+**T-NODE installation**: Install Teuton on machine with T-NODE role.
+Installation process:
+
+1. Install Ruby on your system.
+2. `gem install teuton`
+
+Run `teuton version` to check that your installation is ok.
+
+**S-NODE installation**: Install SSH server on every machine with S-NODE role.
+
+---
+# Other installation ways
+
+[Installation using scripts](scripts_install.md)
+* Use our scripts to run automatical installation for your OS.
+* Use this way if you don't know how to install Ruby on your system.
+
+[Installation using Vagrant](vagrant_install.md)
+* If you plan to install Teuton into virtual machines, and have Vagrant installed into your real machine, this is the easier way for you.
+
+[Manual installation](manual_install.md)
+* If you don't need help, and want to install Teuton by your own, or there are not installation scripts for your favorite OS, and you don't want to use Vagrant then... here you have information how to install all the required packages for Teuton.
+
+Let's us known your installation difficulties.
+
+Thanks!

data/docs/install/manual_install.md

@@ -0,0 +1,25 @@
+There are diferents Teuton [Modes of use](Modes of use). For every mode there are 2 node typesm and every node has their own installation script:
+
+* **T-node**: This host has installed Teuton software.
+* **S-node**: This host has installed SSH server.
+
+---
+
+# T-NODE: Manual installation
+
+| ID | Action            | Details |
+| -- | ----------------- | ----------- |
+| 1  | Git installation  | Run `git --version` to show current version |
+| 2  | Ruby installation | Run `ruby -v` to show current version (2.1.3p242+) |
+| 3  | Rake installation | Run `gem install rake`, then `rake --version` to show current version (10.4.2+). |
+| 4  | Download this project | (a) `git clone https://github.com/dvarrui/teuton.git` (b) Download and unzip [file](https://github.com/dvarrui/teuton-panel/archive/master.zip). |
+| 5  | Gems installation | Run `cd teuton` and `rake gems` |
+| 6  | Final check       | `rake` |
+
+---
+
+# S-NODE: Manual installation
+
+* Install SSH server on your host.
+
+> How to [install SSH on Windows](windows-ssh)

data/docs/install/modes_of_use.md

@@ -0,0 +1,38 @@
+There are several **Teuton** ways of use: Classroom, Conquest and Standalone.
+
+For every mode exists 2 types of nodes: T-Node and S-Node.
+
+---
+
+## Classroom mode
+
+In this mode, a teacher use **Teuton** tool to evaluate the work done by their students into their real or virtual machines. The teacher need to access remotely to these machines.
+
+| Node | Description |
+| ---- | ----------- |
+| T    | Teacher install Teuton software into his machine, and he will connect remotely (using SSH) to every student machine. |
+| S    | Every student machine. |
+
+---
+
+## Contest mode
+
+We will hace a group of contestants who decide to do challenges and execute Teuton software into their own machines just to verify if satisfied the targets/goals of the challenge.
+
+On every run, Teuton software send results to remote server configured with SSH (used by the contest judges).
+
+| Node | Description                                                  |
+| ---- | ------------------------------------------------------------ |
+| T    | Every contest install Teuton software into their machine. Teuton wll connect via SSH to the server. |
+| S    | The server used by judges to save all the reports. |
+
+---
+
+## Standalone mode
+
+Install Teuton software into our own machine, and execute the challenges as you want. It is a good way for standalone learning .
+
+| Node | Descripción |
+| ---- | ----------- |
+| T    | Install Teuton software into our machine. |
+| S    | No necessary. |

data/docs/install/scripts_install.md

@@ -0,0 +1,76 @@
+
+There are different Teuton [Modes of use](modes_of_use.md). For every mode there are 2 node types and every node has their own installation script:
+
+* **T-node**: This host has installed Teuton software.
+* **S-node**: This host has installed SSH server.
+
+> Consult [tested OS](tested_os.md) to ensure if your favorite OS script installation has been tested.
+
+---
+# T-NODE installation
+
+## T-NODE: GNU/Linux installation
+
+Run this command as `root` user:
+
+```bash
+wget -qO- https://raw.githubusercontent.com/teuton-software/teuton/master/bin/linux_t-node_install.sh | bash
+```
+
+## T-NODE: Mac OS X installation
+
+Run this command as admin user (member of `admin` group):
+
+```bash
+curl -sL https://raw.githubusercontent.com/teuton-software/teuton/master/bin/macosx_t-node_install.sh | bash
+```
+
+> No `root` user.
+
+## T-NODE: Windows installation
+
+Requirements:
+* Windows 7+ / Windows Server 2003+
+* PowerShell v2+
+
+Run this command on **PowerShell (PS)** as `Administrator` user:
+
+```powershell
+Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/teuton-software/teuton/master/bin/windows_t-node_install.ps1'))
+```
+
+---
+
+# S-NODE installation
+
+This is, SSH server installation.
+
+> The user from T-NODE have to know admin password/user to establish SSH connections to S-NODE.
+
+## S-NODE: GNU/Linux installation
+
+Run this command as `root` user:
+
+```bash
+wget -qO- https://raw.githubusercontent.com/teuton-software/teuton/master/bin/linux_s-node_install.sh | bash
+```
+
+## S-NODE: Mac OS X installation
+
+Run this command as `root` user:
+
+```bash
+curl -sL https://raw.githubusercontent.com/teuton-software/teuton/master/bin/macosx_s-node_install.sh | bash
+```
+
+## S-NODE: Windows installation
+
+Requirements:
+* Windows 7+ / Windows Server 2003+
+* PowerShell v2+
+
+Run this command on **PowerShell (PS)** as `Administrator` user:
+
+```powershell
+Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/teuton-software/teuton/master/bin/windows_s-node_install.ps1'))
+```

data/docs/install/tested_od.md

@@ -0,0 +1,25 @@
+## GNU/Linux
+
+| O.S.      | Version        | Arch   | T-node | S-node |
+| --------- | -------------- | ------ | ------ | ------ |
+| CentOS    | 7              | x86-64 | [?]    | [?]    |
+| Debian    | 9.7.0          | x86-64 | [X]    | [?]    |
+| Fedora    | Workstation 29 | x84-64 | [?]    | [?]    |
+| LinuxMint | 18.3           | x86-64 | [X]    | [?]    |
+| openSUSE  | Leap 15        | x86-64 | [X]    | [X]    |
+| Ubuntu    | 18.04          | x86-64 | [X]    | [X]    |
+
+## Windows
+
+| O.S.    | Version        | Arch   | Nodo-T | Nodo-S |
+| ------- | -------------- | ------ | ------ | ------ |
+| Windows | 7 Enterprise   | x86    | [X]    | [?]    |
+| Windows | 10 Pro         | x86-64 | [X]    | [X]    |
+| Windows | Server 2012 R2 | x86-64 | [?]    | [?]    |
+
+## Mac OS X
+
+| O.S     | Version               | Arch   | T-Node | S-Node |
+| -------- | -------------------- | ------ | ------ | ------ |
+| Mac OS X | El Capitán (10.11.6) | x86-64 | [X]    | [X]    |
+| Mac OS X | Sierra (10.12)       | x86-64 | [X]    | [?]    |

data/docs/install/vagrant_install.md

@@ -0,0 +1,15 @@
+* First, you must have `Vagrant` installed.
+* Create directory for your vagrant project. For example, `mkdir teuton-vagrant`.
+* Move into that directory: `cd teuton-vagrant`.
+* Download required Vagrantfile:
+
+| Vagrantfile        | URL |
+| ------------------ | ----|
+| T-Node OpenSUSE VM | https://raw.githubusercontent.com/teuton-software/vagrant/master/t-node/opensuse/Vagrantfile |
+| S-Node OpenSUSE VM | https://raw.githubusercontent.com/teuton-software/vagrant/master/s-node/opensuse/Vagrantfile |
+
+* Run `vagrant up` to run the Virtual Machine.
+
+**Notice:** If you plan to build T-node and S-node VMs, then you need to use separated directories for every Vagranfile.
+
+> There are more Vagrantfile files for others OS at https://github.com/teuton-software/vagrant/ repository.

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

@@ -0,0 +1,117 @@
+
+Let's learn how to create our first target.
+A target is a feature you want to measure or check.
+
+> This example is on GitHub repository `teuton-challenge` at `learn/learn-01-target/`.
+
+## Definitions (Group section)
+
+```ruby
+group "learn-01-target" do
+
+  target "Exist <david> user"
+  run "id david"
+  expect "david"
+
+end
+```
+
+It's where 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.
+
+> Localhost's OS must be GNU/Linux (any other compatible OS) because the command used is `id david`.
+
+## Main execution block (Play section)
+
+```ruby
+play do
+  show
+  export
+end
+```
+
+Runing this example:
+
+```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] TestName   => learn-01-target
+==================================
+Executing [teuton] (version 2.0.0)
+[INFO] Running in parallel (2019-06-20 01:37:57 +0100)
+.
+[INFO] Duration = 0.013580866 (2019-06-20 01:37:58 +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                                                                        |
++---------------+------------------------------------------------------------------------------+
+CASE RESULTS
++---------+-------------+-----------+
+| Case ID | % Completed | Members   |
+| Case_01 | 100%        | anonymous |
++---------+-------------+-----------+
+FINAL VALUES
++-------------+---------------------------+
+| start_time  | 2019-06-20 01:37:57 +0100 |
+| finish_time | 2019-06-20 01:37:58 +0100 |
+| duration    | 0.013580866               |
++-------------+---------------------------+
+```
+
+## Results
+
+Output reports are saved into `var/learn-01-target/` directory.
+
+```bash
+var/learn-01-targets
+├── case-01.txt
+└── resume.txt
+```
+
+Let's see `export` keyword output.
+
+```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)
+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               |
+| unique_fault | 0                         |
+| max_weight   | 1.0                       |
+| good_weight  | 1.0                       |
+| fail_weight  | 0.0                       |
+| fail_counter | 0                         |
+| grade        | 100                       |
++--------------+---------------------------+
+```