upskill-event-manager/docs/nas-e2e-debug-plan.md

NAS E2E Debugging Plan (profile.spec.ts) - 2025-04-06

Goal

Diagnose and resolve failures preventing the profile.spec.ts E2E test suite from running successfully against the NAS-based development environment (192.168.10.163). The immediate blocker is a "critical error" preventing the /community-login/ page from loading, causing the Playwright global-setup to time out.

Context

• E2E tests are run locally via Playwright, targeting the WordPress instance on the NAS.
• The run-tests.sh script handles pre-test setup, including disabling known problematic plugins (by renaming their directories) and running WP-CLI commands (plugin activate/deactivate, rewrite flush) with --skip-plugins.
• Despite these workarounds, the /community-login/ page still shows a critical error when accessed via a browser or Playwright.
• The root cause is suspected to be additional plugins with missing vendor directories (due to rsync exclusions or backup state) or potentially an issue within the hvac-community-events plugin or theme when dependencies are disabled.
• Constraint: Avoid modifying third-party plugin code directly. Use temporary workarounds (like renaming directories via script) for testing only. The underlying environment setup process needs separate fixing.

Debugging Plan

1. Enable WP_DEBUG: Retry enabling WP_DEBUG and WP_DEBUG_LOG in wp-config.php on the NAS container to capture detailed errors.

   # Command to be executed locally:
   ssh ben@192.168.10.163 "cd /volume2/docker/wordpress-dev && /usr/local/bin/docker-compose exec -T wordpress sed -i \"s/define( *'WP_DEBUG', false *);/define( 'WP_DEBUG', true );/\" /var/www/html/wp-config.php && /usr/local/bin/docker-compose exec -T wordpress sed -i \"s/\\/\\/define( *'WP_DEBUG_LOG', true *);/define( 'WP_DEBUG_LOG', true );/\" /var/www/html/wp-config.php"
   

2. Trigger Error: Manually access http://192.168.10.163:8080/community-login/ in a browser to ensure the error occurs and is logged.
3. Retrieve Debug Log: Fetch the contents of /var/www/html/wp-content/debug.log from the NAS container.

   # Command to be executed locally:
   ssh ben@192.168.10.163 "cd /volume2/docker/wordpress-dev && /usr/local/bin/docker-compose exec -T wordpress cat /var/www/html/wp-content/debug.log"
   

4. Analyze Debug Log: Examine the log for PHP fatal errors and stack traces to pinpoint the exact file and line causing the "critical error".
5. Identify Culprit: Determine the specific plugin, theme, or core file responsible.
6. Investigate NAS Differences (If Applicable): If the error seems environment-specific (e.g., not simply a missing vendor/autoload.php), investigate potential differences between the NAS and local dev environments:
   • PHP Version (php -v inside container)
   • PHP Extensions (php -m inside container)
   • File Permissions (ls -la on relevant directories inside container/on NAS)
   • Resource Limits (Memory, CPU - potentially harder to check)
7. Formulate Solution: Based on the culprit and investigation:
   • Missing Vendor Directory: Add the newly identified plugin slug to the KNOWN_PROBLEMATIC_PLUGINS_E2E array in run-tests.sh as a temporary workaround. Document this decision.
   • Error in hvac-community-events / Theme: Plan code changes and prepare to switch to Debug/Code mode.
   • Environment Difference: Plan steps to align the NAS environment (e.g., install PHP extension, adjust permissions) and potentially switch modes.
8. Implement Solution/Workaround: Apply the chosen fix (e.g., modify run-tests.sh, switch modes).
9. Re-run Tests: Execute ./wordpress-dev/bin/run-tests.sh --e2e tests/e2e/tests/profile.spec.ts to verify the login page loads and global-setup completes.
10. Address Original Failures: Once global-setup passes, proceed to analyze and debug the specific failures reported within the profile.spec.ts test suite.
11. (Optional) Modify E2E Timeout/Checks: If the page loads reliably but slowly, consider adjusting Playwright timeouts or adding explicit checks for the "critical error" message in global-setup.ts for faster failure detection.
12. Document Findings: Update memory-bank/decisionLog.md and memory-bank/activeContext.md with the findings, decisions made, and workarounds applied. Emphasize the need for a separate task to address the root cause in the environment setup/sync process (e.g., ensuring vendor directories are correctly populated).

Debugging Flow Diagram

graph TD
    A[Start Debugging profile.spec.ts] --> B{Run run-tests.sh};
    B --> C{Disable Known Problematic Plugins (run-tests.sh)};
    C --> D{Run WP-CLI Commands (--skip-plugins)};
    D -- Success --> E{Run Playwright Tests};
    E -- Fails (Timeout on #user_login) --> F{Check /community-login/ Manually};
    F -- Shows Critical Error --> G{Enable WP_DEBUG};
    G --> H{Trigger Error (Manual Load)};
    H --> I{Retrieve debug.log};
    I --> J{Analyze Error};
    J --> K{Identify Culprit};
    K --> K_NAS{Investigate NAS vs Dev Differences?};
    K_NAS -- Yes --> L_NAS[Plan Env Fix];
    K_NAS -- No --> L{Formulate Solution};
    K -- Error in HVAC/Theme --> L_CODE[Plan Code Fix];
    K -- Missing Vendor Dir --> L_WORKAROUND[Plan Workaround (Disable Plugin in run-tests.sh)];
    L_WORKAROUND --> M{Implement Workaround};
    L_CODE --> M_SWITCH[Switch Mode (Debug/Code)];
    L_NAS --> M_SWITCH_ENV[Switch Mode (Code/Ops)];
    M --> B;
    E -- Success --> N[Analyze profile.spec.ts Failures];
    N --> O[Document Findings & Recommend Env Setup Fix];