# SAWIS Playwright Test Suite - Quick Setup Guide

## 🚀 Quick Start

### 1. Prerequisites
- Node.js (v16 or higher)
- npm or yarn package manager
- Internet connection (to access https://bi.sawisonline.co.za/)

### 2. Installation
```bash
# Install dependencies
npm install

# Install Playwright browsers
npm run install:browsers
```

### 3. Run Your First Test
```bash
# Run a quick test to verify setup
npm run test:quick

# Or run homepage tests
npm run test:homepage
```

## 📁 Project Structure

```
playwrite_scripts/
├── tests/
│   ├── homepage.spec.ts      # Homepage functionality tests
│   ├── login.spec.ts         # Authentication tests
│   ├── filters.spec.ts       # Filter functionality tests
│   ├── navigation.spec.ts    # Navigation and routing tests
│   ├── charts.spec.ts        # Data visualization tests
│   └── performance.spec.ts   # Performance and load tests
├── playwright.config.ts      # Playwright configuration
├── package.json             # Dependencies and scripts
├── run-tests.js             # Test runner script
├── README.md                # Comprehensive documentation
├── CHANGELOG.md             # Version history
├── NewKnowledgeBase.md      # Learnings and insights
└── SETUP_GUIDE.md           # This file
```

## 🎯 Available Test Commands

### Quick Tests
```bash
npm run test:quick      # Single test to verify setup
npm run test:homepage   # Homepage tests only
npm run test:login      # Login tests only
npm run test:filters    # Filter tests only
npm run test:nav        # Navigation tests only
npm run test:charts     # Chart tests only
npm run test:perf       # Performance tests only
```

### Full Test Suite
```bash
npm run test:all        # Run all tests
npm run test            # Standard test command
```

### Interactive Testing
```bash
npm run test:ui         # UI mode (interactive)
npm run test:headed     # Visible browser
npm run test:debug      # Debug mode
```

### Reports
```bash
npm run test:report     # Show HTML test report
```

## 🔧 Configuration

### Browser Support
- **Chromium**: Primary testing browser
- **Firefox**: Cross-browser compatibility
- **WebKit**: Safari compatibility
- **Mobile Chrome**: Mobile responsiveness
- **Mobile Safari**: iOS compatibility

### Test Environment
- **Base URL**: https://bi.sawisonline.co.za/
- **Timeout**: 60 seconds for navigation, 15 seconds for actions
- **Retries**: 2 retries on CI, 0 on local development
- **Parallel Execution**: Enabled for faster test execution

## 🐛 Troubleshooting

### Common Issues

#### 1. Tests Timing Out
**Problem**: Tests fail with timeout errors
**Solution**: 
- Check internet connection
- Increase timeout in `playwright.config.ts`
- Use `npm run test:headed` to see what's happening

#### 2. Browser Installation Issues
**Problem**: Browsers not found
**Solution**:
```bash
npm run install:browsers
```

#### 3. Network Issues
**Problem**: Tests fail due to network problems
**Solution**:
- Verify https://bi.sawisonline.co.za/ is accessible
- Check firewall settings
- Try running with `--headed` flag to see browser behavior

#### 4. Permission Issues
**Problem**: Cannot install dependencies or browsers
**Solution**:
- Run as administrator (Windows)
- Check npm permissions
- Clear npm cache: `npm cache clean --force`

### Debug Mode
```bash
# Run tests in debug mode to step through
npm run test:debug

# Run specific test in debug mode
npx playwright test tests/homepage.spec.ts --debug
```

## 📊 Understanding Test Results

### Test Reports
After running tests, view the HTML report:
```bash
npm run test:report
```

### Test Output
- ✅ **Passed**: Test completed successfully
- ❌ **Failed**: Test failed (check screenshots and videos)
- ⏱️ **Timeout**: Test took too long (check network/performance)

### Artifacts
- **Screenshots**: Captured on test failure
- **Videos**: Recorded during test execution
- **Traces**: Detailed execution traces (on retry)

## 🎯 Test Categories

### 1. Homepage Tests
- Page loading and basic functionality
- Navigation elements
- Key metrics display
- Chart sections
- Filter sidebar
- Footer information
- Responsive design
- Accessibility

### 2. Login Tests
- Modal functionality
- Form validation
- reCAPTCHA integration
- Password recovery
- Account creation
- Keyboard navigation
- Focus management

### 3. Filter Tests
- All filter sections
- Dropdown functionality
- Search capability
- Multi-selection
- Apply/Clear buttons
- Data updates
- Filter combinations

### 4. Navigation Tests
- Tab navigation
- Content loading
- State management
- Rapid navigation
- Keyboard support
- Loading states

### 5. Chart Tests
- Chart display
- Reporting periods
- Export functionality
- Table views
- Chart interactions
- Loading states
- Data updates

### 6. Performance Tests
- Page load performance
- Data loading
- Filter application
- Navigation speed
- Large datasets
- Memory usage
- Network latency

## 🔄 Continuous Integration

### GitHub Actions
```yaml
name: SAWIS Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run install:browsers
      - run: npm test
```

### Local Development
```bash
# Run tests in watch mode
npx playwright test --watch

# Run tests with specific grep pattern
npx playwright test -g "should load homepage"

# Generate test code
npx playwright codegen https://bi.sawisonline.co.za/
```

## 📞 Getting Help

### Documentation
- **README.md**: Comprehensive project documentation
- **CHANGELOG.md**: Version history and changes
- **NewKnowledgeBase.md**: Learnings and insights

### Common Commands Reference
```bash
# Quick verification
npm run test:quick

# Run specific test suite
npm run test:homepage

# Run all tests
npm run test:all

# Interactive testing
npm run test:ui

# Debug mode
npm run test:debug

# View reports
npm run test:report
```

### Performance Benchmarks
- **Page Load**: < 10 seconds
- **Data Loading**: < 15 seconds
- **Filter Application**: < 8 seconds
- **Navigation**: < 5 seconds
- **Large Dataset**: < 20 seconds

## 🎉 Success Indicators

Your setup is working correctly when:
- ✅ `npm run test:quick` passes
- ✅ All browsers install successfully
- ✅ Test reports generate properly
- ✅ No critical console errors
- ✅ Tests complete within expected timeframes

---

**Need Help?** Check the main README.md for detailed documentation or run `node run-tests.js help` for command options.