OpenTester-Skills / rules

---
description: OpenTester Testing Rules
globs:
  - "**/*.test.yaml"
  - "**/tests/**"
  - "**/*_test.py"
alwaysApply: true
---

# OpenTester Testing Guidelines

## When to Use

When the user mentions:
- "/test" or "/t" - Create tests for code changes
- "run tests" - Execute existing tests
- "validate" - Check test syntax
- "delete project" or "delete test" - Remove test data
- Test files are modified

## DSL Validation Workflow (CRITICAL)

**ALWAYS validate DSL before saving!**

```
1. Generate DSL YAML
2. Call opentester.validateDSL(dsl_yaml) to check syntax
3. IF validation fails:
   - Read the error message
   - Fix the DSL (common: use assertion object instead of direct type/value)
   - Call validateDSL again
   - REPEAT until validation passes
4. IF validation passes:
   - Call opentester.saveCase to store the test
5. Call opentester.runCase to execute
```

## DSL Format

### Basic Structure
```yaml
version: "1.0"
meta:
  name: "Test Name"
  description: "What this test verifies"

target:
  type: cli  # cli, api, or tui

timeout: 10

steps:
  - name: "Step description"
    action: exec|assert|wait
    # action-specific fields
```

### Action: exec
```yaml
- name: "Execute command"
  action: exec
  command: "echo Hello"           # CLI
  # OR for API:
  method: GET
  path: "/endpoint"
```

### Action: assert (CRITICAL - USE assertion OBJECT!)

❌ WRONG - assert with direct type/value:
```yaml
- action: assert
  type: stdout_contains      # ❌ Wrong!
  value: "text"              # ❌ Wrong!
```

✅ CORRECT - assert with assertion object:
```yaml
- name: "Verify output"
  action: assert
  assertion:                 # ✅ Correct!
    type: stdout_contains
    expected: "text"         # ✅ Use 'expected', not 'value'!
```

**CLI Assertions:**
```yaml
- action: assert
  assertion:
    type: exit_code|stdout_contains|stderr_contains|stdout_matches|stderr_empty
    expected: value
```

**API Assertions:**
```yaml
- action: assert
  assertion:
    type: status_code|json_path
    path: "$.data.name"      # Required for json_path
    expected: value
```

**TUI Assertions:**
```yaml
- action: assert
  assertion:
    type: screen_contains|cursor_at|screen_stable
    expected: value
```

### Action: wait
```yaml
- name: "Wait"
  action: wait
  duration: 5
```

### Variables
- `${vars.name}` - Reference variable
- `${env.VAR}` - Environment variable

## Commands

| User Command | Response |
|-------------|----------|
| `/test [feature]` | Create and run tests |
| `/test-quick` | Quick test without PRD |
| `run tests` | Execute existing tests |
| `debug [test]` | Analyze failures |
| `delete project <id>` | Delete project and all its test cases |
| `delete test <id>` | Delete a specific test case |
| `list templates` | Show all DSL templates |
| `use template <id>` | Create test from a template |
| `save template` | Save test case as template |

## Delete Operations

### Delete Project Workflow
1. Call `opentester.listProjects` to show available projects
2. Call `opentester.getProject(project_id)` to show details
3. **CONFIRM** with user: "This will permanently delete the project and ALL its test cases"
4. Call `opentester.deleteProject(project_id)`
5. Report result

### Delete Test Case Workflow
1. Call `opentester.getProject(project_id)` to find the case
2. **CONFIRM** with user: Show case name and details
3. Call `opentester.deleteCase(project_id, case_id)`
4. Verify by calling `opentester.getProject(project_id)` again
5. Report result

### Template Workflows

**List and Use Template:**
1. Call `opentester.listTemplates(category?, target_type?, tag?)`
2. Call `opentester.getTemplate(template_id)` to see variables
3. Ask user for variable values
4. Call `opentester.instantiateTemplate(template_id, project_id, case_name, variables)`

**Create Template from Case:**
1. Call `opentester.getProject(project_id)` to find the case
2. Ask user which values should become `${variable}` placeholders
3. Call `opentester.createTemplateFromCase(project_id, case_id, template_name, variable_mappings)`

**Template Variables:**
- Use `${var_name}` syntax in DSL templates
- Variables are replaced when instantiating
- Common variables: `${base_url}`, `${endpoint}`, `${timeout}`, `${test_name}`

## Common Validation Errors

| Error | Fix |
|-------|-----|
| `Unknown assertion type` | Use `assertion: { type: ..., expected: ... }` instead of direct `type/value` |
| `field required` | Add missing required field |
| `YAML error` | Fix indentation |