@devassure/cli 1.0.10 → 1.0.13

package/README.md

@@ -1,6 +1,6 @@
-# DevAssure AI Testing Agent CLI
+# DevAssure Invisible (QA) Agent CLI
 
-Command-line interface for DevAssure Testing Agent - Autonomous agent executing tests from natural language instructions.
+Command-line interface for DevAssure Invisible (QA) Agent - executes end to end UI tests from natural language instructions and csv files. CLI can be used to run tests by integrating into CI/CD pipelines.
 
 ## Prerequisites
 - Node.js 18+
@@ -155,7 +155,7 @@ default:
 
 ### Maintenance
 
-- **`devassure cleanup`** - Clean up old sessions
+- **`devassure cleanup`** - Clean up execution history to free up space
   - `--retain-days <days>` - Retain sessions from the last N days
   - `--retain-sessions <count>` - Retain the last N sessions
   - If no options provided, prompts to delete all sessions
@@ -451,6 +451,193 @@ steps:
   - Verify if the manager user is added
 ```
 
+## Library tools
+
+Library tools are inbuilt tools that users can include in the project by listing the required tools in a `library.yaml` file.
+
+**Sample library.yaml** (e.g. `.devassure/library.yaml`):
+
+```yaml
+tools:
+  - 'authenticator'
+  - 'faker:*'
+```
+
+### faker
+
+Faker provides realistic synthetic data generators for tests:
+
+| Tool-key | Description |
+|------|-------------|
+| `*first_name*` | Generate a random first name |
+| `*last_name*` | Generate a random last name |
+| `*full_name*` | Generate a random full name |
+| `*email*` | Generate a random email address |
+| `*phone*` | Generate a random phone number |
+
+### authenticator
+
+Authenticator provides TOTP (Time-based One-Time Password) helpers:
+
+| Tool-key | Description |
+|------|-------------|
+| `get_authenticator_otp` | Generate a TOTP code from an authenticator secret. The authenticator secret must be passed to generate the code. |
+
+## Tools
+
+Tools let you run custom commands or programs and consume their output. The configuration lives in `.devassure/tools/index.yaml`.
+
+**Requirement:** `tools/index.yaml` is required for tools to work. It must exist at `.devassure/tools/index.yaml` (relative to your project path).
+
+Tools can run any command or program; the runner executes the command and consumes its output. For custom code or scripts, put the tool code inside the `.devassure/tools` folder and reference the execution command in `tools/index.yaml` (e.g. `exec: node script.js` or `exec: npm run myTool`).
+
+**Note:** You can use any programming language or program. You are responsible for setting up dependencies (e.g. Node.js, Python, venv, system binaries).
+
+### Mandatory fields
+
+Each tool must have **name**, **description**, and **exec**:
+
+| Field | Description |
+|-------|-------------|
+| **name** | Unique identifier for the tool (e.g. used when invoking the tool). |
+| **description** | Short description of what the tool does. |
+| **exec** | Command(s) to run. Can be a single line or a multi-line string. Supports `${argName}` substitution for args. |
+
+Optional per-tool fields include **cwd** and **args** (see below).
+
+**Minimal example:**
+
+```yaml
+tools:
+  - name: "getProjectDetails"
+    description: "Get project details from api"
+    cwd: "api-tools"
+    args:
+      - name: projectId
+        type: string
+    exec: npm run getProjectDetails ${projectId}
+```
+
+- **cwd** (optional): Working directory for the command. It is relative to the **tools folder** (`.devassure/tools`). If omitted, the working directory is the tools folder. Absolute paths are also supported.
+- **args** (optional): List of parameters. Each has `name` and `type`; see [Supported arg types and optional args](#supported-arg-types-and-optional-args) below.
+
+### Optional top-level configuration: settings and setup
+
+**settings:** Default options applied to every **tool** run and every **setup** step. For all fields except **env**, the value on the tool or setup step is used when present; values in `settings` are fallback when the tool or step does not define that field. For **env**, the list of environment variables is **merged**: settings env vars and the tool/setup step env vars are combined (tool/setup entries override settings when the same key is used).
+
+**setup:** Optional list of steps run once per session before scenario executions start (e.g. install dependencies). Each step can specify `name`, `cwd`, `exec`, and any of the settings fields; inheritance from `settings` applies when a step omits a field.
+
+### cwd behavior
+
+- **Relative:** Resolved from the **tools folder** (e.g. `cwd: "api-tools"` → `.devassure/tools/api-tools`).
+- **Default:** If `cwd` is not provided, the working directory is the tools folder.
+- **Absolute:** Absolute paths are supported (e.g. `cwd: "/opt/scripts"`).
+
+### Settings and tool/setup options
+
+| Option | Applies to | Description |
+|--------|------------|-------------|
+| **timeoutSec** | Tool / setup | Maximum execution time in seconds (e.g. `10`). |
+| **output.start** / **output.end** | Tool / setup | Markers in stdout; only content **between** these markers is captured as the tool output. Strongly recommended when the process prints a lot of extra content (logs, progress). Your script should print the actual result between these markers. |
+| **env** | Tool / setup | List of `KEY: value` environment variables added or overridden for the process. |
+| **ignore_failure** | Tool / setup | If `true`, a non-zero exit or failure does not fail the run (e.g. optional setup). Default is `false`. |
+
+#### Output start and end markers
+
+When the command prints a lot of unwanted content (logs, progress, debug), use **output.start** and **output.end** in `settings` (or on the tool). The runner captures only the stdout between these two markers. Print the markers and the necessary output from your script.
+
+**JavaScript example:** print the markers, then the result, then the end marker:
+
+```javascript
+// In your script (e.g. getProjectDetails.js)
+const startMarker = "__TOOL_OUTPUT_START__";
+const endMarker = "__TOOL_OUTPUT_END__";
+
+// ... do work, then:
+console.log(startMarker);
+console.log(JSON.stringify(result));
+console.log(endMarker);
+```
+
+In `tools/index.yaml` you would set `output.start` and `output.end` to match (e.g. `__TOOL_OUTPUT_START__` and `__TOOL_OUTPUT_END__`).
+
+### Supported arg types and optional args
+
+**Supported types:** `string`, `number`, `boolean`, `object`. Use `type` in each arg.
+
+**Optional args:** Add `optional: true` to an arg. If not provided, it may be omitted or passed empty depending on how you use it in `exec` (e.g. `"${projectName}"` for an optional string).
+
+**Example with multiple types and one optional arg:**
+
+```yaml
+tools:
+  - name: "exampleTool"
+    description: "Example with string, number, boolean, object args"
+    args:
+      - name: id
+        type: string
+      - name: count
+        type: number
+      - name: verbose
+        type: boolean
+      - name: options
+        type: object
+      - name: projectName
+        type: string
+        optional: true
+    exec: node run.js ${id} ${count} ${verbose} "${options}" "${projectName}"
+```
+
+### exec format
+
+- **Single line:** `exec: npm run getProjectDetails ${projectId}`
+- **Multi-line:** Use YAML multi-line (e.g. `exec: |` with following lines). Useful for running several commands in sequence (e.g. warmup, main command, cleanup):
+
+```yaml
+exec: |
+  npm run warmupTestingProcess
+  npm run getProjectDetails ${projectId} "${projectName}"
+  npm run cleanupTestingProcess
+```
+
+### Full example (tools/index.yaml)
+
+The following example shows **settings** (timeoutSec, output markers, env, ignore_failure), **setup** (one step with cwd and exec), and **tools** with optional arg and multi-line exec:
+
+```yaml
+settings:
+  timeoutSec: 10
+  output:
+    start: "__TOOL_OUTPUT_START__"
+    end: "__TOOL_OUTPUT_END__"
+  env:
+    - BUILD_ENV: "dev"
+    - DB_NAME: "legacy-db"
+  ignore_failure: false
+setup:
+  - name: "Install dependencies"
+    cwd: "api-tools"
+    exec: "npm install"
+tools:
+  - name: "getProjectDetails"
+    description: "Get project details from api"
+    cwd: "api-tools"
+    args:
+      - name: projectId
+        type: string
+      - name: projectName
+        type: string
+        optional: true
+    exec: |
+      npm run warmupTestingProcess
+      npm run getProjectDetails ${projectId} "${projectName}"
+      npm run cleanupTestingProcess
+```
+
+## Proxy
+
+If the `HTTP_PROXY` or `HTTPS_PROXY` environment variables are set, the CLI will use them to proxy requests.
+
 ## FAQ
 
 **How to add new test cases?**