Package Exports

pdq-qa-agent
pdq-qa-agent/src/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (pdq-qa-agent) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

🤖 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 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

Get API Token: Atlassian API Tokens
Configure: qa-agent setup-jira
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 |

🔧 Configuration

Environment Variables (.env)

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

{
  "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

# Interactive setup
qa-agent test

# Direct command
qa-agent test https://myapp.com

# With authentication
qa-agent test https://myapp.com --email user@company.com --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

Create a dedicated QA project (e.g., key: QA)
Ensure Bug issue type is available
Configure appropriate workflows
Set up default priorities (High, Medium, Low)

API Token Creation

Go to Atlassian API Tokens
Click "Create API token"
Label it "QA Agent Automation"
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 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

📝 License

MIT License - see LICENSE file for details.

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