# Quick Start Guide - Hyly E2E Plugin

Get up and running with the Hyly E2E Plugin in 10 minutes.

## Prerequisites

Before starting, ensure you have:
- ✅ Installed the plugin (see `INSTALL.md`)
- ✅ Configured `.env` with Notion credentials
- ✅ Notion database created and shared with integration

## Your First Test Automation Pipeline

### Step 1: Prepare Your Requirements in Notion

Create a Notion page with your feature requirements. Example structure:

```
Feature: User Dashboard

## User Stories
- As a user, I want to view my dashboard so that I can see my data
- As a user, I want to filter data so that I can focus on specific items

## Acceptance Criteria
- Dashboard loads within 3 seconds
- All widgets display correctly
- Filters apply immediately

## Test Scenarios
- Login and navigate to dashboard
- Verify all widgets are visible
- Apply filters and verify results
```

### Step 2: Run the Pipeline

In Claude Code CLI:

```
User: "Run the test automation pipeline"
```

Claude will ask for your Notion URL:

```
Claude: "Please provide the Notion URL to process for this pipeline run"
```

Paste your Notion page URL:

```
User: "https://www.notion.so/yourworkspace/your-page-id"
```

### Step 3: Review Each Stage

The pipeline will execute 6 stages with approval gates:

#### 🔹 Stage 1: Requirements Extraction

Claude extracts requirements from Notion and presents a summary:

```
Stage 1 Complete - Approval Required

Summary: Extracted 5 user stories, 8 acceptance criteria, 4 test scenarios
Output Files:
  - test-requirements/requirements.json
  - test-requirements/requirements-summary.md
Key Results: Feature covers dashboard functionality, filters, and widgets

Do you approve Stage 1 and want to proceed to Stage 2?
```

**Response**: `yes`

#### 🔹 Stage 2: Test Case Generation

Claude generates comprehensive test cases:

```
Stage 2 Complete - Approval Required

Summary: Generated 6 test cases with 15-20 steps each
Output Files:
  - test-plans/test-plan.json
Key Results:
  - TC-001: Login and Dashboard Navigation
  - TC-002: Widget Display Verification
  - TC-003: Filter Functionality
  - TC-004: Dashboard Export
  - TC-005: Dashboard Creation
  - TC-006: Dashboard Deletion

Do you approve Stage 2 and want to proceed to Stage 3?
```

**Review the test cases**, then approve:

**Response**: `yes`

#### 🔹 Stage 3: Test Case Registration

Claude will ask which test cases to register:

```
Which test cases would you like to register?
- Type 'all' to register all test cases
- Type specific numbers (e.g., '1,3,5')
- Type a range (e.g., '2-4')
```

**Response**: `all` (or select specific cases)

Claude registers test cases to Notion:

```
Stage 3 Complete - Approval Required

Summary: Registered 6 test cases to Notion
Output Files:
  - test-registry/registration-summary.json
Key Results: All test cases have Notion page IDs

Do you approve Stage 3 and want to proceed to Stage 4?
```

**Response**: `yes`

#### 🔹 Stage 4: Playwright Script Generation

Claude generates production-ready test scripts:

```
Stage 4 Complete - Approval Required

Summary: Generated 6 Playwright test scripts
Output Files:
  - tests/dashboard-navigation.spec.ts
  - tests/widget-display.spec.ts
  - tests/filter-functionality.spec.ts
  - tests/dashboard-export.spec.ts
  - tests/dashboard-creation.spec.ts
  - tests/dashboard-deletion.spec.ts
  - test-generation/generation-summary.json

Do you approve Stage 4 and want to proceed to Stage 5?
```

**Response**: `yes`

#### 🔹 Stage 5: Script Review

Claude asks for a hint file:

```
Do you have any hint file for me to use?
```

**Response**: `master-hints.md` (or choose appropriate hint file)

Claude reviews all scripts:

```
Stage 5 Complete - Approval Required

Summary: Reviewed 6 scripts, average score: 82/100
Output Files:
  - test-reviews/review-summary.json
Key Results:
  - 4 scripts passed review (score > 80)
  - 2 scripts improved automatically (auto-fix triggered)
  - All scripts now ready for execution

Do you approve Stage 6 and want to proceed to Stage 7?
```

**Response**: `yes`

#### 🔹 Stage 7: Test Execution

Claude executes all tests and reports results:

```
Stage 7 Complete

Summary: Executed 6 test cases
Results:
  - Passed: 5
  - Failed: 1
  - Skipped: 0
  - Duration: 3m 24s
Output Files:
  - test-results/executions/execution-summary.json
  - Notion database updated with results

Check your Notion database for detailed execution results.
```

### Step 4: Review Results

1. **Open your Notion database**
2. **View test execution results** with pass/fail status
3. **Check failed tests** for error details
4. **Use test-debugger skill** to fix failing tests

## Using Individual Skills

### Selector Finder Skill

Find selectors for your application elements:

```
User: "Find selector for the 'Add to Cart' button"

Claude:
- Inspects your live application
- Recommends: page.getByRole('button', { name: 'Add to Cart' })
- Provides alternatives and usage examples
```

### Test Debugger Skill

Debug a failing test:

```
User: "Debug the failing checkout test"

Claude:
- Reads test-results/results.json
- Analyzes error: "Timeout waiting for element"
- Identifies: Selector issue on line 45
- Provides fix: Replace selector with semantic alternative
```

## Common Workflows

### Workflow 1: Generate Tests for New Feature

1. Document requirements in Notion
2. Run pipeline with Notion URL
3. Approve each stage
4. Execute generated tests
5. Fix any failures using test-debugger

### Workflow 2: Find Reliable Selectors

1. Invoke selector-finder skill
2. Specify element to find
3. Get semantic selector recommendation
4. Update page objects with new selector

### Workflow 3: Debug Failing Tests

1. Run tests and note failures
2. Invoke test-debugger skill
3. Get root cause analysis
4. Apply recommended fixes
5. Re-run tests to verify

### Workflow 4: Improve Existing Tests

1. Run Stage 5 (review) on existing tests
2. Provide appropriate hint file
3. Review improvement suggestions
4. Apply fixes using test-debugger
5. Update tests based on recommendations

## Tips for Success

### Writing Good Requirements

✅ **DO**:
- Write clear user stories
- Include specific acceptance criteria
- Describe the UI interactions
- Mention expected outcomes

❌ **DON'T**:
- Use vague descriptions
- Skip acceptance criteria
- Focus only on backend logic
- Forget to mention UI elements

### Choosing Hint Files

| Hint File | Use When |
|-----------|----------|
| `master-hints.md` | General/comprehensive review |
| `default-hints.md` | Basic Playwright best practices |
| `login-test-hints.md` | Authentication/login tests |
| `dashboard-widget-hints.md` | Dashboard/widget features |
| `export-test-hints.md` | Export/download functionality |
| `filter-hints.md` | Filter components |
| `table-explorer-hints.md` | Data tables |

### Improving Generated Tests

If generated tests are too generic:

1. **Add more details to requirements** in Notion
2. **Reference your application's UI** specifically
3. **Run Stage 2 again** with improved requirements
4. **Use test-debugger** to fix specific issues

### Handling Approval Gates

Each stage requires explicit approval:
- Type `yes` to approve and continue
- Type `no` to reject (Claude will ask what to improve)
- Review outputs before approving
- Check generated files for quality

## Next Steps

### Customize for Your Project

1. **Create custom hint files** for your application
2. **Document your selector patterns** in hints
3. **Add your page objects** to reference files
4. **Update credentials** in `.env`

### Explore Advanced Features

1. **Auto-fix loop** in Stage 5 (automatic improvements)
2. **Pattern learning** from existing tests
3. **Live DOM inspection** with selector-finder
4. **Iterative review** (up to 2 auto-fix iterations)

### Integrate with CI/CD

```yaml
# Example GitHub Actions workflow
name: E2E Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install
      - run: npx playwright install
      - run: npx playwright test
```

## Troubleshooting Quick Fixes

### Tests Not Generating
```
# Check registration summary has valid data
cat test-registry/registration-summary.json

# Re-run Stage 3 if needed
"Run Stage 3 of the pipeline"
```

### Selectors Not Found
```
# Use selector-finder to find correct selector
"Find selector for the [element name]"

# Update page object with new selector
```

### Tests Failing
```
# Use test-debugger to analyze
"Debug the failing [test name]"

# Apply recommended fixes
```

### Pipeline Stuck
```
# Check what stage you're at
"What stage is the pipeline currently on?"

# Continue from current stage
"Continue with Stage [X]"
```

## Getting Help

### Documentation
- `README.md` - Full plugin documentation
- `INSTALL.md` - Installation guide
- `CHANGELOG.md` - Version history

### Resources
- **Hint Files**: Check `hints/` folder for examples
- **Agent Docs**: Read `agents/` files for agent details
- **Skills**: Review `skills/` for skill documentation

### Support
- **GitHub Issues**: https://github.com/hyly-ai/hyly-e2e-plugin/issues
- **Email**: support@hyly.ai
- **Documentation**: https://docs.hyly.ai/e2e-plugin

---

**Congratulations!** 🎉

You've successfully run your first AI-powered test automation pipeline.

**Next**: Explore the skills, customize hint files, and integrate with your CI/CD pipeline.