104 lines
No EOL
6.5 KiB
Markdown
104 lines
No EOL
6.5 KiB
Markdown
# Plan: Improving the Testing & Debugging Workflow
|
|
|
|
**Date:** 2025-04-05
|
|
|
|
**Goal:** Address inefficiencies, time consumption, and recurring issues in the testing and debugging process for the HVAC Community Events WordPress plugin. This plan focuses on stabilizing the test environment, refining testing strategies, and improving documentation/workflow.
|
|
**Note (2025-04-07):** **Development is shifting to an official Cloudways staging environment.** The previous NAS-based Docker setup described in older documentation is paused/deprecated. This plan's goals remain relevant, but implementation details (e.g., environment setup, test execution commands) will need to be adapted for the Cloudways context.
|
|
|
|
**Analysis Summary:**
|
|
|
|
The current process suffers from:
|
|
1. **Environment Complexity & Fragility:** Docker setup is complex and prone to configuration errors.
|
|
2. **Testing Strategy Challenges:** Skipped tests, brittle E2E tests, and difficulties bootstrapping third-party plugins in integration tests.
|
|
3. **Repetitive Debugging Loops:** Similar environment and test runner issues recur.
|
|
4. **Documentation Gaps:** Existing documentation may not reflect the latest working configurations or troubleshooting knowledge.
|
|
|
|
---
|
|
|
|
## Phase 1: Stabilize the Test Environment
|
|
|
|
* **Goal:** Reduce time spent debugging the environment itself by simplifying configuration, ensuring consistency, and addressing known core issues.
|
|
* **Steps:**
|
|
1. **Configuration Review & Simplification:**
|
|
* Analyze interactions between `phpunit.xml.dist`, `wp-tests-config.php`, `tests/bootstrap.php`, and `wp-config.php`.
|
|
* Identify opportunities for simplification and conflict reduction.
|
|
2. **Dependency Management Audit:**
|
|
* Verify `composer.lock` and `package-lock.json` are up-to-date and committed.
|
|
* Ensure `composer install` and `npm install` are part of the documented setup/pre-testing workflow.
|
|
3. **Docker Configuration Tuning:**
|
|
* Investigate the impact of removing `:cached` flags from key volume mounts in `docker-compose.yml`.
|
|
* Verify host/container file permissions consistency.
|
|
4. **Root Cause Analysis for Skipped Tests:**
|
|
* **Integration Setup (`Test_HVAC_Profile_Integration`):** Diagnosed as an incompatibility between the `wp-phpunit` environment and namespaced test classes, combined with conflicts from repeated plugin initialization within the test lifecycle, leading to persistent serialization errors even with `backupGlobals="false"` and `processIsolation="false"`. Decided to keep this test class skipped (`@group skip`).
|
|
* **Missing JS (`php-date-formatter.js`):** Confirmed missing from the installed TEC CE plugin version (even after syncing from production). Recommended workaround is to modify E2E tests to avoid depending on it.
|
|
5. **Create Robust Test Setup Script:**
|
|
* Develop a script (`bin/setup-test-env.sh` or enhance `run-tests.sh`) to automate *all* prerequisites: dependency installation, plugin activation, rewrite flush, potential DB reset.
|
|
|
|
## Phase 2: Refine Testing Strategy
|
|
|
|
* **Goal:** Improve test reliability, balance the test pyramid, and ensure meaningful coverage.
|
|
* **Steps:**
|
|
1. **Revisit Skipped Tests:** Based on Phase 1 findings:
|
|
* `Test_HVAC_Profile_Integration`: Keep skipped due to unresolved environment conflicts.
|
|
* Task 5.8 Event Summary transaction test: Attempt to un-skip if reliable plugin bootstrapping (Step 2) is achieved.
|
|
* E2E TEC CE shortcode rendering tests: Keep skipped or investigate further if deemed critical.
|
|
2. **Develop Reliable Plugin Bootstrapping:**
|
|
* Create and document a standard pattern (helper functions/classes) for reliably initializing WordPress *and* specific third-party plugins within PHPUnit integration tests.
|
|
3. **Enhance E2E Test Resilience:**
|
|
* **Selectors:** Mandate `data-testid` attributes for key elements. Update tests.
|
|
* **Waits:** Replace brittle waits with robust strategies (stable selectors, network idle, specific API calls).
|
|
* **Scope:** Focus E2E on integration/flow, not exhaustive third-party UI testing. Mock complex interactions if needed.
|
|
4. **Strengthen Integration/Unit Tests:**
|
|
* Identify E2E failures preventable by earlier tests.
|
|
* Add targeted integration tests for plugin interactions (hooks, data saving).
|
|
* Ensure unit tests cover complex logic and edge cases.
|
|
|
|
## Phase 3: Improve Debugging Workflow & Documentation
|
|
|
|
* **Goal:** Make debugging faster and prevent recurring issues through better tooling and knowledge sharing.
|
|
* **Steps:**
|
|
1. **Enhance `testing.md`:**
|
|
* Update configuration details based on Phase 1 stabilization.
|
|
* Expand troubleshooting section with step-by-step diagnosis and resolutions for common errors.
|
|
* Clearly document required setup steps (including new script).
|
|
* Document the standard plugin bootstrapping pattern (from Phase 2).
|
|
2. **Create Environment Verification Script:**
|
|
* Develop `bin/verify-test-env.sh`.
|
|
* Checks: PHPUnit runnable, WP-CLI accessible, test DB connection, Playwright config readable, plugins active, key files exist, etc.
|
|
* Instruct developers to run this *before* debugging test failures.
|
|
3. **Update Memory Bank:**
|
|
* Record key decisions in `memory-bank/decisionLog.md`.
|
|
* Update `memory-bank/activeContext.md` to reflect focus on test process improvement.
|
|
* Add new patterns to `memory-bank/systemPatterns.md`.
|
|
|
|
---
|
|
|
|
**Workflow Diagram (Conceptual):**
|
|
|
|
```mermaid
|
|
graph TD
|
|
A[Start: Inefficient Testing/Debugging] --> B{Phase 1: Stabilize Environment};
|
|
B --> B1[Review Configs];
|
|
B --> B2[Audit Dependencies];
|
|
B --> B3[Tune Docker Config];
|
|
B --> B4[Root Cause Analysis (Skipped Tests/JS)];
|
|
B --> B5[Create Setup Script];
|
|
B --> C{Phase 2: Refine Testing Strategy};
|
|
C --> C1[Revisit Skipped Tests];
|
|
C --> C2[Develop Plugin Bootstrap Pattern];
|
|
C --> C3[Enhance E2E Resilience (Selectors/Waits)];
|
|
C --> C4[Strengthen Integration/Unit Tests];
|
|
C --> D{Phase 3: Improve Workflow & Docs};
|
|
D --> D1[Enhance testing.md];
|
|
D --> D2[Create Verification Script];
|
|
D --> D3[Update Memory Bank];
|
|
D --> E[End: More Efficient Testing/Debugging];
|
|
|
|
subgraph Legend
|
|
direction LR
|
|
L1[Phase]
|
|
L2[Action/Step]
|
|
end
|
|
|
|
style A fill:#f9f,stroke:#333,stroke-width:2px
|
|
style E fill:#ccf,stroke:#333,stroke-width:2px |