veriqa-test-advisor/INSTALLATION.md

AI-powered regression test case advisor CLI tool with integrated Manual QA support

# 🚀 VeriQA Installation & Setup Guide

## 📋 Prerequisites

- **Node.js 16+** ([Download here](https://nodejs.org/))
- **npm** (comes with Node.js)
- **Git** (for commit analysis)

## 🎯 Installation Methods

### Method 1: Global Installation (Recommended)

```bash
# Install VeriQA globally
npm install -g veriqa-test-advisor

# Auto-setup your project 
npx veriqa-setup

# Start using VeriQA
veriqa-test-advisor --help
```

### Method 2: Project-Specific Installation

```bash
# In your existing project
npm install veriqa-test-advisor --save-dev

# Setup project structure
npx veriqa-setup

# Use via npm scripts
npm run test:ai
```

### Method 3: Quick Demo

```bash
# Try VeriQA without installation
mkdir my-test-project && cd my-test-project
npx veriqa-test-advisor --help
npx veriqa-setup
```

## 🛠️ Auto Setup Details

The `veriqa-setup` command automatically creates:

### 📁 Project Structure
```
your-project/
├── tests/
│   ├── auth/           # Authentication tests
│   │   └── login.spec.js
│   ├── product/        # Product/feature tests  
│   │   └── search.test.js
│   └── user/           # User management tests
│       └── profile.spec.js
├── mappings/
│   └── module_test_map.json
├── scripts/
│   └── quick-start.js
├── .env                # Configuration
├── playwright.config.js # Playwright setup
├── codecept.conf.js    # CodeceptJS setup
└── package.json        # Updated with scripts
```

### ⚙️ Configuration Files

**`.env` (Environment Variables):**
```env
PERPLEXITY_API_KEY=your_api_key_here
VERIQA_FRAMEWORK=playwright
VERIQA_ENV=local
```

**`package.json` (NPM Scripts):**
```json
{
  "scripts": {
    "test:ai": "veriqa-test-advisor --ai",
    "test:smoke": "veriqa-test-advisor --run --tag smoke", 
    "test:regression": "veriqa-test-advisor --run --tag regression",
    "test:dry": "veriqa-test-advisor --dry-run --tag smoke"
  }
}
```

### 🧪 Sample Test Files

**Playwright Test (`tests/auth/login.spec.js`):**
```javascript
// @module: auth
const { test, expect } = require('@playwright/test');

test('Sample Login Test @smoke @regression', async ({ page }) => {
  await page.goto('/login');
  await page.fill('[data-testid="email"]', 'test@example.com');
  await page.click('[data-testid="login-button"]');
  await expect(page.locator('text=Welcome')).toBeVisible();
});
```

**CodeceptJS Test (`tests/product/search.test.js`):**
```javascript
// @module: product  
Feature('Product Search');

Scenario('Sample Product Search @smoke', ({ I }) => {
  I.amOnPage('/products');
  I.fillField('[data-testid="search-input"]', 'laptop');
  I.click('[data-testid="search-button"]');
  I.see('Search Results');
});
```

## 🚀 Quick Start

After installation and setup:

### 1. Configure API Key
```bash
# Edit .env file
nano .env

# Add your Perplexity AI key
PERPLEXITY_API_KEY=your_actual_api_key_here
```

### 2. Test the Installation
```bash
# Check version
veriqa-test-advisor --version

# Get help
veriqa-test-advisor --help

# Run demo
node scripts/quick-start.js
```

### 3. First AI Analysis
```bash
# Make a commit first
git add . && git commit -m "Setup VeriQA testing framework"

# Get AI suggestions
npm run test:ai
# or
veriqa-test-advisor --ai
```

### 4. Run Your First Tests
```bash
# Dry run to see what would execute
npm run test:dry

# Run smoke tests
npm run test:smoke

# Run all regression tests  
npm run test:regression
```

## 🔧 Customization

### Update Test URLs

**For Playwright (`playwright.config.js`):**
```javascript
module.exports = defineConfig({
  use: {
    baseURL: 'https://your-app.com', // Update this
  }
});
```

**For CodeceptJS (`codecept.conf.js`):**
```javascript
exports.config = {
  helpers: {
    Playwright: {
      url: 'https://your-app.com', // Update this
    }
  }
};
```

### Add Your Own Tests

1. **Create test files** in appropriate modules:
   ```bash
   # For authentication features
   touch tests/auth/signup.spec.js
   
   # For product features  
   touch tests/product/checkout.spec.js
   ```

2. **Add module tags**:
   ```javascript
   // @module: auth
   // @module: product
   ```

3. **Use proper test tags**:
   ```javascript
   test('My test @smoke @regression', async ({ page }) => {
     // test code
   });
   ```

## 🎯 Integration with Existing Projects

### If you already have tests:

1. **Move existing tests** to module folders:
   ```bash
   mkdir -p tests/auth tests/product
   mv existing-login-tests/* tests/auth/
   ```

2. **Add module tags** to existing test files:
   ```javascript
   // Add this at the top of each test file
   // @module: your-module-name
   ```

3. **Update configuration** files:
   ```bash
   # Backup existing configs
   cp playwright.config.js playwright.config.js.backup
   
   # Let VeriQA setup update them
   npx veriqa-setup
   ```

## 🆘 Troubleshooting

### Common Issues

**1. "Command not found: veriqa-test-advisor"**
```bash
# Reinstall globally
npm uninstall -g veriqa-test-advisor
npm install -g veriqa-test-advisor
```

**2. "No tests found"**
```bash
# Check test structure
ls -la tests/
# Regenerate mapping
veriqa-test-advisor --run --verbose
```

**3. "AI suggestions failed"**  
```bash
# Check API key in .env
cat .env | grep PERPLEXITY_API_KEY
# Get free API key: https://perplexity.ai
```

**4. "Playwright not found"**
```bash
# Install Playwright
npm install @playwright/test
npx playwright install
```

### Getting Help

- 📖 **Documentation**: [GitHub Wiki](https://github.com/kapilrathore/veriqa-test-advisor/wiki)
- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/kapilrathore/veriqa-test-advisor/issues)  
- 💬 **Questions**: [GitHub Discussions](https://github.com/kapilrathore/veriqa-test-advisor/discussions)
- 📧 **Email**: support@veriqa.dev

## 🎉 Success Indicators

After successful setup, you should see:

✅ **File structure created**  
✅ **Sample tests executable**  
✅ **AI suggestions working**  
✅ **NPM scripts available**  
✅ **Test mapping generated**

```bash
# Verify everything works
npm run test:dry    # Should show test plan
veriqa-test-advisor --version # Should show version
ls tests/          # Should show auth, product, user folders
```

---

**🇮🇳 Made with ❤️ in India | VeriQA Test Advisor**