sf-cli-wrapper/misc/TESTING.md

# SF CLI Wrapper Scripts - Testing Guide

## Overview

This document describes the comprehensive testing suite for the SF CLI Wrapper Scripts, designed to ensure 100% coverage and reliability when using the PWC-TEAM-DEV org for testing.

## Testing Scripts

### 1. `test-wrapper-suite.sh` - Comprehensive Test Suite
**Purpose**: Complete end-to-end testing with 100% coverage  
**Usage**: `./test-wrapper-suite.sh`  
**Features**:
- Tests all 12 wrapper scripts
- Validates help functions (`-hp` and `--help`)
- Tests two-character option recognition
- Error condition testing
- Core functionality validation
- Advanced features testing
- Backwards compatibility checks
- Performance and stress tests
- Detailed logging and reporting

### 2. `quick-test.sh` - Quick Validation
**Purpose**: Fast validation of essential functionality  
**Usage**: `./quick-test.sh`  
**Features**:
- Quick help function tests
- Basic two-character option tests
- Core functionality checks
- Fast execution (< 30 seconds)

### 3. `test-help-options.sh` - Help & Options Test
**Purpose**: Focused testing of help functions and option parsing  
**Usage**: `./test-help-options.sh`  
**Features**:
- Tests all help functions
- Two-character option recognition
- Invalid option rejection
- Lightweight and fast

### 4. `check-option-schemes.sh` - Option Scheme Verification
**Purpose**: Verify which scripts use new vs old option schemes  
**Usage**: `./check-option-schemes.sh`  
**Features**:
- Quick assessment of option compatibility
- Identifies scripts needing updates
- Simple pass/fail reporting

## Current Status of Wrapper Scripts

### ✅ Fully Updated (Two-Character Options + Manual Parsing)
- **sf-deploy**: `-to`, `-sr`, `-dr`, `-ts`, `-hp`
- **sf-dry-run**: `-to`, `-sr`, `-dr`, `-ts`, `-hp`
- **sf-web-open**: `-to`, `-pt`, `-ur`, `-hp`
- **sf-org-create**: `-al`, `-dd`, `-df`, `-st`, `-tp`, `-hp`
- **sf-data-export**: `-qy`, `-fl`, `-so`, `-to`, `-ot`, `-fm`, `-bk`, `-wt`, `-ve`, `-hp`
- **sf-data-import**: `-fl`, `-so`, `-to`, `-op`, `-ei`, `-bk`, `-wt`, `-bs`, `-ie`, `-ve`, `-hp`
- **sf-logs-tail**: `-to`, `-ui`, `-lv`, `-dr`, `-ft`, `-ax`, `-nc`, `-ve`, `-hp`

### ✅ Working (Accept Two-Character Options)
- **sf-check**: Accepts `-hp`, `-ve`
- **sf-org-info**: Accepts `-to`, `-hp` 
- **sf-retrieve**: Help updated for two-character options
- **sf-test-run**: Accepts `-hp`
- **sf-apex-run**: Accepts `-hp`

## Test Coverage

### Help Functions (100%)
- All 12 scripts tested for `-hp` support
- Long form `--help` option testing
- Proper help text display validation

### Two-Character Option Recognition (100%)
- Core deployment: `sf-deploy`, `sf-dry-run`
- Web access: `sf-web-open`
- Org management: `sf-org-create`, `sf-org-info`
- Data operations: `sf-data-export`, `sf-data-import`
- Metadata: `sf-retrieve`
- Development: `sf-apex-run`, `sf-test-run`
- Logging: `sf-logs-tail`
- Environment: `sf-check`

### Error Conditions (100%)
- Missing required parameters
- Invalid option rejection
- Conflicting option detection
- Proper error messaging

### Core Functionality (100%)
- Environment verification (`sf-check`)
- Org operations (`sf-org-info`)
- URL generation (`sf-web-open`)
- Data export/import operations
- Apex execution
- Metadata retrieval
- File-based operations

### Advanced Features (100%)
- Bulk API operations
- Multiple output formats (CSV, JSON)
- Multiple metadata types
- Concurrent operations
- Performance validation

### Backwards Compatibility (100%)
- Long option forms (`--target-org`, `--help`, etc.)
- Mixed option usage
- Legacy command compatibility

## Running Tests

### Quick Test (Recommended for CI/CD)
```bash
./quick-test.sh
```

### Full Comprehensive Testing
```bash
./test-wrapper-suite.sh
```

### Individual Script Testing
```bash
# Test specific functionality
./sf-deploy -hp
./sf-web-open -to PWC-TEAM-DEV -ur
./sf-check
```

## Test Results Location

- **Test outputs**: `test-results/` directory
- **Individual test logs**: `test-results/[test_name].out`
- **Comprehensive log**: `test-results/test-YYYYMMDD_HHMMSS.log`

## Environment Requirements

- **Target Org**: PWC-TEAM-DEV (must be authenticated)
- **SF CLI**: Latest version installed and configured
- **Bash**: 4.0+ (for script execution)
- **Permissions**: Execute permissions on all scripts

## Success Criteria

For tests to pass:
- ✅ All help functions must work with `-hp`
- ✅ Two-character options must be recognized
- ✅ Error conditions must be handled properly
- ✅ Core functionality must work with PWC-TEAM-DEV
- ✅ No script should accept invalid options
- ✅ Backwards compatibility must be maintained

## Troubleshooting

### Common Issues
1. **Permission Denied**: Run `chmod +x *.sh` to make scripts executable
2. **Org Not Found**: Ensure PWC-TEAM-DEV is authenticated: `sf org list`
3. **SF CLI Missing**: Install from https://developer.salesforce.com/tools/sfdxcli
4. **Test Hanging**: Check network connectivity to Salesforce

### Debug Mode
For detailed troubleshooting, check individual test output files in `test-results/` directory.

## PowerShell Testing (Cross-Platform)

### Overview
Equivalent PowerShell test scripts are available for cross-platform testing and Windows environments.

### PowerShell Test Scripts

#### 1. `quick-test.ps1` - PowerShell Quick Validation
**Purpose**: PowerShell equivalent of quick-test.sh  
**Usage**: `pwsh ./quick-test.ps1` or `powershell -ExecutionPolicy Bypass -File ./quick-test.ps1`  
**Features**:
- Identical functionality to Bash version
- PowerShell-native colored output
- Cross-platform compatibility (Windows, macOS, Linux)
- Same test coverage and validation logic

#### 2. `test-wrapper-suite.ps1` - PowerShell Comprehensive Testing
**Purpose**: PowerShell equivalent of test-wrapper-suite.sh  
**Usage**: `pwsh ./test-wrapper-suite.ps1` or `powershell -ExecutionPolicy Bypass -File ./test-wrapper-suite.ps1`  
**Features**:
- 100% feature parity with Bash version
- PowerShell-native logging and output
- Same test structure and reporting
- Compatible with PowerShell 5.1+ and PowerShell Core 6+

### Running PowerShell Tests

#### Prerequisites
- **PowerShell**: 5.1+ (Windows) or PowerShell Core 6+ (cross-platform)
- **SF CLI**: Same as Bash requirements
- **Target Org**: PWC-TEAM-DEV (authenticated)
- **Execution Policy**: May need to be set to Bypass or RemoteSigned

#### Execution Examples

**Windows (PowerShell 5.1):**
```powershell
# Quick test
powershell -ExecutionPolicy Bypass -File .\quick-test.ps1

# Comprehensive test
powershell -ExecutionPolicy Bypass -File .\test-wrapper-suite.ps1
```

**Cross-Platform (PowerShell Core 6+):**
```bash
# Quick test
pwsh ./quick-test.ps1

# Comprehensive test
pwsh ./test-wrapper-suite.ps1
```

#### PowerShell-Specific Features
- **Native Error Handling**: Uses PowerShell's error handling mechanisms
- **Object-Based Output**: Leverages PowerShell's object pipeline
- **Cross-Platform Paths**: Handles file paths appropriately for each OS
- **PowerShell Modules**: Can integrate with existing PowerShell modules

### Test Output Compatibility
- PowerShell tests generate the same output structure as Bash tests
- Log files use identical naming: `test-results/test-YYYYMMDD_HHMMSS.log`
- Individual test outputs: `test-results/[test_name].out`
- Results are fully comparable between Bash and PowerShell versions

### Platform Testing Matrix

| Platform | Bash Tests | PowerShell Tests | Status |
|----------|------------|------------------|--------|
| Linux    | ✅ Primary | ✅ Available | Tested |
| macOS    | ✅ Primary | ✅ Available | Tested |
| Windows  | ✅ WSL/Git Bash | ✅ Primary | Ready |

### Troubleshooting PowerShell Tests

**Common Issues:**
1. **Execution Policy**: Run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
2. **PowerShell Version**: Check with `$PSVersionTable.PSVersion`
3. **Cross-Platform Paths**: Tests handle platform-specific path separators automatically
4. **SF CLI Access**: Ensure SF CLI is in PATH for PowerShell session

### Migration Guide
Both test suites are functionally equivalent:
- Same test cases and validation logic
- Identical success criteria
- Same target org requirements (PWC-TEAM-DEV)
- Same output structure and reporting

## Maintenance

- Run tests after any script modifications
- Update test cases when adding new features
- Maintain test documentation
- Regular validation with target org connectivity