# E2E AI Test Guide

Natural language test instructions for AI-driven tool validation.

## Purpose

E2E AI tests are markdown files containing natural language instructions that an AI can follow to validate tool behavior against a real Modyo platform.

## File Location

```
tests/e2e-ai/
├── CLAUDE.md           # Points here
├── {tool-name}.md      # Test scenarios
└── ...
```

## Test File Format

```markdown
# {tool-name} E2E AI Tests

## Tool Overview
Brief description of what the tool does.

## Test Platform
- Platform: `fed-team` (or other configured platform)

---

## {Category} Operations

### Scenario N: {Description}
**Instruction:**
> Natural language instruction for the AI to execute

**Expected Parameters:**
\`\`\`json
{ "action": "...", "param": "..." }
\`\`\`

**Validation:**
- [ ] Validation point 1
- [ ] Validation point 2

---

## Error Scenarios

### Scenario EN: {Error Description}
**Instruction:**
> Instruction that should produce an error

**Expected:** Error message description

---

## Test Cleanup
Instructions for cleaning up test data if needed.

---

**Total Scenarios:** X main + Y error = Z scenarios
```

## Writing Instructions

### Good Instructions
- Clear, unambiguous language
- Specific values when needed
- Reference existing resources by name/ID

### Bad Instructions
- Vague or ambiguous
- Missing required context
- Assuming prior state

## Example Scenarios

### CRUD Operations
```markdown
### Scenario 1: List Resources
**Instruction:**
> List all spaces in the fed-team platform

**Expected Parameters:**
\`\`\`json
{ "action": "list", "platformSlug": "fed-team" }
\`\`\`
```

### Smart Resolution
```markdown
### Scenario 5: Get by Name
**Instruction:**
> Get the space named "Marketing" from fed-team

**Expected Parameters:**
\`\`\`json
{ "action": "manage", "platformSlug": "fed-team", "identifier": "Marketing" }
\`\`\`
```

### Error Cases
```markdown
### Scenario E1: Missing Required Field
**Instruction:**
> Create a new space without providing a name

**Expected:** Validation error for missing name
```

## Running Tests

1. Configure platform in manager service
2. Read test file for tool
3. Execute each scenario
4. Validate results match expectations
5. Run cleanup if needed

## Coverage Goals

Each tool should have scenarios for:
- All supported actions
- Smart identifier resolution (when applicable)
- Pagination (for list actions)
- Error cases (validation, not found)
- Verification mode (when supported)