teuton 2.7.3 → 2.9.0

data/docs/learn/02-target.md

@@ -7,37 +7,40 @@ A [target](../dsl/target.md) is a feature you want to check. Targets are defined
 ## Target definition
 
 * [target](dsl/target.md): Description of the element to be tested.
-* [run](../dsl/run.md): Execute a command `id david` on localhost.
+* [run](../dsl/run.md): Execute a command `id obiwan` on localhost.
 * [expect](../&dsl/expect.md): Verify that the result contains expected value.
 
 ```ruby
 group "Learn about targets" do
 
-  target "Create user david"
-  run "id david"
-  expect ["uid=", "(david)", "gid="]
+  target "Exist user obiwan"
+  run "id obiwan"
+  expect ["uid=", "(obiwan)", "gid="]
 
   target "Delete user vader"
   run "id vader"
-  expect ["id:", "vader", "no exist"]
-
+  expect_fail
 end
 ```
 
-> In this example, our localhost's OS is GNU/Linux (or any other compatible OS) because the command executed is `id david`.
+> In this example, our localhost's OS is GNU/Linux (or any other compatible OS) because the command executed is `id obiwan`.
 
-When the user exists, we expect this words: `uid=, (david), gid=`.
+When the user exists, we expect this words: `uid=, (obiwan), gid=`.
 
 ```
-❯ id david
-uid=1000(david) gid=1000(david) grupos=1000(david)
+❯ id obiwan
+uid=1000(obiwan) gid=1000(obiwan) grupos=1000(obiwan)
 ```
 
 But when user does not exist, we expect different words: `id:, vader, no exist`.
 
 ```
 ❯ id vader
-id: «vader»: no existe ese usuario
+id: «vader»: no such user
+
+❯ echo $?
+1
+
 ```
 
 ## Execution section
@@ -93,32 +96,34 @@ CONFIGURATION
 
 GROUPS
 - Learn about targets
-    01 (1.0/1.0)
-        Description : Create user david
-        Command     : id david
+    01 (0.0/1.0)
+        Description : Create user obiwan
+        Command     : id obiwan
+        Output      : id: «obiwan»: no existe ese usuario
         Duration    : 0.002 (local)
-        Alterations : find(uid=) & find((david)) & find(gid=) & count
-        Expected    : Greater than 0 (String)
-        Result      : 1 (Integer)
+        Alterations : find(uid=) & find((obiwan)) & find(gid=) & count
+        Expected    : Greater than 0
+        Result      : 0
     02 (1.0/1.0)
         Description : Delete user vader
         Command     : id vader
+        Output      : id: «vader»: no existe ese usuario
         Duration    : 0.002 (local)
-        Alterations : find(id:) & find(vader) & find(no exist) & count
-        Expected    : Greater than 0 (String)
-        Result      : 1 (Integer)
+        Alterations : Read exit code
+        Expected    : Greater than 0
+        Result      : 1
 
 RESULTS
 +--------------+---------------------------+
 | case_id      | 01                        |
-| start_time   | 2023-04-10 09:09:30 +0100 |
-| finish_time  | 2023-04-10 09:09:30 +0100 |
-| duration     | 0.003863242               |
+| start_time   | 2023-06-16 08:42:13 +0100 |
+| finish_time  | 2023-06-16 08:42:13 +0100 |
+| duration     | 0.004527443               |
 | unique_fault | 0                         |
 | max_weight   | 2.0                       |
-| good_weight  | 2.0                       |
-| fail_weight  | 0.0                       |
-| fail_counter | 0                         |
-| grade        | 100                       |
+| good_weight  | 1.0                       |
+| fail_weight  | 1.0                       |
+| fail_counter | 1                         |
+| grade        | 50                        |
 +--------------+---------------------------+
 ```

data/docs/learn/13-feedback.md

@@ -20,17 +20,16 @@ end
 
 Every time teuton is run, all cases are evaluated and when exporting the results, by default, all the information collected during the evaluation process is logged.
 
-Each "target" contains the following fields:
+Each `target` contains following fields:
 
-* Identification: id, description
-* Evaluation result: check(true/false)
-* Punctuation: score, weight
-* Check process: conn_type, command, duration, alterations, expected, result
+* Identification: `id`, `description`
+* Evaluation result: `check`(true/false)
+* Punctuation: `score`, `weight`
+* Check process: `conn_type`, `command`, `duration`, `alterations`, `expected` and `result`
 
-Some of these fields should always be visible, such as: id, description, check, score, and weight. And others, more related to the process that perform teuton for verification can be hidden using the "feedback: false" parameter.
-
-With "feedback: false" the fields are hidden: command, alterations, expected and result.
+Some of these fields should always be visible, such as: id, description, check, score, and weight. And others, more related to the process that perform teuton for verification can be hidden using the `feedback: false` parameter.
 
+With `feedback: false` the fields are hidden: command, alterations, expected and result.
 
 ## Results
 
@@ -40,7 +39,7 @@ Executing `teuton run examples/13-feedback`, we get this output:
 GROUPS
 - Preserve output reports
     01 (1.0/1.0)
-        Description : Exits user david
+        Description : Exits user Obiwan
         Command     : ********
         Duration    : 0.002 (local)
         Alterations : *******************

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

@@ -0,0 +1,39 @@
+[<<back](README.md)
+
+# expect vs result
+
+* `expect` is the statement we use to evaluate the result generated by a previous `run` statement.
+* `result` allows you to manipulate the output of the run command in more detail.
+
+`expect` is easier to use but less powerful than `result`.
+
+> Example files at [examples/25-expect-result](../../examples/25-expect-result)
+
+## Expect
+
+`expect` has different ways to evaluate result.
+
+| DSL                | Description |
+| ------------------ | ----------- |
+| expect FILTER      | it finds lines in the output with the content FILTER |
+| expect_none FILTER | it finds lines in the output without the FILTER content |
+| expect_nothing     | is true when the result is empty |
+| expect_exit NUMBER | Exit code is NUMBER |
+| expect_ok          | Exit code 0 |
+| expect_fail        | Exit code > 0 |
+
+> Learn more about [expect](../dsl/expect.md)
+
+## Result
+
+`result` is an object that encapsulates the output of the run command and allows manipulation of its contents before being evaluated by `expect`.
+
+| Result command | Description |
+| -------------- | ----------- |
+| expect result.count.eq NUMBER | Is true when output has NUMBER lines |
+| expect result.count.gt NUMBER | Is true when output has more than NUMBER lines |
+| expect result.count.lt NUMBER | is true when output has less than NUMBER lines |
+| expect result.grep(FILTER).count.eq NUMBER | output has NUMBER lines with FILTER |
+| expect result.grep_v(FILTER).count.eq NUMBER | output has NUMBER lines without FILTER |
+
+> Learn more about [result](../dsl/result.md)

data/docs/learn/26-expect_sequence.md

@@ -0,0 +1,79 @@
+[<<back](README.md)
+
+# DSL: expect_sequence
+
+Evaluate the occurrence of a certain sequence that takes place in different lines of the output.
+
+> Example files at [examples/26-expect_sequence](../../examples/26-expect_sequence)
+
+## Description
+
+In the classic target/run/expect, the expect statement works by locating lines from the output of the previous command that meet certain criteria.
+
+We can even (using regular expressions) detect if there is any line in the output where a certain sequence appears.
+
+
+```ruby
+# Example:
+#   expect with regular expression to detect [a, b, c] sequence
+#   within a line
+
+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.
+
+
+```ruby
+# Example:
+#   expect_sequence to detect [a, b, c] sequence
+
+expect_sequence do
+  find "a"
+  find "b"
+  find "c"
+end
+```
+
+> NOTE: expect_sequence can be useful for evaluating iptables firewall configurations where permission assignment order is relevant.
+
+## Evaluating different sequences
+
+* **Simple 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.
+
+expect_sequence do
+  find "A"
+  find "B"
+  find "C"
+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.
+
+```ruby
+# Examples: [A,B,C], [x,A,B,C,x], etc.
+
+expect_sequence do
+  find "A"
+  next_to "B"
+  next_to "C"
+end
+```
+
+* **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.
+
+expect_sequence do
+  find "A"
+  next_to "B"
+  ignore 2
+  next_to "C"
+end
+```

data/docs/learn/27-run_script.md

@@ -0,0 +1,91 @@
+[<<back](README.md)
+
+# DSL: run_script
+
+You know the classic sequence `target/run/expect`, but sometimes you need to run our own script files on the remote computer. So you have to:
+
+1. Upload a copy of the script file to the remote host
+2. and then run it on remote host
+
+**run_script** upload and execute your own local script on remote host.
+
+> Example files at [examples/27-run_file](../../examples/27-run_script)
+
+## Example scripts
+
+Suppose we have the following files:
+```
+example
+├── config.yaml
+├── show.sh
+└── start.rb
+```
+
+Contents of the `show.sh` script:
+```bash
+#!/usr/bin/env bash
+MESSAGE=$1
+echo $MESSAGE
+exit 0
+```
+
+## Usage examples
+
+`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.
+
+```ruby
+target "Mode 1: Upload script and execute on remote host"
+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.
+
+```ruby
+target "Mode 2: Upload script and execute on remote host"
+run_script "show.sh", shell: "bash", args: "Hello", on: :host1
+expect "Hello"
+```
+
+Or setting shell default value:
+
+```ruby
+set(:shell, "bash")
+
+target "Mode 2: Upload script and execute on remote host"
+run_script "show.sh", args: "Hello", on: :host1
+expect "Hello"
+```
+
+## Running example
+
+```
+------------------------------------
+Started at 2023-07-23 13:46:11 +0100
+....uu..u.u.u.uu..u.!F!F!F!F
+Finished in 30.457 seconds
+------------------------------------
+
+CASE RESULTS
++------+-----------+-------+-------+
+| CASE | MEMBERS   | GRADE | STATE |
+| 01   | Localhost | 100.0 | ✔     |
+| 02   | Remote1   | 100.0 | ✔     |
+| 03   | Remote2   | 100.0 | ✔     |
+| 04   | Remote3   | 0.0   | ?     |
++------+-----------+-------+-------+
+
+CONN ERRORS
++------+---------+-------+------------------+
+| CASE | MEMBERS | HOST  | ERROR            |
+| 04   | Remote3 | host1 | host_unreachable |
++------+---------+-------+------------------+
+```
+
+Meaning of progress symbols:
+* `.`: check ok
+* `F`: check fail
+* `!`: connection fail
+* `u`: upload ok

data/docs/learn/28-upload.md

@@ -0,0 +1,55 @@
+[<<back](README.md)
+
+# DSL: upload
+
+`upload` is a dsl instruction, whose purpose is to upload files to the remote host.
+
+```ruby
+  upload "FILENAME", to: :host1
+```
+
+* `upload "FILENAME"`, upload local file to remote.
+* `to: :host1`, specifies remote host.
+
+> Example files at [examples/28-upload](../../examples/28-upload)
+
+## Other options
+
+* Upload "LOCALDIR/FILENAME" to default remote dir into remote host:
+
+```ruby
+  upload "LOCALDIR/FILENAME", to: :host1
+```
+
+* Upload "LOCALDIR/FILENAME" to remote dir into remote host:
+
+```ruby
+  upload "LOCALDIR/FILENAME", remotedir: "REMOTEDIR", to: :host1
+```
+
+* Upload several local files from "LOCALDIR" to default remote dir into host:
+
+```ruby
+  upload "LOCALDIR/*", to: :host1
+```
+
+* Upload several local files from "LOCALDIR" to remote host:
+
+```ruby
+  upload "LOCALDIR/*", remotedir: "REMOTEDIR", to: :host1
+```
+
+## Example
+
+```ruby
+  target "Upload file and then run it"
+  upload "script/show.sh", remotedir: "sh", to: :host1
+  run "bash sh/show.sh HelloWorld", on: :host1
+  expect "HelloWorld"
+```
+
+Example steps:
+1. Describe target.
+2. Upload local file to remote host.
+3. Run script using Bash on remote host.
+4. Evaluate script output.

data/docs/learn/README.md

@@ -28,20 +28,9 @@ Learn how write your own Teuton tests:
 1. [RESULT object](22-result.md)
 1. [Test code](23-test-code.md)
 1. [Test SQL and database](24-test-sql.md)
+1. [expect vs result](25-expect-result.md) TODO
+1. [EXPECT_SEQUENCE](26-expect_sequence.md)
+1. [RUN_SCRIPT](27-run_script.md)
+1. [UPLOAD](28-upload.md)
 
 Mores examples at [teuton-tests](https://github.com/dvarrui/teuton-tests) GitHub repository.
-
-# 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):
-* [ES - CHAPI19: Charla Teuton](https://youtu.be/KFWQDfNAFxI?t=12221)
-* [ES - CHAPI19: Teuton demo](https://github.com/dvarrui/proyectos-de-ejemplo/tree/master/charlas/teuton)
-
-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)

data/docs/videos.md

@@ -7,14 +7,20 @@
 
 # Videos
 
-Teuton:
+> By now there are no English videos. We are sorry!
+
+Teuton v2.1:
 * [Apuntes FP Informática - I Congreso Virtual - Mayo 2020](https://youtu.be/RxIV26BAoGo)
-* [Teuton Software 2.1 - Tutorial - Oct 2020](https://youtu.be/cyBN-rOYQeY)
+* [Teuton Software 2.1 - Tutorial - Abr 2020](https://youtu.be/cyBN-rOYQeY)
 
-Teuton en el 2016 se llamaba "sysadmingame".
-* ES -[CHAPI16 - Presentación sysadmingame chapi16 - Abril 2016](https://youtu.be/cNJaB5xzHHQ)
-* sysadmingame:
-    1. [Instalación del programa](https://youtu.be/dnyMq9_KDco)
-    2. [Crear un caso simple](https://youtu.be/0e2g5Izvc6c)
-    3. [Crear un caso complejo](https://youtu.be/ebEK6OXH8kQ)
+Teuton v2.0:
+* [ES - CHAPI19: Charla Teuton](https://youtu.be/KFWQDfNAFxI?t=12221)
+* [ES - CHAPI19: Teuton demo](https://github.com/dvarrui/proyectos-de-ejemplo/tree/master/charlas/teuton)
 
+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)
+
+Sysadmingame: En el 2016 el proyecto se llamaba "sysadmingame".
+* ES -[CHAPI16 - Presentación sysadmingame chapi16 - Abril 2016](https://youtu.be/cNJaB5xzHHQ)

data/lib/teuton/case/case.rb

@@ -2,16 +2,16 @@
 
 require_relative "../utils/project"
 require_relative "../utils/verbose"
-require_relative "../utils/result/result"
 require_relative "../report/report"
 require_relative "dsl/all"
 require_relative "config"
 require_relative "close"
+# require_relative "builtin/main"
+require_relative "host"
 require_relative "play"
-require_relative "builtin/main"
+require_relative "result/result"
 
 class Case
-  # Case: export, filename, grade, members,skip
   include DSL
   include Verbose
 

data/lib/teuton/case/config.rb

@@ -2,11 +2,6 @@
 
 require_relative "../utils/project"
 
-# Class Case::Config
-# * get
-# * set
-# * unset
-# * missing_method
 class Case
   class Config
     # This class manage configuration for only one case

data/lib/teuton/case/dsl/all.rb

@@ -1,8 +1,12 @@
 require_relative "expect"
 require_relative "getset"
-require_relative "goto"
+require_relative "host"
 require_relative "log"
 require_relative "macro"
+require_relative "run"
+require_relative "run_script"
 require_relative "send"
 require_relative "target"
 require_relative "unique"
+require_relative "upload"
+require_relative "weight"

data/lib/teuton/case/dsl/expect.rb

@@ -1,26 +1,34 @@
 # frozen_string_literal: true
 
-module DSL
-  # expect, expect2, expect_any, expect_first, expect_last
-  # expect_nothing, expect_none, expect_one
+require_relative "expect_exitcode"
+require_relative "expect_sequence"
 
-  # expect <condition>, :weight => <value>
+module DSL
+  # expect <condition>,
+  #      value: RealValue,
+  #   expected: ExpectedValue,
+  #     weight: float
+  #
   def expect(input, args = {})
     if input.instance_of?(TrueClass) || input.instance_of?(FalseClass)
       expect2(input, args)
     elsif input.instance_of?(String) || input.instance_of?(Regexp) || input.instance_of?(Array)
       expect_any input
     else
-      puts Rainbow("[TypeError] expect #{input} (#{input.class})").red
+      puts Rainbow("[ERROR] Case expect TypeError: expect #{input} (#{input.class})").red
     end
   end
 
   def expect2(cond, args = {})
     @action_counter += 1
     @action[:id] = @action_counter
-    @action[:check] = cond
-
-    @action[:result] = (args[:value] || @result.value)
+    if @result.exitcode < 0
+      @action[:check] = false
+      @action[:result] = @action[:output]
+    else
+      @action[:check] = cond
+      @action[:result] = (args[:value] || @result.value)
+    end
 
     @action[:alterations] = @result.alterations
     @action[:expected] = (args[:expected] || @result.expected)
@@ -41,22 +49,6 @@ module DSL
     expect2 result.count.gt(0), args
   end
 
-  def expect_exit(value)
-    @result.alterations = "Read exit code"
-    real_value = result.exitcode
-    cond = if value.is_a? Range
-      expect_value = "With range #{value}"
-      value.to_a.include? real_value
-    elsif value.is_a? Array
-      expect_value = "Inside list #{value}"
-      value.include? real_value
-    else
-      expect_value = value
-      (real_value == value.to_i)
-    end
-    expect2 cond, value: real_value, expected: expect_value
-  end
-
   def expect_first(input, args = {})
     @result.first
     output = input
@@ -95,14 +87,9 @@ module DSL
     expect2 result.count.eq(1), args
   end
 
-  def weight(value = nil)
-    # Set weight value for the action
-    if value.nil?
-      @action[:weight]
-    elsif value == :default
-      @action[:weight] = 1.0
-    else
-      @action[:weight] = value.to_f
-    end
+  def expect_sequence(&block)
+    seq = ExpectSequence.new(result.content.dup)
+    cond = seq.is_valid?(&block)
+    expect2 cond, value: seq.real, expected: seq.expected
   end
 end

data/lib/teuton/case/dsl/expect_exitcode.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module DSL
+  def expect_exit(value)
+    @result.alterations = "Read exit code"
+    real_value = result.exitcode
+    cond = if value.is_a? Range
+      expect_value = "With range #{value}"
+      value.to_a.include? real_value
+    elsif value.is_a? Array
+      expect_value = "Inside list #{value}"
+      value.include? real_value
+    else
+      expect_value = value
+      (real_value == value.to_i)
+    end
+    expect2 cond, value: real_value, expected: expect_value
+  end
+
+  def expect_fail
+    @result.alterations = "Read exit code"
+    real_value = result.exitcode
+    expect_value = "Greater than 0"
+    cond = (real_value > 0)
+    expect2 cond, value: real_value, expected: expect_value
+  end
+
+  def expect_ok
+    expect_exit 0
+  end
+end