@devassure/cli 1.0.5 → 1.0.8

package/README.md

@@ -1,4 +1,4 @@
-# DevAssure CLI
+# DevAssure Agent CLI
 
 Command-line interface for DevAssure Testing Agent - Autonomous agent executing tests from natural language instructions.
 
@@ -62,8 +62,6 @@ Add test cases to the project by adding yaml files to the `.devassure/tests` fol
 
 Example test case file:
 
-```yaml
-
 ```yaml
 summary: Sample test case
 steps:
@@ -123,6 +121,7 @@ default:
 
 - **`devassure run-tests`** - Run tests using current directory as test cases directory
   - `--path <path>` - Project path (default: current directory)
+  - `--csv <path>` - Path to CSV file containing test cases (relative or absolute). Relative paths in order: current directory, `.devassure` are supported. File must exist and have `.csv` extension.
   - `--tag <tags>` / `--tags <tags>` - Comma-separated tag values (e.g., `--tag=tag1,tag2,tag3`)
   - `--priority <priorities>` / `--priorities <priorities>` - Comma-separated priority values (e.g., `--priority=P0,P1`)
   - `--folder <folders>` / `--folders <folders>` - Comma-separated folder paths (e.g., `--folder=admin/users,project/integration`)
@@ -224,12 +223,19 @@ devassure run-tests --tag=smoke --priority=P0 --folder=admin/users
 # Use raw filter string (takes precedence over other filter parameters)
 devassure run-tests --filter="tag = tag1,tag2 && priority = P0"
 
+# Use keyword search to filter tests (this will do text match on summary, steps, tags)
+devassure run-tests --filter="query = dashboard"
+
 # All parameters support plural forms
 devassure run-tests --tags=smoke,regression --priorities=P0,P1 --folders=admin/users
 
 # Run tests and archive reports to a folder (zip created after run completes)
 devassure run-tests --archive=./reports
 devassure run --archive=/tmp/archives
+
+# Run tests from a CSV file (relative path resolved from project path)
+devassure run-tests --csv=sample-tests.csv
+devassure run --csv=.devassure/sample-tests.csv
 ```
 
 ### Archiving and Opening Reports
@@ -258,6 +264,166 @@ devassure summary --session-id=<session-id>
 devassure summary --last --json
 ```
 
+## Sample configuration files
+
+All configuration files live under `.devassure/`. Below are sample contents for each file type.
+
+### app.yaml
+
+App description and rules for the agent:
+
+```yaml
+description: >
+  About my app
+  in multi line
+rules:
+  - User can't create more than 3 projects
+  - Any data deleted can't be restored
+```
+
+### personas.yaml
+
+(Optional) User personas used in tests:
+
+```yaml
+normal_user:
+  description: No admin access can do all other operations
+  age_group: 18-30
+  gender: M
+  region: USA
+admin:
+  description: Admin can add or delete other users and manage privileges
+deactivated_user:
+  description: Login is deactivated by admin
+expired_user:
+  description: License has expired
+```
+
+### test_data.yaml
+
+Default URL, users, and test data per environment:
+
+> If data keys are not present for a specific environment, the default data will be used.
+
+```yaml
+default:
+  url: 'http://localhost:3000'
+  users:
+    default:
+      user_name: 'user@test.com'
+      password: 12345678
+    admin:
+      user_name: 'admin@test.com'
+      password: 12345678
+  stripe_data:
+    allowed_card:
+      card: 4444 4444 4444 4444
+    wrong_cvv:
+      card: 1234 1234 1234 1234
+      expiry: 10/28
+      cvv: 123
+  test_otp: 1122
+uat:
+  url: 'http://uat.myapp.com'
+  users:
+    default:
+      user_name: 'user@uat.com'
+      password: 12345678
+    admin:
+      user_name: 'admin@uat.com'
+      password: 12345678
+  test_otp: 2345
+```
+
+### agent_instructions.yaml
+
+Instructions for the agent during test execution:
+
+```yaml
+instructions:
+  - Reload the app and retry if app shows warning server is busy
+  - Sign up a new user and proceed if any of the given logins are not working
+```
+
+### preferences.yaml
+
+Browser and execution preferences:
+
+```yaml
+browsers:
+  default:
+    browser: chromium
+    resolution: 1920 x 1200
+    headless: true
+workers: 2
+```
+
+### csv_mapping.yaml
+
+Column mappings when running tests from a CSV file (used with `--csv`). Maps CSV column names to test case fields:
+
+```yaml
+summary: Summary
+steps: Steps
+priority: Priority
+tags: Tags
+```
+
+### Sample test cases
+
+Example test case in `.devassure/tests/sample-test.yaml`:
+
+```yaml
+summary: Sample test case
+steps:
+  - Open the application url
+  - Verify if the page loads successfully
+  - Verify if there are no error messages
+priority: High
+tags:
+  - sample
+  - ui
+```
+
+Another example with multiple steps:
+
+```yaml
+summary: Login as admin and verify dashboard
+steps:
+  - Open the application url
+  - Log in with admin credentials from test data
+  - Verify dashboard loads and shows admin menu
+  - Log out
+priority: P0
+tags:
+  - smoke
+  - login
+  - admin
+```
+
+## FAQ
+
+**How to add new test cases?**  
+Add YAML files under `.devassure/tests/` (or `test/`), or use a CSV file with `--csv <path>` and optionally `.devassure/csv_mapping.yaml` to map columns to test fields.
+
+**Is test case YAML always needed or can we use CSV only?**  
+No. You can run tests from CSV only: use `devassure run-tests --csv=<path>` and configure `.devassure/csv_mapping.yaml` so your CSV columns map to summary, steps, priority, and tags.
+
+**What are the mandatory fields for a test case?**  
+For YAML test cases, `summary` and `steps` are required. `priority` and `tags` are optional. For CSV, the mapped columns must provide at least the equivalent of summary and steps.
+
+**How to add a new environment?**  
+Add a new top-level key (e.g. `uat`) and its data in `.devassure/test_data.yaml`. Then run with `devassure run-tests --environment=uat` (or `--environment uat`). If you omit `--environment`, the `default` key in test_data.yaml is used.
+
+**What are the supported browsers?**  
+Supported browsers are Chromium, Chrome, Edge. Controlled by `.devassure/preferences.yaml` under `browsers.default.browser`. The default is `chromium`. See the preferences.yaml section above for the structure.
+
+**How to run with headless mode?**  
+In `.devassure/preferences.yaml`, set `browsers.default.headless: true`.
+
+**How to run the tests in Continuous Integration?**  
+Use `devassure add-token <your-token>` to authenticate (no browser). Then run `devassure run-tests` with the options you need (e.g. `--csv`, `--filter`, `--tag`, `--priority`, `--archive` for saving report zips). You can retain only recent sessions with `devassure cleanup --retain-days 7` or `--retain-sessions 10`.
+
 ## Support
 
 For more information, visit [DevAssure](https://devassure.io) or run `devassure help` for command-specific help.