🤖 PDQ QA Agent

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

🚀 Quick Start

Install Globally

npm install -g pdq-qa-agent

Run Tests

# Interactive mode (prompts for all parameters)
qa-agent test

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

# Quick one-liner for PDQ team
qa-agent test https://recipe.prettydamnquick.ai --email [email protected] --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
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:

# ✅ SECURE: Password prompted and hidden
qa-agent test https://myapp.com --email [email protected]

# ✅ SECURE: Interactive mode
qa-agent test

# ❌ INSECURE: Password visible in command line and shell history
qa-agent test https://myapp.com --email [email protected] --password "secret123"

CI/CD Security

For automated environments, use environment variables:

# Set environment variables securely
export GMAIL_EMAIL="[email protected]"
export GMAIL_PASSWORD="$SECURE_PASSWORD_FROM_VAULT"

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

🔧 Configuration

Environment Variables (.env)

# Authentication
[email protected]
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
[email protected]
JIRA_API_TOKEN=your-api-token
JIRA_PROJECT_KEY=QA

Configuration File (qa-config.json)

{
  "url": "https://your-website.com",
  "credentials": {
    "email": "[email protected]", 
    "password": "your-password"
  },
  "options": {
    "headless": false,
    "timeout": 30000
  },
  "outputPath": "./qa-reports"
}

🔄 Usage Examples

Basic Testing

# 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 [email protected]
# Password will be prompted securely

# INSECURE: password visible in shell history (not recommended)
qa-agent test https://myapp.com --email [email protected] --password secret

Advanced Configuration

# 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

# 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)

npm install -g @pdq/qa-agent
qa-agent test https://your-website.com

Option 2: One-time Usage

npx pdq-qa-agent test https://your-website.com

Option 3: Local Project

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
2. Click "Create API token"
3. Label it "QA Agent Automation"
4. Copy the token securely

Team Setup

# Each team member runs:
qa-agent setup-jira

# Or configure environment variables:
export JIRA_URL=https://company.atlassian.net
export [email protected]
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
• GitHub Repository
• Issue Tracker
• NPM Package

📝 License

MIT License - see LICENSE file for details.

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