upskill-event-manager/docs/staging-test-plan.md

Staging Environment Testing Plan

Overview

This document outlines a safe and reliable approach for running unit tests on the staging server without disrupting the WordPress environment. It addresses previous issues that led to WordPress core file corruption and provides a structured process for test execution.

Current Issues

• Previous staging test attempts led to WordPress core file corruption
• SSH/rsync commands modified files outside the plugin directory
• Environment variables and SSH connections had configuration issues
• Test dependencies were not properly installed or configured

Plan Diagram

flowchart TD
    A[Start] --> B[Create Backup]
    B --> C[Sync Production to Staging]
    C --> D[Verify WordPress Integrity]
    D --> E[Deploy Plugin Code Only]
    E --> F[Configure Test Environment]
    F --> G[Run Unit Tests]
    G --> H{Tests Pass?}
    H -->|Yes| I[Document Results]
    H -->|No| J[Debug Within Plugin]
    J --> K{Issue in Plugin?}
    K -->|Yes| L[Fix Plugin Code]
    K -->|No| M[Restore from Backup]
    L --> G
    M --> N[Document Environment Issue]
    I --> O[End]
    N --> O

Detailed Steps

1. Preparation Phase

• Create a complete backup of the staging environment using Cloudways dashboard
• Document current staging environment state (plugin versions, WordPress version)
• Verify SSH access is working with the correct credentials

2. Environment Reset Phase

• Use Cloudways dashboard to clone/sync the production application to staging
• This will reset the staging environment to a known good state
• Verify WordPress core integrity after sync

3. Plugin Deployment Phase

• Deploy only the plugin code (hvac-community-events) to the staging server
  • Use the existing deploy-plugin.sh script with proper configuration
  • Ensure the script only modifies files within the plugin directory
  • Include test files (unit tests, test-doubles.php, bootstrap.php)

4. Test Configuration Phase

• Configure the test environment within the plugin directory only
• Install test dependencies using Composer within the plugin directory
• Create test configuration files that don't modify WordPress core
• Verify test configuration before running tests

5. Test Execution Phase

• Run unit tests with proper error handling
• Capture test output for analysis
• Implement automatic rollback if tests modify files outside plugin directory
• Document test results and any issues encountered

6. Recovery Procedures

• If WordPress becomes unstable, restore from backup using Cloudways dashboard
• Document any environment-specific issues for future reference
• Create a list of "safe" vs "unsafe" operations for staging environment

Implementation Details

Modified Scripts

1. deploy-plugin.sh

• Add path validation to ensure operations only affect the plugin directory
• Add dry-run option for verification before actual deployment
• Improve error handling and reporting

2. configure-staging-tests.sh

• Restrict file operations to plugin directory only
• Remove any operations that modify WordPress core files
• Add verification steps to confirm proper configuration

3. run-staging-unit-tests.sh

• Add safeguards to prevent WordPress core modification
• Improve error handling and reporting
• Add option to run specific tests only

Safe vs. Unsafe Operations

Safe Operations

• Deploying code to the plugin directory only
• Installing Composer dependencies within the plugin directory
• Running unit tests that don't modify the database
• Creating configuration files within the plugin directory

Unsafe Operations (Avoid These)

• Modifying WordPress core files
• Changing database credentials
• Running commands with root privileges
• Modifying files outside the plugin directory

Documentation Updates

• Update testing.md with staging-specific instructions
• Create a troubleshooting guide for common staging test issues
• Document the recovery process for staging environment problems

Next Steps

1. Reset staging environment using Cloudways dashboard
2. Implement the modified scripts with safety measures
3. Deploy plugin code to staging
4. Configure test environment
5. Run unit tests with proper monitoring