teuton 2.10.8 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5b35750a1b166a54ba8f1c2f8dfdf82b8f1bbeb10dbc26c954aa926ebf47209
-  data.tar.gz: 06363a74c993cfe89d182a6f8473d7f713f3351da16e2f397fe9f7dfd327c049
+  metadata.gz: 5088e7bd81367702f9c4bf03819a8b0c6314d42491afb5a35afc985102db54a8
+  data.tar.gz: e6fed00de115a204785a5c9d8949ab45bfab14088a91c49b4e43dad868020366
 SHA512:
-  metadata.gz: ec53a0570321130474a302b5863d470b8e99f051eaad3070a367374dfbeddda4e3cab5e85af02f8dbf29b9405022a440167920aface1242eed30b49243465ec7
-  data.tar.gz: bac07b9e1d452de58acade93b292cd7edf62e37bede4a2ee05d450816c6068577b7463afe986265559f94529aad0ee2a5d84bae606f46a5619afe911320224c1
+  metadata.gz: 9a54014188a4eb0869d3bb82e35da1043c7e663bff461b3feb32c8b9e653a7e4770f4d24970a193b1cb8f55cb280014f4e7e3f92c140c19b04559f11833f16c1
+  data.tar.gz: 69a5dd3e075fae27c3495d0d406284d8d448e1a8f68decea3905ed9fd08fe60395d0454ba291f6680aa489766485e6d18cf1b346a717ed9a190b097cd8d4d2e9

data/README.md

@@ -21,28 +21,54 @@ Install Ruby and then:
 gem install teuton
 ```
 
-> **NOTE**
-> * Available versions ([rubygems.org/gems/teuton](https://rubygems.org/gems/teuton/))
-> * Install a specific version: `gem install teuton -v VERSION`.
-> * Update: `gem update teuton`.
-
-# Usage
+# Quickstart
+
+**Create** your test file:
+
+```ruby
+# File: examples/02-target/start.rb 
+group "Learn about targets" do
+  target "Create user obiwan", weight: 2
+  run "id obiwan"
+  expect ["uid=", "(obiwan)", "gid="]
+
+  target "Delete user vader"
+  run "id vader"
+  expect_fail
+end
+
+start do
+  show
+  export
+end
+```
 
-Use `teuton run TESTPATH` command to run test:
+**Usage**: Run test with `teuton run TESTPATH`.
 
 ```console
 $ teuton run examples/02-target
 ------------------------------------
-Started at 2025-11-12 20:15:59 +0000
+Started at 2025-12-01 18:14:44 +0000
 F.
 Finished in 0.005 seconds
 ------------------------------------
  
 CASE RESULTS
-+------+---------+-------+-------+
-| CASE | MEMBERS | GRADE | STATE |
-| 01   | VALUE   | 33.0  | ?     |
-+------+---------+-------+-------+
++------+-----------+-------+-------+
+| CASE | MEMBERS   | GRADE | STATE |
+| 01   | anonymous | 33.0  | ?     |
++------+-----------+-------+-------+
+```
+
+**Output**: reports saved into `var/TESTNAME` folder.
+
+```
+$ tree var 
+var
+└── 02-target
+    ├── case-01.txt
+    ├── moodle.csv
+    └── resume.txt
 ```
 
 Consult the generated [output files](examples/02-target/output.d/)
@@ -51,17 +77,38 @@ Consult the generated [output files](examples/02-target/output.d/)
 
 * Use simple DSL to define your tests: `target`, `run`,`expect` and more.
 * Remote devices only require SSH or Telnet service installed.
-* Output format: txt, html, json, yaml, etc.
+* Output format: txt, html, json, yaml, markdown, etc.
 * Multiplatform.
 * [Free Software License](LICENSE).
 
 # Documentation
 
-* [Installation](docs/install/README.md)
-* [Learning](docs/learn/README.md)
-* [Examples](examples)
-* [Commands](docs/commands/README.md)
-* [Language reference](docs/dsl/README.md)
+* Installation
+    * [Teuton installation](docs/install/t-node.md)
+    * [SSH/Telnet installation](docs/install/s-node.md)
+* Teuton commands
+    * [teuton config](docs/commands/config.md)
+    * [teuton check](docs/commands/check.md)
+    * [teuton help](docs/commands/help.md)
+    * [teuton new](docs/commands/new.md)
+    * [teuton readme](docs/commands/readme.md)
+    * [teuton run](docs/commands/run.md)
+* [Learning guide](docs/learn/README.md). Learning to create tests by doing.
+* [Learning Examples](examples). The learning guide is based on these examples.
+* [Configuration file](docs/config_file.md)
+* [DSL - Language reference](docs/dsl/README.md). DSL used to define tests.
+    * [expect](docs/dsl/expect.md)
+    * [export](docs/dsl/export.md)
+    * [get](docs/dsl/get.md)
+    * [group](docs/dsl/group.md)
+    * [play](docs/dsl/play.md)
+    * [result](docs/dsl/result.md)
+    * [run](docs/dsl/run.md)
+    * [send](docs/dsl/send.md)
+    * [set](docs/dsl/set.md)
+    * [show](docs/dsl/show.md)
+    * [target](docs/dsl/target.md)
+* [Modes of use](docs/modes_of_use.md): Classroom, contest, standalone.
 * [Blogs and videos](docs/videos.md)
 
 # Contact

data/docs/commands/README.md

@@ -2,86 +2,23 @@
 
 # Commands
 
-Available command functions:
-1. [Show help](#1-show-help)
-2. [Show version](#2-show-version)
-3. [Create new test](#3-create-new-test)
-4. [Check test](#4-check-test)
-5. [Run test](#5-run-test)
-6. [Show test info as README file](#6-show-test-info-as-readme-file)
-
-# 1. Show help
-
-Show help about command functions.
-
-Usage: 
-* `teuton help`
-* `teuton help FUNCTION_NAME`
-
-Alias: `teuton h`,`teuton -h`, `teuton --help`
-
-# 2. Show version
-
-Show current version.
-
-Usage: `teuton version`
-
-Alias: `teuton v`, `teuton -v`, `teuton --version`
-
-# 3. Create new test
-
-Create test skeleton.
-
-Usage: `teuton new foo`
-
-Example:
-
-```console
-$ teuton new foo
-
-Creating foo project
-* Create dir        => foo
-* Create file       => foo/config.yaml
-* Create file       => foo/start.rb
+```
+$ teuton
+Commands:
+  teuton [run] [OPTIONS] DIRECTORY   # Run test from directory
+  teuton check [OPTIONS] DIRECTORY   # Check test and config file content
+  teuton config [OPTIONS] DIRECTORY  # Suggest configuration or run server
+  teuton help [COMMAND]              # Describe available commands or one specific command
+  teuton new DIRECTORY               # Create skeleton for a new project
+  teuton readme DIRECTORY            # Show README extracted from test contents
+  teuton version                     # Show the program version
 ```
 
-This command will create the next structure:
-
-| File/Directory  | Description    |
-| --------------- | -------------- |
-| foo             | Base directory |
-| foo/start.rb    | Main file with test definitions |
-| foo/config.yaml | YAML configuration file |
-
-Alias: `teuton n foo`, `teuton -n foo`, `teuton --new foo`
-
-# 4. Check test
-
-Check test and config files from DIRPATH folder.
-
-Usage: `teuton check DIRPATH`
-
-[Example](check-example.md)
-
-| Command                      | Description |
-| ---------------------------- | ----------- |
-| teuton check path/to/dir/foo | Test content of start.rb and config.yaml files. |
-| teuton check path/to/dir/foo --cname=demo | Test content of start.rb and demo.yaml files. |
-| teuton check path/to/file/foo.rb | Test content of foo.rb and foo.yaml files. |
-| teuton check path/to/file/foo.rb --cname=demo | Test content of foo.rb and demo.yaml files.|
-
-Alias: `teuton c foo`, `teuton -c foo`, `teuton --check foo`
-
-# 5. Run test
-
-Read about how to [run tests](run-tests.md)
-
-# 6. Show test info as README file
-
-Create a readme file for the exercise.
-
-Usage: `teuton readme DIRPATH > README.md`
-
-This function reads test and config files, and generate Markdown output with guidelines and target descriptions about the exercise.
-
-Alias: `teuton r DIRPATH`, `teuton -r DIRPATH`, `teuton --readme DIRPATH`
+Available command functions:
+1. [run](run.md)
+2. [check](check.md)
+3. [config](config.md)
+4. [help](help.md)
+5. [new](new.md)
+6. [readme](readme.md)
+7. **version**: _Show current version_. Usage: `teuton version`.

data/docs/commands/check.md

@@ -0,0 +1,66 @@
+[<< back](../../README.md)
+
+# check
+
+_Check test and config files from test folder._
+
+Usage: `teuton check PATH/TO/DIR`
+
+| Command                      | Description |
+| ---------------------------- | ----------- |
+| teuton check PATH/TO/DIR/foo | Test content of start.rb and config.yaml files. |
+| teuton check PATH/TO/DIR/foo --cname=demo | Test content of start.rb and demo.yaml files. |
+| teuton check PATH/TO/FILE/foo.rb | Test content of foo.rb and foo.yaml files. |
+| teuton check PATH/TO/FILE/foo.rb --cname=demo | Test content of foo.rb and demo.yaml files.|
+
+Options:
+
+| Param            | Description                              | Default value |
+| ---------------- | ---------------------------------------- | ------------- |
+| --no-panelconfig | Show check information                   | Enabled       |
+| --panelconfig    | Only show config file recomended content | Disabled      |
+| --cpath          | Specify path to config file              | PATH/TO/config.yaml |
+| --cname          | Specify name to config file              | config.yaml   |
+
+Alias: `teuton c foo`, `teuton -c foo`, `teuton --check foo`
+
+## Example
+
+```
+$ teuton check examples/02-target
+
++----------------------------+
+| GROUP: Learn about targets |
++----------------------------+
+(001) target      Create user obiwan
+      weight      2.0
+      run         'id obiwan' on localhost
+      expect      ["uid=", "(obiwan)", "gid="] (Array)
+
+(002) target      Delete user vader
+      weight      1.0
+      run         'id vader' on localhost
+      expect_fail
+
++--------------+-------+
+| DSL Stats    | Count |
++--------------+-------+
+| Groups       | 1     |
+| Targets      | 2     |
+| Runs         | 2     |
+|  * localhost | 2     |
++--------------+-------+
+[WARN] Configfile not found
+       .../examples/02-target/config.yaml
+[INFO] Recomended content:
+---
+global:
+cases:
+- tt_members: TOCHANGE
+```
+
+The check process notifies that
+* This test hasn't config file
+* and recommends content for our config file. But it isn't necessary for this example.
+* exit_code 0 = Syntax ok.
+* exit code 1 = Syntax ERROR.

data/docs/commands/config.md

@@ -0,0 +1,120 @@
+[<< back](../../README.md)
+
+# config
+
+_Help to create config file._
+
+Usage:
+* `teuton config DIRECTORY`
+* `teuton config --server DIRECTORY`
+
+## Suggest config content
+
+* This is our test file content.
+
+```ruby
+# File: examples/03-remote_hosts/start.rb`
+
+group "Remote host" do
+  target "Create user root"
+  run "id root", on: :host1
+  expect ["uid=", "(root)", "gid="]
+
+  target "Delete user vader"
+  run "id vader", on: :host1
+  expect_fail
+end
+
+play do
+  show
+  export
+end
+```
+
+* Run `teuton config examples/03-remote_hosts` to suggest config file content:
+
+``` 
+---
+global:
+cases:
+- tt_members: TOCHANGE
+  host1_ip: TOCHANGE
+  host1_username: TOCHANGE
+  host1_password: TOCHANGE
+```
+
+## Init Config Server
+
+_Initialize Config Server, so students connect and help to build config file content._
+
+* Project files:
+```
+foo
+├── config.yaml
+└── start.rb
+```
+
+```yaml
+# File: foo/config.yaml
+---
+global:
+cases:
+- tt_members: TOCHANGE
+  tt_moodle_id: TOCHANGE
+```
+
+* `teuton config --server foo`, init config server.
+```
+--------------------------------------------------
+   ConfigServer URL: http://192.168.1.42:8080
+
+   Project path : foo
+   Global params (0)
+   Cases params (2)
+   * tt_members
+   * tt_moodle_id
+--------------------------------------------------
+== Sinatra (v4.2.1) has taken the stage on 8080 for development with backup from Puma
+Puma starting in single mode...
+* Puma version: 7.1.0 ("Neon Witch")
+* Ruby version: ruby 3.2.8 (2025-03-26 revision 13f495dc2c) [x86_64-linux]
+*  Min threads: 0
+*  Max threads: 5
+*  Environment: development
+*          PID: 18938
+* Listening on http://0.0.0.0:8080
+Use Ctrl-C to stop
+```
+
+* Now students connect to host 192.168.1.42 and send their configuracion values.
+* Student host:
+
+![](images/config01.png)
+
+* Teacher host:
+
+![](images/config02.png)
+
+* When all students submit their data, the teacher presses CTRL-C to end the service
+* The received data is saved in separate files within the `config.d` subfolder
+* Project files:
+```
+foo
+├── config.d
+│   ├── from_127.0.0.1.yaml
+│   ├── from_192.168.1.14.yaml
+│   └── from_192.168.1.28.yaml
+├── config.yaml
+└── start.rb
+```
+
+* And now the main configuration file (config.yaml) has the following content:
+    * Global param `tt_include: config.d`. 
+    * No cases in main config file. Read case data from files into `config.d` subfolder.
+
+```yaml
+---
+global:
+  tt_include: config.d
+cases: []
+```

data/docs/commands/help.md

@@ -0,0 +1,37 @@
+[<< back](../../README.md)
+
+# help
+
+_Show help about command functions._
+
+Usage: 
+* `teuton help`
+* `teuton help FUNCTION_NAME`
+
+Alias: `teuton h`,`teuton -h`, `teuton --help`
+
+**Example**: `teuton help`
+```
+Commands:
+  teuton [run] [OPTIONS] DIRECTORY   # Run test from directory
+  teuton check [OPTIONS] DIRECTORY   # Check test and config file content
+  teuton config [OPTIONS] DIRECTORY  # Suggest configuration or run server
+  teuton help [COMMAND]              # Describe available commands or one specific command
+  teuton new DIRECTORY               # Create skeleton for a new project
+  teuton readme DIRECTORY            # Show README extracted from test contents
+  teuton version                     # Show the program version
+```
+
+**Example**: `teuton help config`
+```
+Usage:
+  teuton config [OPTIONS] DIRECTORY
+
+Options:
+  [--server], [--no-server], [--skip-server]  
+
+Description:
+  config DIRECTORY, "Suggest the content of the configuration file based on the test"
+
+  config --server DIRECTORY, "Init Config Server. Students connect and help to build config file content"
+```

data/docs/commands/new.md

@@ -0,0 +1,34 @@
+[<< back](../../README.md)
+
+# new
+
+_Create the skeleton of a new project._
+
+Usage: `teuton new DIRECTORY`
+
+Example:
+
+```console
+$ teuton new foo
+
+Creating foo project
+* Create dir        => foo
+* Create file       => foo/config.yaml
+* Create file       => foo/start.rb
+```
+
+This command will create the next structure:
+
+```
+foo
+├── config.yaml
+└── start.rb
+```
+
+| Type      | Path            | Description    |
+| --------- | --------------- | -------------- |
+| Directory | foo             | Base directory |
+| File      | foo/start.rb    | Main file with test definitions |
+| File      | foo/config.yaml | YAML configuration file |
+
+Alias: `teuton n foo`, `teuton -n foo`, `teuton --new foo`

data/docs/commands/readme.md

@@ -0,0 +1,52 @@
+[<< back](../../README.md)
+
+# readme
+
+_Show test info as README file. Useful for create a readme file for the exercise._
+
+Usage:
+* `teuton readme DIRPATH`
+* `teuton readme DIRPATH > README.md`
+
+This function reads test and config files, and generate Markdown output with guidelines and target descriptions about the exercise.
+
+Alias: `teuton r DIRPATH`, `teuton -r DIRPATH`, `teuton --readme DIRPATH`
+
+## Example
+
+Test content:
+```
+$ cat examples/02-target/start.rb
+
+group "Learn about targets" do
+  target "Create user obiwan", weight: 2
+  run "id obiwan"
+  expect ["uid=", "(obiwan)", "gid="]
+
+  target "Delete user vader"
+  run "id vader"
+  expect_fail
+end
+
+start do
+  show
+  export
+end
+```
+
+Generate test documentation: `teuton readme examples/02-target`
+
+---
+```
+Date   : 2025-12-02 16:00:09 +0000
+Teuton : 2.11.0
+```
+
+# Test name: 02-target
+
+## Learn about targets
+
+Go to [LOCALHOST](#required-hosts) host, and do next:
+* (x2.0) Create user obiwan.
+* (x1.0) Delete user vader.
+---

data/docs/commands/{run-tests.md → run.md}

@@ -1,5 +1,5 @@
 
-[<< back](README.md)
+[<< back](../../README.md)
 
 # Run test
 

data/docs/config_file.md

@@ -0,0 +1,125 @@
+[<< back](../README.md)
+
+# Config file
+
+By default, Teuton projects use `config.yaml` as configuration file.
+
+Our tests may or may not have a configuration file. It is common to have a configuration file to easily adapt the test execution to different hosts, environments or situations. For example: adapt the config file for each course for the different students we are going to evaluate.
+
+## Creating new project
+
+* Create a new project `teuton new foo`.
+```
+Creating foo project
+* Create dir        => foo
+* Create file       => foo/config.yaml
+* Create file       => foo/start.rb
+```
+
+* We now have the following files.
+```
+foo
+├── config.yaml
+└── start.rb
+```
+
+* Configuration file content.
+```yaml 
+# File: foo/config.yaml
+---
+global:
+cases:
+- tt_members: TOCHANGE
+```
+
+The configuration file is in YAML format with two main sections: `global` y `cases`. The `global` section can be empty. Parameters defined in the `global` section will be accessible to all cases.
+The `cases` section contains specific parameters for each case.
+
+## Global section vs cases section
+
+**Example:**
+
+```yaml
+# File: examples/03-remote_hosts/config.yaml
+---
+global:
+  host1_username: root
+cases:
+- tt_members: student_1
+  host1_ip: 192.168.1.201
+  host1_password: secret_1
+- tt_members: student_2
+  host1_ip: 192.168.1.202
+  host1_password: secret_2
+- tt_members: student_3
+  host1_ip: 127.0.0.1
+  host1_password: secret_3
+```
+
+* The parameter `host1_username` is defined in the global section, so all cases will read the same value. Example: `get(:host1_username) == "root"`.
+* The parameters `tt_members`, `host1_ip`, and `host1_password` are defined in each case. So, every student has diferents values. The student number 1 will have one value, student number 2 another, and so on.
+
+It is posible to add as many parameters as you need. But remember that parameters defined in the global section will be available to all students (cases), while parameters defined in the cases section will be specifically defined for each student (case).
+
+## Reserved params
+
+It is posible to add all the parameters you need into your configuration file, but some parameter names has special meaning. Reserved parameter names begin with prefix `tt_`.
+
+| Param name           | Section | Status       | Descripction |
+| -------------------- | ------- | ------------ | ------------ |
+| **tt_members**       | cases   | **Required** | Student name if it is an individual assignment or names of the members if it is a group assignment |
+ **tt_moodle_id**      | cases   | Optional     | Student identifier on the Moodle platform. Example: student's Moodle email address |
+| **tt_moodle_max_score** | global | Optional   | Default value: 100. The grades generated by Teuton have values ​​between 0 and 100. But by changing this parameter to 10, for exmaple, the values are adjusted to between 0 and 10 before saving the grades into the moodle.csv file |
+| **tt_include**       | global  | Optional     | The contents of the files within the directory defined by the parameter are added to our main configuration file |
+| **tt_sequence**      | global  | Optional     | By default, all cases are evaluated in parallel unless sequential mode is enabled. Sequential mode is useful for debugging processes.|
+| **tt_source_ip**     | cases   | Auto         | Automatically filled in during remote setup. This value is completed when the student sends their configuration remotely.|
+| **tt_source_file**   | cases   | Auto         | Automatically filled in during the configuration loading. This value is populated when the configuration files from the folder defined by the tt_include parameter are read. |
+| **tt_skip**          |         | Optional     | False by default. To skip a case and not evaluate it, set the value to true. |
+| **tt_testname**      | global  | Optional     | Customize your test name |
+
+## Host properties
+
+Parameters used to define the properties of each host must begin with an identifier (HOSTID).
+
+Lits of available host properties:
+
+| Param name      | Required | Default value | Description |
+| --------------- | -------- | ------------- | ----------- |
+| HOSTID_ip       | Yes      |               | IP address or hostname of the host identified by HOSTID |
+| HOSTID_username | No       |               | User account to access HOSTID |
+| HOSTID_password | No       |               | Password to access HOSTID |
+| HOSTID_protocol | No       | ssh           | Available options: ssh (default), telnet |
+| HOSTID_port     | No       | 22/23         | Default value: 22 (ssh), 23 (telnet) |
+| HOSTID_route    | No       |               | This option is used to configure a gateway to access HOSTID |
+
+We can create as many host configurations as different devices are required to complete the activity.
+
+If `HOSTID_password` is not defined, then SSH connection will use the SSH keys.
+
+**Example**: If each student needs two hosts for the activity, one web server and the other as web cliente, we need to define 2 hosts: one with HOSTID `server`and the other wiht HOSTID `client`:
+
+```yaml
+global:
+cases:
+- tt_members: student_1
+  server_ip: 192.168.13.1
+  server_username: root
+  server_password: server_secret_1
+  client_ip: 192.168.13.2
+  client_username: david
+  client_password: david_secret_1
+```
+
+Or we can use other names, for example one with HOSTID `host1` and the other with HOSTID `host2`.
+
+```yaml
+global:
+cases:
+- tt_members: student_1
+  host1_ip: 192.168.13.1
+  host1_username: root
+  host1_password: server_secret_1
+  host2_ip: 192.168.13.2
+  host2_username: david 
+  host2_password: david_secret_1
+```

data/docs/devel/README.md

@@ -0,0 +1,12 @@
+
+Development process:
+
+Process
+git clone REPO
+install ruby-dev or ruby-devel 
+debian => sudo apt install ruby-dev build-essential
+debian => ssh make gcc ruby-devel
+
+gem install bundler
+bundle install
+rake