upskill-event-manager/memory-bank/decisionLog.md

HVAC Role Manager - Decision Log

[2025-04-14 18:58] - Initial Role Manager Design Decisions

Role Inheritance Architecture

• Decision: Implement hierarchical role inheritance with multiple parent support
• Rationale:
  • Allows flexible permission structures
  • Supports complex organizational hierarchies
  • Enables granular permission management
• Implementation Details:
  • Roles can inherit from multiple parent roles
  • Capabilities are merged from all parent roles
  • Conflicts are detected and managed explicitly

Capability Management Approach

• Decision: Use WordPress capability system with custom extensions
• Rationale:
  • Maintains compatibility with WordPress core
  • Leverages existing security mechanisms
  • Allows seamless integration with plugins
• Implementation Details:
  • Extended capability checking for complex scenarios
  • Transaction-based role modifications
  • Automatic capability cleanup

TEC Integration Strategy

• Decision: Implement lightweight TEC capability integration
• Rationale:
  • Maintains separation of concerns
  • Ensures compatibility with TEC updates
  • Simplifies maintenance
• Implementation Details:
  • Support for TEC-specific capabilities
  • Integration examples in documentation
  • Clear separation between core and TEC functionality

Security Considerations

• Decision: Implement comprehensive security measures
• Rationale:
  • Protect WordPress core roles
  • Prevent capability escalation
  • Ensure proper cleanup
• Implementation Details:
  • Core role protection
  • Capability validation
  • Transaction role management
  • Automatic cleanup mechanisms

[2025-04-14 18:58] - Documentation Structure

• Decision: Create comprehensive, well-organized documentation
• Rationale:
  • Ensures maintainability
  • Facilitates adoption
  • Supports future development
• Implementation Details:
  • API reference documentation
  • Integration examples
  • Best practices guide [2025-04-23 13:19:25] - Debugging MVP integration tests: Identified that Playwright E2E tests fail due to login failure on the staging environment via the custom community login page. The page redirects to wp-login.php instead of the dashboard after submission, without displaying an explicit error. Likely causes are issues with the custom login page's backend processing or redirection logic on staging. Documentation regarding Playwright test execution command and location (./tests/run-tests.sh pw) was found to be outdated and has been updated in relevant files (docs/mvp-integration-testing-plan.md, docs/REQUIREMENTS.md, wordpress-dev/README.md, memory-bank/playwright-test-plan.md). Further server-side debugging is needed to fix the login issue. [2025-04-23 16:19:18] - Debugging MVP integration tests: Confirmed that the test_trainer user does not exist on the staging environment via WP-11111111111111111. This is the root cause of the Playwright E2E test login failures. Investigation into existing scripts and documentation (wordpress-dev/bin/, tests/, docs/testing.md) did not reveal an automated script for creating these test users on staging. Manual creation or development of a new setup script is required.
  • Testing guidelines

[2025-04-23 19:01:29] - Migration from Docker to Cloudways Staging: Completed the transition from Docker-based local development to using the Cloudways staging server as the primary development and testing environment. This decision was made to simplify the development workflow, ensure consistent testing environments, and reduce setup complexity. All documentation has been updated to remove Docker references and replace them with Cloudways staging server directives. Key benefits include: 1) Consistent environment for all developers, 2) Simplified setup process, 3) Production-like testing environment, 4) Reduced local resource requirements, and 5) Improved collaboration through shared staging environment. Implementation involved updating README.md, MIGRATION_GUIDE.md, and productContext.md to reflect the new workflow.

[2025-04-23 23:16:32] - Decided to modify deploy-plugin.sh and deploy_config.sh to correct rsync source path interpretation and successfully deploy plugin files to staging. [2025-04-23 23:16:32] - Identified and corrected role name mismatch in setup-staging-test-users.sh (trainer to hvac_trainer) to enable successful test user creation. [2025-04-23 23:16:32] - Modified run-tests.sh to replace Docker commands with SSH commands targeting staging and explicitly pass UPSKILL_STAGING_URL to Playwright. [2025-04-23 23:16:32] - Increased Playwright timeout and enabled retries in playwright.config.ts to address test failures and obtain debugging artifacts. [2025-04-23 19:12:11] - Deprecated all Docker-based configuration and scripts. Removed Docker variables from dev-env.conf and replaced wp-config-docker.php with a deprecation notice. Cloudways Staging is now the sole supported development and testing environment. This change eliminates confusion, ensures consistency, and aligns all workflows with the current staging infrastructure. [2025-04-24 05:21:00] - Identified database connection issue as root cause of E2E test failures. Analysis of Playwright debugging artifacts revealed that the application is unable to connect to the database (Access denied for user 'root'@'localhost'), preventing the rendering of critical UI elements that the tests are waiting for. Decision: Update documentation to reflect this finding and create a plan to fix the database connection configuration on the staging server. [2025-04-24 05:37:00] - Created fix-db-connection.sh script to address the database connection issue. Decision: Implement a comprehensive script that not only fixes the immediate issue but also provides diagnostic capabilities and safeguards (backup creation, dry-run mode) to ensure a safe and effective resolution. The script follows a systematic approach of checking connections, identifying configuration issues, and applying fixes with proper validation.

[2025-04-24 06:17:00] - Identified a limitation with the fix-db-connection.sh script: it modifies files outside the wp-content/plugins/hvac-community-events directory. These changes will be overridden during production-to-staging syncs. Future fixes should ideally target only the custom plugin directory or be part of the standard deployment process.

[2025-04-24 07:04:00] - E2E Test URL Configuration Update Decision

• Decision: Update E2E test files to use relative paths instead of hardcoded URLs
• Rationale:
  • Enables tests to run correctly in different environments (local, staging, production)
  • Improves maintainability by centralizing URL configuration in playwright.config.ts
  • Follows best practices for test automation by avoiding environment-specific hardcoding
• Implementation Details:
  • Modified dashboard.spec.ts to use relative paths for URL assertions
  • Updated login-page.ts and registration-page.ts to use relative paths
  • Leveraged the baseURL configuration from playwright.config.ts
• Limitations:
  • Tests still fail due to missing elements on pages
  • Further investigation needed to understand differences in page structure between environments
  • May require additional configuration or test updates to fully resolve E2E test failures

[2025-04-24 07:28:00] - E2E Test Element Not Found Error Resolution Strategy

• Decision: Address E2E test element not found errors through a multi-pronged approach
• Rationale:
  • Tests are failing because specific elements from The Events Calendar Community Events plugin aren't rendering
  • URL format mismatches between test expectations and actual staging site behavior
  • Potential plugin activation or configuration issues on staging server
• Implementation Details:
  • Verify plugin activation status on staging server
  • Update test assertions to use more flexible matching (e.g., expect.stringContaining())
  • Review WordPress URL configuration settings
  • Enable debug mode to identify plugin rendering issues
• Implications:
  • May require updates to both test code and staging server configuration
  • Highlights the importance of consistent environment configuration between local and staging
  • Demonstrates need for more resilient test assertions that can handle environment differences

[2025-04-24 14:52:59] - Updated plugin verification and integration scripts to use correct TEC plugin slugs (event-tickets, event-tickets-plus, events-calendar-pro, the-events-calendar, the-events-calendar-community-events). Fixed Playwright E2E test orchestration and plugin activation logic. Documented that all plugin activation issues are resolved, but the [tribe_community_events view="list"] shortcode and related E2E tests are failing due to rendering issues, not plugin activation.

[2025-04-24 22:19:54] - Diagnostic Halt: TEC Community Events Shortcode/E2E Rendering Issue

• Advanced debugging session halted at user request.
• Enabled server-side debug logging and injected error_log diagnostics into TEC Community Events shortcode handler.
• Confirmed debug log is writable and other plugin logs are present.
• Diagnostic logs from shortcode handler (do_shortcode) never appeared, even after:
  • Triggering shortcode via WP-CLI as test user
  • Running full Playwright E2E suite
  • Injecting a test log at the top of the handler
• Most likely root causes:
  1. E2E tests are not reaching Community Events pages due to navigation, login, or setup failures.
  2. Plugin/theme/template override or misconfiguration is preventing shortcode execution.
  3. Code path/environment issue in test context.
• Next steps (if resumed): Directly confirm page content and plugin activation in DB, review E2E navigation and login flow, and check for template overrides.

[2025-04-29 19:09:15] - Debugged Playwright test failure for event creation. Determined the publish button selector was incorrect; debug logs confirmed the correct selector is #post or .events-community-submit. Action: recommend updating test selector to match actual submit button.