pdq-qa-agent/README.md

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

# 🤖 PDQ QA Agent

> **Enterprise-grade automated web application testing with Playwright, PDF reports, and Jira integration**

[![npm version](https://badge.fury.io/js/%40pdq%2Fqa-agent.svg)](https://badge.fury.io/js/%40pdq%2Fqa-agent)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🚀 Quick Start

### Install Globally
```bash
npm install -g pdq-qa-agent
```

### Run Tests
```bash
# Interactive mode (prompts for all parameters)
qa-agent test

# Direct command with all parameters
qa-agent test https://your-website.com --email your@email.com --password your-password --jira-project DATA

# Quick one-liner for PDQ team
qa-agent test https://recipe.prettydamnquick.ai --email tamir@prettydamnquick.com --password 'KaiZen&69!' --jira-project DATA
```

### View Results
- **PDF Report**: Comprehensive report with screenshots and analysis
- **Jira Issues**: Automatically created for detected bugs (when configured)
- **Terminal Output**: Real-time test progress and summary

## ✨ Features

### 🎯 Comprehensive Testing
- **Navigation Testing** - Page structure, menus, breadcrumbs, browser controls
- **Form Testing** - Discovery, validation, submission, error handling
- **Link Testing** - Internal/external links, accessibility compliance
- **Performance Testing** - Load times, resource analysis, bottleneck identification
- **Error Testing** - Console errors, JavaScript exceptions, network failures

### 📊 Professional Reporting
- **Enterprise PDF Reports** with structured tables and visual evidence
- **Test Case Traceability** with TC-001, TC-002 format
- **Embedded Screenshots** for visual proof and debugging
- **Executive Summary** with metrics and recommendations
- **Session Tracking** with unique test identifiers

### 🐛 Automatic Issue Management
- **Jira Integration** - Automatically creates bug tickets
- **Detailed Bug Reports** with steps to reproduce and environment info
- **Priority Mapping** based on error severity
- **Test Traceability** linking issues to specific test failures

### 🔧 Easy Configuration
- **Command Line Interface** with interactive prompts
- **Environment Variables** for CI/CD integration
- **Configuration Files** for project-based settings
- **Global Installation** for quick access anywhere

## 📋 Commands

| Command | Description |
|---------|-------------|
| `qa-agent test` | Run comprehensive QA tests (interactive) |
| `qa-agent test <url>` | Test specific URL with options |
| `qa-agent test <url> --jira-project DATA` | Test with specific Jira project for tickets |
| `qa-agent init` | Initialize QA project in current directory |
| `qa-agent setup-jira` | Configure Jira integration |
| `qa-agent test-jira` | Test Jira connection |

## 🎫 Jira Integration

### Setup Steps
1. **Get API Token**: [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. **Configure**: `qa-agent setup-jira`
3. **Test**: `qa-agent test-jira`

### Automatic Issue Creation
The QA Agent automatically creates Jira issues for:
- ❌ **Failed Tests** → Bug tickets with test details
- 🔴 **Console Errors** → JavaScript error tickets
- 🌐 **Network Errors** → API failure tickets

Each issue includes:
- Detailed error information and stack traces
- Steps to reproduce with exact commands
- Environment details (URL, browser, timestamp)
- Test artifacts and screenshots

## 📊 Sample Report

The generated PDF reports include:

### 1. Executive Summary
```
📊 1. Summary

| Metric       | Count |
|--------------|-------|
| Total Tests  | 5     |
| Passed       | 4     |
| Failed       | 1     |
| Pass Rate    | 80.0% |
```

### 2. Test Cases Overview
```
🧪 2. Test Cases Overview

| Test Case ID | Description | Expected Result | Actual Result | Status | Comments |
|--------------|-------------|-----------------|---------------|---------|----------|
| TC-001       | Navigation  | Elements load   | As expected   | [PASS]  | N/A      |
| TC-002       | Forms       | Validation works| As expected   | [PASS]  | N/A      |
```

### 3. Defects Identified
```
🐛 3. Defects Identified

| Issue ID | Title | Severity | Status | Jira Link |
|----------|-------|----------|---------|-----------|
| PROJ-123 | Performance Test Failed | Medium | Created | PROJ-123 |
```

## 🔐 Security Best Practices

### Password Security
For video recording and shell history security:

```bash
# ✅ SECURE: Password prompted and hidden
qa-agent test https://myapp.com --email user@company.com

# ✅ SECURE: Interactive mode
qa-agent test

# ❌ INSECURE: Password visible in command line and shell history
qa-agent test https://myapp.com --email user@company.com --password "secret123"
```

### CI/CD Security
For automated environments, use environment variables:

```bash
# Set environment variables securely
export GMAIL_EMAIL="automation@company.com"
export GMAIL_PASSWORD="$SECURE_PASSWORD_FROM_VAULT"

# Run without exposing credentials
qa-agent test https://myapp.com
```

## 🔧 Configuration

### Environment Variables (.env)
```bash
# Authentication
GMAIL_EMAIL=your-email@gmail.com
GMAIL_PASSWORD=your-app-password

# Target Configuration
QA_URL=https://your-webapp.com
QA_HEADLESS=false
QA_TIMEOUT=30000
QA_OUTPUT_PATH=qa-reports

# Jira Integration
JIRA_URL=https://company.atlassian.net
JIRA_EMAIL=your-jira-email@company.com
JIRA_API_TOKEN=your-api-token
JIRA_PROJECT_KEY=QA
```

### 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"
}
```

## 🔄 Usage Examples

### Basic Testing
```bash
# Just run qa-agent for guided setup (recommended!)
qa-agent

# Interactive guided testing (no need to remember commands)
qa-agent test

# Direct command (still works)
qa-agent test https://myapp.com

# Secure authentication (password always hidden)
qa-agent test https://myapp.com --email user@company.com
# Password will be prompted securely

# INSECURE: password visible in shell history (not recommended)
qa-agent test https://myapp.com --email user@company.com --password secret
```

### Advanced Configuration
```bash
# Custom output directory
qa-agent test https://myapp.com --output ./test-results

# Headless mode for CI/CD
qa-agent test https://myapp.com --headless

# Using configuration file
qa-agent test --config ./qa-config.json
```

### CI/CD Integration
```bash
# Export environment variables
export QA_URL=https://staging.myapp.com
export GMAIL_EMAIL=$TEST_EMAIL
export GMAIL_PASSWORD=$TEST_PASSWORD
export QA_HEADLESS=true

# Run tests
qa-agent test
```

## ⚡ Quick Installation Options

### Option 1: Global Installation (Recommended)
```bash
npm install -g @pdq/qa-agent
qa-agent test https://your-website.com
```

### Option 2: One-time Usage
```bash
npx pdq-qa-agent test https://your-website.com
```

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

## 🏗️ Architecture

```
PDQ QA Agent
├── 🧪 Test Modules
│   ├── NavigationTest - Page structure & navigation
│   ├── FormTest - Form discovery & validation  
│   ├── LinkTest - Link accessibility & validation
│   ├── PerformanceTest - Load times & resources
│   └── ErrorTest - Console & network errors
├── 📊 Reporting
│   ├── PDFReporter - Enterprise PDF generation
│   └── ScreenshotManager - Visual evidence capture
├── 🔧 Utilities
│   ├── ConfigManager - Configuration handling
│   ├── ErrorCollector - Error aggregation
│   └── JiraIntegration - Issue management
└── 🎯 Core
    └── QAAgent - Test orchestration & execution
```

## 🚀 For Jira Admins

As a Jira admin, here's what you need to know:

### Required Permissions
- **Create Issues** in the target project
- **Edit Issues** for updating status/assignees
- **View Project** for project access

### Project Setup
1. Create a dedicated QA project (e.g., key: `QA`)
2. Ensure Bug issue type is available
3. Configure appropriate workflows
4. Set up default priorities (High, Medium, Low)

### API Token Creation
1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click "Create API token"
3. Label it "QA Agent Automation"
4. Copy the token securely

### Team Setup
```bash
# Each team member runs:
qa-agent setup-jira

# Or configure environment variables:
export JIRA_URL=https://company.atlassian.net
export JIRA_EMAIL=qa-automation@company.com
export JIRA_API_TOKEN=your-token
export JIRA_PROJECT_KEY=QA
```

## 📈 Benefits

### For QA Teams
- ✅ **Automated Testing** - Reduce manual testing effort
- ✅ **Comprehensive Coverage** - Test all critical functionality
- ✅ **Professional Reports** - Stakeholder-ready documentation
- ✅ **Issue Tracking** - Automatic bug detection and reporting

### For Development Teams  
- ✅ **Early Bug Detection** - Catch issues before production
- ✅ **Detailed Reports** - Clear reproduction steps
- ✅ **CI/CD Integration** - Automated testing in pipelines
- ✅ **Performance Insights** - Load time and resource analysis

### For Project Managers
- ✅ **Executive Dashboards** - High-level quality metrics
- ✅ **Test Traceability** - Link issues to specific tests
- ✅ **Progress Tracking** - Pass/fail rates and trends
- ✅ **Compliance Ready** - Professional documentation

## 🔗 Links

- [Installation Guide](./INSTALL.md)
- [GitHub Repository](https://github.com/pdq-team/qa-agent)
- [Issue Tracker](https://github.com/pdq-team/qa-agent/issues)
- [NPM Package](https://www.npmjs.com/package/@pdq/qa-agent)

## 📝 License

MIT License - see [LICENSE](LICENSE) file for details.

---

**PDQ QA Agent** - Making enterprise-grade QA automation accessible to everyone.