pdq-qa-agent/INSTALL.md

Enterprise-grade QA automation with Playwright, PDF reports, and Jira integration

# PDQ QA Agent - Installation & Usage Guide

## 🚀 Quick Installation

### Option 1: Global Installation (Recommended)
```bash
npm install -g pdq-qa-agent
```

### Option 2: Run without Installation
```bash
npx pdq-qa-agent test https://your-website.com
```

### Option 3: Local Installation
```bash
npm install pdq-qa-agent
npx qa-agent test https://your-website.com
```

## ⚡ Quick Start

### 1. Basic Test Run
```bash
# Interactive mode - will prompt for URL and credentials
qa-agent test

# Direct command with URL
qa-agent test https://your-website.com

# With authentication and Jira project
qa-agent test https://your-website.com --email your@email.com --password your-password --jira-project DATA
```

### 2. Initialize Project
```bash
# Create configuration files in current directory
qa-agent init

# This creates:
# - qa-reports/ directory
# - .env.example file
# - qa-config.json file
```

### 3. Setup Jira Integration (Optional)
```bash
qa-agent setup-jira
```

## 📋 Command Reference

### Main Commands

| Command | Description | Example |
|---------|-------------|---------|
| `qa-agent test` | Run QA tests (interactive) | `qa-agent test` |
| `qa-agent test <url>` | Run QA tests on specific URL | `qa-agent test https://example.com` |
| `qa-agent init` | Initialize QA project | `qa-agent init` |
| `qa-agent setup-jira` | Configure Jira integration | `qa-agent setup-jira` |
| `qa-agent test-jira` | Test Jira connection | `qa-agent test-jira` |

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--email <email>` | Gmail email for authentication | - |
| `--password <password>` | Gmail password | - |
| `--jira-project <key>` | Jira project key (DATA, PDQ, QA, etc.) | From .env file |
| `--output <path>` | Output directory for reports | `./qa-reports` |
| `--headless` | Run browser in headless mode | `false` |
| `--timeout <ms>` | Timeout in milliseconds | `30000` |
| `--config <path>` | Path to config file | - |

## 🔧 Configuration

### Environment Variables (.env)

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

```bash
# Authentication
GMAIL_EMAIL=your-email@gmail.com
GMAIL_PASSWORD=your-app-password

# Target URL
QA_URL=https://your-webapp.com

# Browser Configuration
QA_HEADLESS=false
QA_TIMEOUT=30000

# Output Configuration
QA_OUTPUT_PATH=qa-reports

# Jira Integration (Optional)
JIRA_URL=https://your-company.atlassian.net
JIRA_EMAIL=your-jira-email@company.com
JIRA_API_TOKEN=your-jira-api-token
JIRA_PROJECT_KEY=QA
JIRA_DEFAULT_ASSIGNEE=account-id-of-default-assignee
```

### Configuration File (qa-config.json)

```json
{
  "url": "https://your-website.com",
  "credentials": {
    "email": "your@email.com",
    "password": "your-password"
  },
  "options": {
    "headless": false,
    "timeout": 30000
  },
  "outputPath": "./qa-reports",
  "tests": {
    "navigation": true,
    "forms": true,
    "links": true,
    "performance": true,
    "errors": true
  }
}
```

## 🎫 Jira Integration Setup

### Step 1: Get Jira API Token
1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click "Create API token"
3. Copy the generated token

### Step 2: Configure Jira
```bash
qa-agent setup-jira
```

This will prompt you for:
- Jira URL (e.g., `https://company.atlassian.net`)
- Your Jira email address
- API token (from Step 1)
- Project key (e.g., `QA`, `TEST`)
- Default assignee (optional)

### Step 3: Test Connection
```bash
qa-agent test-jira
```

## 📊 Generated Reports

The QA Agent generates comprehensive PDF reports that include:

✅ **Executive Summary** with pass/fail metrics  
✅ **Test Cases Overview** with detailed results  
✅ **Defects Identified** with Jira integration  
✅ **Screenshots and Evidence**  
✅ **Performance Analysis**  
✅ **Recommendations**  

Reports are saved to the output directory (default: `./qa-reports/`)

## 🔄 Usage Examples

### 1. Complete Test Suite
```bash
qa-agent test https://myapp.com \
  --email test@company.com \
  --password mypassword \
  --jira-project DATA \
  --output ./test-results \
  --headless
```

### 2. Quick Test (Interactive)
```bash
qa-agent test
# Follow the prompts to enter URL and credentials
```

### 3. Configuration File Based
```bash
qa-agent test --config ./qa-config.json
```

### 4. Environment Variables
```bash
# Set environment variables
export QA_URL=https://myapp.com
export GMAIL_EMAIL=test@company.com
export GMAIL_PASSWORD=mypassword

# Run test
qa-agent test
```

## 🐛 Automatic Issue Creation

When Jira is configured, the QA Agent automatically creates issues for:

- **Failed Tests** - Creates Bug tickets with test details
- **Console Errors** - Creates Bug tickets for JavaScript errors  
- **Network Errors** - Creates Bug tickets for failed API calls

Each issue includes:
- Detailed error information
- Steps to reproduce
- Environment details
- Test artifacts

## ⚠️ Troubleshooting

### Browser Installation Issues
```bash
npx playwright install
```

### Permission Issues (macOS/Linux)
```bash
sudo npm install -g @pdq/qa-agent
```

### Windows PowerShell Execution Policy
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

## 🔗 Links

- [Documentation](https://github.com/pdq-team/qa-agent)
- [Issue Tracker](https://github.com/pdq-team/qa-agent/issues)
- [Jira API Documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/)

---

*PDQ QA Agent - Enterprise-grade automated testing made simple*