Reorganize directory structure: move utility files to misc/ directory
- Move all non-wrapper files (testing scripts, documentation, utilities) to misc/ directory - Keep SF CLI wrapper scripts and README.md in root directory for better organization - Maintain clean root directory with only the actual wrapper scripts and main documentation - All wrapper scripts remain easily accessible and discoverable - Supporting files are organized in misc/ subdirectory
This commit is contained in:
reynold
258
misc/TESTING.md
Normal file
258
misc/TESTING.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user