teuton 2.1.1 → 2.1.2

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

@@ -0,0 +1,168 @@
+
+Learn how to use config file into your tests.
+Tests can use params defined into config files. It's good idea save variable data separated into external config file.
+
+> This example is on GitHub repository `teuton-challenge` at `learn/learn-02-config`.
+
+## Config file (`config.yaml`)
+
+```yaml
+---
+:global:
+:cases:
+- :tt_members: Student-name-1
+  :username: david
+- :tt_members: Student-name-2
+  :username: fran
+```
+
+## Definitions (`start.rb`)
+
+```ruby
+group "learn 02 config" do
+
+  target "Create user " + get(: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 param from configuracion file. It's posible personalize tests separated for every case.
+
+> Localhost's OS must be GNU/Linux (any other compatible OS) because the command used is `id david`.
+
+## Main execution block
+
+```ruby
+play do
+  show
+  # export using other output formats
+  export :format => :colored_text
+end
+
+```
+
+Runing this example and see `show` keyword output:
+
+```bash
+ $ teuton learn/learn-02-config
+[INFO] ScriptPath => learn/learn-02-config/start.rb
+[INFO] ConfigPath => learn/learn-02-config/config.yaml
+[INFO] TestName   => learn-02-config
+==================================
+Executing [teuton] (version 2.0.1)
+[INFO] Running in parallel (2019-06-20 11:20:49 +0100)
+.id: «darth-maul»: no existe ese usuario
+F
+[INFO] Duration = 0.008375141 (2019-06-20 11:20:49 +0100)
+
+
+==================================
+INITIAL CONFIGURATIONS
++---------------+------------------------------------------------------------------------------+
+| tt_title      | Executing [teuton] (version 2.0.1)                                           |
+| tt_scriptname | learn/learn-02-config/start.rb    |
+| tt_configfile | learn/learn-02-config/config.yaml |
+| tt_testname   | learn-02-config                                              |
+| tt_sequence   | false                                                                        |
++---------------+------------------------------------------------------------------------------+
+CASE RESULTS
++---------+-------------+----------------+
+| Case ID | % Completed | Members        |
+| Case_01 | 100%        | Student-name-1 |
+| Case_02 |   0% ?      | Student-name-2 |
++---------+-------------+----------------+
+FINAL VALUES
++-------------+---------------------------+
+| start_time  | 2019-06-20 11:20:49 +0100 |
+| finish_time | 2019-06-20 11:20:49 +0100 |
+| duration    | 0.008375141               |
++-------------+---------------------------+
+HALL OF FAME
++-----+---+
+| 100 | * |
+| 0   | * |
++-----+---+
+
+```
+---
+
+## Results
+
+Output reports are saved into `var/learn-02-config/` directory.
+
+```
+var/learn-02-config
+├── case-01.txt
+├── case-02.txt
+└── resume.txt
+```
+
+Let's see `export` keyword output.
+
+```
+$ more var/learn-02-config/case-01.txt
+
+CONFIGURATIONS
++------------+----------------+
+| tt_members | Student-name-1 |
+| username   | root           |
+| tt_skip    | false          |
++------------+----------------+
+
+TEST
+======================
+GROUP: learn 02 config
+ 01 (1.0/1.0)
+     Description : Checking user <root>
+     Command     : id root
+     Duration    : 0.003 (local)
+     Alterations : find(root) & count
+     Expected    : Greater than 0 (String)
+     Result      : 1 (Integer)
+
+RESULTS
++--------------+---------------------------+
+| case_id      | 1                         |
+| start_time_  | 2019-06-20 12:29:41 +0100 |
+| finish_time  | 2019-06-20 12:29:42 +0100 |
+| duration     | 0.003650038               |
+| unique_fault | 0                         |
+| max_weight   | 1.0                       |
+| good_weight  | 1.0                       |
+| fail_weight  | 0.0                       |
+| fail_counter | 0                         |
+| grade        | 100                       |
++--------------+---------------------------+
+```
+
+---
+
+## Using other config files
+
+**Default names:**:
+By default, when you run `teuton play foo`, this will search for:
+* `foo/start.rb` test file and
+* `foo/config.yaml` config file.
+
+**Using cname param:**
+But it's posible run `teuton play --cname=rock foo`, and this will search for:
+* `foo/start.rb` test file and
+* `foo/rock.yaml` config file.
+
+`cname` param searchs YAML config file into the same project folder.
+
+**Using cpath param:**
+An also, it's posible run `teuton play --cpath=/home/david/startwars.yaml foo`, and this will search for:
+* `foo/start.rb` test file and
+* `/home/david/starwars.yaml` config file.
+
+`cpath` param use YAML config file, from the specified path.
+
+**Using diferent main rb name:**
+When you run `teuton play foo/mazingerz.rb`, this will search for:
+* `foo/mazingerz.rb` test file and
+* `foo/mazingerz.yaml` config file.

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

@@ -0,0 +1,90 @@
+
+Learn how to:
+* 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 `teuton-challenge` at `learn/learn-03-remote-hosts`.
+
+## Config file (`config.yaml`)
+
+```yaml
+---
+:global:
+  :host1_username: root
+  :host1_password: profesor
+:cases:
+- :tt_members: Darth Maul
+  :host1_ip: 192.168.1.201
+  :host1_hostname: siths
+  :username: maul
+- :tt_members: R2D2
+  :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
+```
+
+## Definitions (group section)
+
+Defining 3 targets to be checked:
+
+```ruby
+group "learn 03 remote hosts" do
+
+  target "Hostname is <#{get(:host1_hostname)}>"
+  goto   :host1, :exec => "hostname"
+  expect_one get(:host1_hostname)
+
+  target "DNS Server OK"
+  goto   :host1, :exec => "nslookup www.google.es"
+  expect "Nombre:"
+
+  target "Exist user <#{get(:username)}>"
+  goto   :host1, :exec => "net user"
+  expect get(:username)
+
+end
+```
+
+> Remote machine (host1) OS must be Windows.
+
+## Execution (play section)
+
+```ruby
+play do
+  show
+  # export using other output formats
+  export :format => :colored_text
+  export :format => :json
+  send :copy_to => :host1
+end
+```
+
+* `show`, show process log on screen.
+* `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
+
+```
+ $ 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-03.json
+    ├── resume.colored_text
+    └── resume.json
+```
+
+* `case-01`, report with details about case 01 (maul)
+* `case-02`, report with details about case 02 (r2d2)
+* `case-03`, report with details about case 03 (obiwan)
+* `cresume`, report with global resumed information about all cases.

data/docs/learn/example-04-use.md

@@ -0,0 +1,74 @@
+
+Learn how to:
+* Organize huge amount of groups/targets into several files.
+* Checking Windows OS infrastructure (host1).
+
+> This example is on GitHub repository `teuton-challenge` at `learn/learn-04-use`.
+
+## Tree directory
+
+This example has more files:
+
+```bash
+$ tree learn/learn-04-use
+learn/learn-04-require
+├── config.yaml
+├── network.rb
+├── README.md
+├── start.rb
+└── users.rb
+```
+
+* `README.md` and `config.yaml` are the same as previous examples.
+
+## Execution (play section)
+
+Previous `start.rb` file is splited in: start.rb, users.rb and network.rb.
+
+Let's see current `start.rb` file:
+
+```ruby
+use 'users'
+use 'network'
+
+play do
+  show
+  export
+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.
+
+## Definitions (user section)
+
+> Require Windows OS on remote machine.
+
+Let's see `users.rb` file
+```ruby
+group "User configuration" do
+  target "Exist user <#{get(:username)}>"
+  goto   :host1, :exec => "net user"
+  expect get(:username)
+end
+
+```
+
+## Definitions (network section)
+
+> Require Windows OS on remote machine.
+
+Let's see `network.rb` file:
+
+```ruby
+group "Network configuracion" do
+
+  target "Hostname is <#{get(:host1_hostname)}>"
+  goto   :host1, :exec => "hostname"
+  expect_one get(:host1_hostname)
+
+  target "DNS Server OK"
+  goto   :host1, :exec => "nslookup www.nba.es"
+  expect "Nombre:"
+
+end
+```

data/docs/learn/example-05-debug.md

@@ -0,0 +1,104 @@
+
+Learn how to:
+* Check test syntax.
+* Debug your tests.
+
+> This example is on GitHub repository `teuton-challenge` at `learn/learn-05-debug`.
+
+## Tree directory
+
+```bash
+$ tree learn/learn-05-debug
+learn/learn-05-debug
+├── config.yaml
+├── external.rb
+├── internal.rb
+├── README.md
+└── start.rb
+```
+
+## Execution (play section)
+
+The `start.rb`  is main execution rb file, and uses `external` and `internal` rb files.
+
+Let's see current `start.rb` file:
+
+```ruby
+use 'external'
+use 'internal'
+
+play do
+  show
+  export :format => :colored_text
+end
+```
+
+## Debugging: Testing rb files
+
+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 (That's good) to load other files.
+
+When this happend, sometimes we need to verify or check rb file consistency and syntax, and we will do it with `teuton test PATH/TO/PROJECT/FOLDER`. Let's see an example:
+
+```bash
+$ teuton test learn/learn-01-target
+[INFO] ScriptPath => ...epos/teuton.d/units/learn/learn-01-target/start.rb
+[INFO] ConfigPath => ...s/teuton.d/units/learn/learn-01-target/config.yaml
+[INFO] TestName   => learn-01-target
+
++------------------------+
+| GROUP: learn-01-target |
++------------------------+
+(001) target      Create user <david>
+     weight      1.0
+     goto        localhost and {:exec=>"id david"}
+     expect      david (String)
+
++--------------+-------+
+| DSL Stats    | Count |
++--------------+-------+
+| Groups       | 1     |
+| Targets      | 1     |
+| Goto         | 1     |
+|  * localhost | 1     |
+| Uniques      | 0     |
+| Logs         | 0     |
+|              |       |
+| Gets         | 0     |
+| Sets         | 0     |
++--------------+-------+
++----------------------+
+| Revising CONFIG file |
++----------------------+
+[WARN] File /home/david/proy/repos/teuton.d/units/learn/learn-01-target/config.yaml not found!
+[INFO] Recomended content:
+---
+:global:
+:cases:
+- :tt_members: VALUE
+```
+
+In this case, Teuton detects that there isn't config file and propose us content for `config.yaml`.
+
+## Debugging: Result content
+
+Every time we invoke `goto` or `run` keywork, a OS command is executed and the output showed on screen is captured by Teuton and saved into `result` internal object.
+
+We coul debug it invoking `result.debug` into our rb file. Let's see an example from `external.rb.rb` file:
+
+```ruby
+group "Windows: external configuration" do
+
+  target "Localhost: Verify connectivity with #{gett(:windows1_ip)}"
+  run "ping #{get(:windows1_ip)} -c 1"
+  result.debug
+  expect_one "0% packet loss"
+  result.debug
+
+  target "Localhost: netbios-ssn service working on #{gett(:windows1_ip)}"
+  run "nmap -Pn #{get(:windows1_ip)}"
+  expect "139/tcp", "open"
+
+end
+```
+
+`result.debug` it's usefull when you are verifying what command ouput has been captured by Teuton.

data/docs/learn/example-11-first-test.md

@@ -0,0 +1,96 @@
+
+Steps:
+1. Create skeleton
+2. Personalize targets
+3. Personalize configuration file
+4. Run the challenge
+
+---
+
+## STEP 1: Create skeleton
+
+Create skeleton for a new project: `teuton create foo`
+
+```bash
+$ teuton create foo
+
+[INFO] Create project <foo>
+* Create dir        => foo
+* Create dir        => foo/assets
+* Create file       => foo/start.rb
+* Create file       => foo/config.yaml
+* Create file       => foo/.gitignore
+* Create file       => foo/assets/README.md
+```
+
+> It's posible to create these files by hand.
+
+This command will create:
+
+| File/Directory  | Description    |
+| --------------- | -------------- |
+| foo             | Base directory |
+| foo/assets      | Base directory for assest (images and text files) |
+| foo/start.rb    | Main Script    |
+| foo/config.yaml | YAML configuration file |
+| foo/.gitignore  | Prevent uploading YAML files to git repository |
+| foo/assets/README.md | Statement of practice |
+
+---
+
+## STEP 2: Personalize targets
+
+Write your own targets using the keywords: `target`, `goto` and `expect`. Let's see an example:
+
+```ruby
+group "Demo group" do
+
+	target "Exist </home/david> directory"
+	goto   :host1, :exec => "file /home/david"
+	expect ["/home/david", "directory"]
+
+end
+```
+
+The above example checks if exists 'yoda' user, on *host1* system.
+
+> Let's see the keywords used:
+>
+> * `target "Exist </home/david> directory"`, Describe the target with our words, so every one could easily understand what we are trying
+to check.
+> * `goto :host1, :exec => "file /home/david"`: Execute the command
+into the remote machine (host1).
+> * `expect ["/home/david", "directory"]`: Compare command ouput with our expectations.
+
+---
+
+## STEP 3: Personalize Configfile
+
+Use a YAML file (`foo/config.yaml`) or JSON for your own configurations. In this example, the file contains params used by our challenge (script).
+
+**Example**:
+
+```yaml
+---
+:global:
+ :host1_username: root
+:cases:
+- :tt_members: Student 01 name or alias
+ 	:host1_ip: 1.1.1.1
+ 	:host1_password: root-password-student-01
+- :tt_members: Student 02 name or alias
+ 	:host1_ip: 2.2.2.2
+ 	:host1_password: root-password-student-02
+```
+
+> The above file configures 2 diferents cases with their own params. The script use this information when execute every case.
+
+---
+
+## STEP 4: run the challenge
+
+Now we only have to run the challenge:
+
+```bash
+$ teuton foo
+```

data/docs/learn/learning.md

@@ -0,0 +1,34 @@
+
+# Learning
+
+Learn how to write your own tests reading examples.
+- [Quick demo](quick-demo.md)
+- [Example 01 - Target](example-01-target.md)
+- [Example 02 - Config file](example-02-configfile.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 11 - Create your first test](example-11-first-test.md)
+- [Videos](videos.md)
+
+---
+# 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!
+But if you want to see Spanish videos, here you are:
+
+Teuton (v2.0):
+* [CHAPI19 - Charla Teuton](https://youtu.be/KFWQDfNAFxI?t=12221)
+
+Sysadmingame (Teuton v1.0)
+* [Sysadmingame (1 de 3): Instalación del programa](https://youtu.be/dnyMq9_KDco)
+* [Sysadmingame (2 de 3): Crear un caso simple](https://youtu.be/0e2g5Izvc6c)
+* [Sysadmingame (3 de 3): Crear un caso complejo](https://youtu.be/ebEK6OXH8kQ)
+* [CHAPI16 - Charla sysadmingame](https://youtu.be/cNJaB5xzHHQ)