update docs

docs/02-global-config.md

@@ -8,17 +8,23 @@ It contains general settings, endpoints, validator names, global variables, and
 The configuration file is structured as follows:
 
 ```yaml
-endpoints:
-  - name: "node-1"
-    executionUrl: "http://127.0.0.1:8545"
-    consensusUrl: "http://127.0.0.1:5052"
+coordinator:
+  maxConcurrentTests: 1 # max number of tests to run concurrently
+  testRetentionTime: 14d # delete test run (logs + status) after that duration
 
 web:
   server:
     host: "0.0.0.0"
     port: 8080
+  api:
+    enabled: true # enable rest api
   frontend:
-    enabled: true
+    enabled: true # enable web ui
+
+endpoints:
+  - name: "node-1"
+    executionUrl: "http://127.0.0.1:8545"
+    consensusUrl: "http://127.0.0.1:5052"
 
 validatorNames:
   inventoryYaml: "./validator-names.yaml"
@@ -48,12 +54,14 @@ externalTests:
 
 ```
 
+- **`coordinator`**:\
+  Manages the execution of tests, specifying the maximum number of tests that can run concurrently (`maxConcurrentTests`) and how long to retain test runs, including logs and status, after completion (`testRetentionTime`).
 
 - **`endpoints`**:\
   A list of Ethereum consensus and execution clients. Each endpoint includes URLs for both RPC endpoints and a name for reference in subsequent tests.
 
 - **`web`**:\
-  Configurations for the web frontend, detailing server host and port settings.
+  Configurations for the web api & frontend, detailing server host and port settings.
 
 - **`validatorNames`**:\
   Defines a mapping of validator index ranges to their respective names. \
@@ -75,3 +83,4 @@ externalTests:
 - **`externalTests`**:\
   This feature enables the integration of tests that are defined in separate files, fostering a modular and scalable test configuration approach. \
   It allows for better organization and management of complex testing scenarios.
+

docs/03-rest-api.md

@@ -0,0 +1,18 @@
+# REST API
+
+When enabled, Assertoor offers a REST API that facilitates interaction with the testing framework, enabling users to programmatically fetch statuses and results of tests and tasks. Additionally, the API supports basic operations such as scheduling or canceling test runs, making it a powerful tool for automating and integrating Assertoor into broader testing and CI/CD pipelines.
+
+## Key Features of the REST API:
+
+- **Status and Results Retrieval**: Users can query the API to obtain detailed status updates and results for both tests and individual tasks, allowing for real-time monitoring and analysis of test executions.
+
+- **Test Management**: The API supports scheduling new test runs and canceling existing ones, providing flexibility in managing test execution according to dynamic testing requirements or conditions.
+
+- **Integration Friendly**: The REST API's standard interface ensures it can be easily integrated with external tools and systems, enhancing Assertoor's utility in automated testing environments.
+
+### Accessing the API Documentation:
+
+The detailed API documentation, including all supported endpoints, request formats, and response structures, is accessible via the Assertoor web UI. This comprehensive documentation is designed to be user-friendly, offering examples and explanations to facilitate easy adoption and integration of the API into your workflows.
+
+To access the API documentation, ensure the Assertoor web interface is enabled and navigate to the designated URL. The documentation provides interactive examples and the ability to test endpoints directly from your browser, offering a hands-on approach to learning and utilizing the REST API.
+

docs/04-test-config.md

@@ -0,0 +1,71 @@
+# Test Configuration
+
+Assertoor allows you to set up tests to check various aspects of the Ethereum network. You can organize these tests in two ways: directly within your main configuration file or through external files for more complex scenarios. Here’s how it works:
+
+## Local Tests
+
+Local tests are defined in your main Assertoor configuration file. You can list tasks that you want to run as part of your test, along with any cleanup tasks to run afterward, regardless of whether your test passes or fails.
+
+```yaml
+- id: "test1"
+  name: "Test with local tasks"
+  timeout: "48h"
+  config: {}
+  tasks: []
+  cleanupTasks: []
+  schedule:
+    startup: true
+    cron:
+      - "* * * * *"
+ ```
+
+- **`id`**:\
+  A unique identifier for your test.
+- **`name`**:\
+  The test's name.
+- **`timeout`**:\
+  How long to run the test before stopping it. This is optional.
+- **`config`**:\
+  A place to set static variables for your test. Optional.
+- **`tasks`**:\
+  The tasks to run for your test.
+- **`cleanupTasks`**:\
+  Tasks that clean up after your main tasks. These run no matter if the main tasks pass or fail. This is optional.
+- **`schedule`**:\
+  Determines when your test runs. You can set it to start when Assertoor starts or on a schedule using cron format. This is optional.
+
+## External Tests
+
+External test playbooks, loaded via the `file` attribute in the Assertoor configuration, follow a structured format. These playbooks allow for defining comprehensive tests with specific tasks, variable configurations, and scheduling options.
+
+**Example External Test Playbook:**
+
+```yaml
+id: test1
+name: "Test 1"
+timeout: 1h
+config:
+  # walletPrivkey: ""
+  # validatorPairNames: []
+configVars: {}
+tasks: []
+cleanupTasks: []
+schedule:
+  startup: true
+  cron:
+    - "* * * * *"
+```
+
+**Key Properties Explained:**
+
+- **`id`**: A unique identifier for the test, allowing for easy reference.
+- **`name`**: The descriptive name of the test, providing clarity on its purpose.
+- **`timeout`**: Specifies the duration after which the test should be considered failed if not completed.
+- **`config`**: Static variable configuration, where you can define variables directly used by the test.
+- **`configVars`**: Dynamic variable configuration that copies variables from the global scope, supporting complex expressions through jq syntax.
+- **`tasks`**: The list of tasks to be executed as part of the test. Refer to the task configuration section for detailed task structures.
+- **`cleanupTasks`**: Specifies tasks to be executed after the main tasks, regardless of their success or failure.
+- **`schedule`**: Determines when the test should be run. If omitted, the test is scheduled to start upon Assertoor startup. It also supports cron expressions for more precise scheduling.
+
+This format provides a flexible and powerful way to define tests outside the main configuration file, allowing for modular test management and reusability across different scenarios or environments.
+