# Installation Guide - Hyly E2E Plugin

This guide will walk you through installing and configuring the Hyly E2E Plugin for Claude Code.

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Installation Methods](#installation-methods)
3. [Configuration](#configuration)
4. [Verification](#verification)
5. [Troubleshooting](#troubleshooting)

## Prerequisites

Before installing the plugin, ensure you have:

### Required

- **Claude Code CLI** - Latest version installed
- **Node.js** - Version 18.0.0 or higher
- **npm** or **yarn** - Package manager
- **Playwright** - Version 1.40.0 or higher

### Optional (for full functionality)

- **Notion Account** - For requirements extraction and test registration
- **Chrome DevTools MCP Server** - For selector-finder skill

## Installation Methods

### Method 1: Install from Marketplace (Recommended)

Once the plugin is published to a marketplace:

```bash
# Install from the official Hyly marketplace
/plugin install hyly-e2e-plugin@hyly-ai
```

### Method 2: Install from GitHub

```bash
# Install directly from GitHub repository
/plugin install github:hyly-ai/hyly-e2e-plugin
```

### Method 3: Manual Installation

1. **Download the Plugin**
   ```bash
   # Clone the repository
   git clone https://github.com/hyly-ai/hyly-e2e-plugin.git

   # Or download and extract the ZIP file
   ```

2. **Copy to Your Project**
   ```bash
   # Copy the plugin folder to your project root
   cp -r hyly-e2e-plugin /path/to/your/project/
   ```

3. **Install via Local Path**
   ```bash
   # In Claude Code CLI, install from local path
   /plugin install ./hyly-e2e-plugin
   ```

4. **Install Dependencies**
   ```bash
   cd hyly-e2e-plugin
   npm install
   ```

## Configuration

### Step 1: Create Environment File

Create a `.env` file in your project root:

```bash
# Navigate to your project root
cd /path/to/your/project

# Create .env file
touch .env
```

### Step 2: Add Environment Variables

Edit the `.env` file and add:

```env
# Notion Integration (Required for pipeline)
NOTION_API_KEY=your_notion_api_key_here
NOTION_DATABASE_ID=your_notion_database_id_here

# Test Credentials (Optional - customize for your app)
TEST_EMAIL=your_test_email@example.com
TEST_PASSWORD=your_test_password_here

# Application URLs (Optional - customize for your app)
APP_URL=https://your-app-qa.example.com
LOGIN_URL=https://accounts-qa.example.com
```

### Step 3: Setup Notion Integration

#### A. Create Notion Integration

1. Go to https://www.notion.so/my-integrations
2. Click **"New integration"**
3. Fill in the details:
   - **Name**: E2E Test Automation (or your preferred name)
   - **Associated workspace**: Select your workspace
   - **Type**: Internal Integration
4. Click **"Submit"**
5. Copy the **Internal Integration Token** (starts with `secret_`)
6. Paste it in your `.env` file as `NOTION_API_KEY`

#### B. Create Test Case Database

1. Open Notion and create a new database
2. Add the following properties:

   | Property Name | Type | Options (for Select/Multi-select) |
   |--------------|------|-----------------------------------|
   | Name | Title | - |
   | Test ID | Text | - |
   | Status | Select | Pending, Passed, Failed, Skipped |
   | Priority | Select | High, Medium, Low |
   | Tags | Multi-select | (Add as needed: Smoke, Regression, etc.) |
   | Description | Text | - |
   | Pre-conditions | Text | - |
   | Steps | Text | - |
   | Expected Results | Text | - |
   | Date | Date | - |
   | Duration | Text | - |
   | Passed | Number | - |
   | Failed | Number | - |
   | Skipped | Number | - |

#### C. Share Database with Integration

1. Open your test case database in Notion
2. Click the **"Share"** button (top right)
3. Click **"Invite"**
4. Search for your integration name
5. Select it and click **"Invite"**

#### D. Extract Database ID

1. Open your database in Notion
2. Look at the URL: `https://www.notion.so/workspace/DATABASE_ID?v=...`
3. Copy the `DATABASE_ID` portion (32-character string)
4. Paste it in your `.env` file as `NOTION_DATABASE_ID`

Example:
```
https://www.notion.so/myworkspace/24f1db9ba44180adb6f1dc75ab88a8f1?v=...
                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                 This is your DATABASE_ID
```

### Step 4: Setup Chrome DevTools MCP (Optional)

For the `selector-finder` skill to work:

1. **Install Chrome DevTools MCP Server** (if not already installed)

   Follow the instructions at: https://github.com/anthropics/chrome-devtools-mcp

2. **Configure in Claude Code**

   The MCP server should be automatically detected by Claude Code.

3. **Verify Connection**
   ```bash
   # In Claude Code CLI
   /mcp list

   # Should show chrome-devtools in the list
   ```

### Step 5: Install Project Dependencies

If you're setting up Playwright for the first time:

```bash
# Install Playwright
npm install -D @playwright/test

# Install browsers
npx playwright install

# Install Playwright dependencies
npx playwright install-deps
```

## Verification

### Verify Plugin Installation

```bash
# List installed plugins
/plugin list

# Should show hyly-e2e-plugin in the list
```

### Verify Skills

```bash
# Check available skills
/skill list

# Should show:
# - selector-finder
# - test-debugger
```

### Verify Agents

Try invoking the pipeline orchestrator:

```bash
# In Claude Code conversation
"Run the test automation pipeline"

# Should prompt you for a Notion URL
```

### Test Notion Connection

Create a simple test to verify Notion connection:

```bash
# In Claude Code conversation
"Extract requirements from this Notion page: [YOUR_NOTION_URL]"

# Should successfully extract and display requirements
```

### Test Selector Finder

```bash
# In Claude Code conversation
"Find selector for the login button"

# Should use Chrome DevTools to inspect and recommend selectors
```

## Troubleshooting

### Plugin Not Found After Installation

**Issue**: `/plugin list` doesn't show the plugin

**Solutions**:
1. Restart Claude Code CLI
2. Verify plugin manifest exists at `hyly-e2e-plugin/.claude-plugin/plugin.json`
3. Check plugin.json is valid JSON
4. Reinstall using `/plugin install ./hyly-e2e-plugin`

### Notion API Authentication Errors

**Issue**: "Unauthorized" or "Invalid API key" errors

**Solutions**:
1. Verify `NOTION_API_KEY` is correctly set in `.env`
2. Ensure the API key starts with `secret_`
3. Check the integration has access to your workspace
4. Verify the database is shared with the integration

### Selector Finder Not Working

**Issue**: "Chrome DevTools MCP not available"

**Solutions**:
1. Install Chrome DevTools MCP server
2. Start the MCP server
3. Verify with `/mcp list` in Claude Code
4. Restart Claude Code after installing MCP

### Scripts Not Generating

**Issue**: Stage 4 fails or generates empty scripts

**Solutions**:
1. Verify Stage 3 completed successfully
2. Check `registration-summary.json` exists and has valid data
3. Ensure test cases have detailed steps (not generic)
4. Review Stage 2 output for quality

### Pipeline Hangs at Approval

**Issue**: Pipeline doesn't continue after approval

**Solutions**:
1. Type "yes" exactly (lowercase)
2. Check for typos in response
3. Verify you're responding to the correct prompt
4. Restart the pipeline if stuck

### Environment Variables Not Loading

**Issue**: Scripts can't find `NOTION_API_KEY` or other variables

**Solutions**:
1. Verify `.env` file is in project root (not plugin folder)
2. Check file is named `.env` exactly (not `.env.txt`)
3. Ensure no spaces around `=` in variable assignments
4. Restart terminal/Claude Code after creating `.env`

### Permission Errors

**Issue**: "EACCES" or permission denied errors

**Solutions**:
1. Check file/folder permissions
2. Run with appropriate user permissions
3. Ensure directories exist: `test-results/`, `test-plans/`, etc.
4. Create missing directories manually

## Next Steps

After successful installation:

1. **Read the Quick Start Guide** - `QUICKSTART.md`
2. **Review Examples** - Check example test cases and hints
3. **Customize Hints** - Create project-specific hint files
4. **Run First Pipeline** - Try the complete 7-stage pipeline
5. **Explore Skills** - Use selector-finder and test-debugger

## Getting Help

- **Documentation**: See `README.md` for full documentation
- **Examples**: Check the `hints/` folder for pattern examples
- **Issues**: Report bugs at https://github.com/hyly-ai/hyly-e2e-plugin/issues
- **Support**: Email support@hyly.ai

## Updating the Plugin

To update to the latest version:

```bash
# Uninstall current version
/plugin uninstall hyly-e2e-plugin

# Install latest version
/plugin install hyly-e2e-plugin@hyly-ai

# Or for local installation
git pull  # In plugin directory
/plugin install ./hyly-e2e-plugin
```

---

**Installation complete!** 🎉

You're ready to start automating your E2E tests with AI-powered intelligence.