>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3568046. --> Reported by: [littlepixiez](https://www.drupal.org/user/2568718) >>> <h3>Problem/Motivation</h3> <p>The primary use case for this testing infrastructure is to test issues, PRs, and patches on AI ecosystem modules (like ai_search, ai_agents, ai_provider_anthropic, etc.). Testers need to:</p> <ul> <li>Specify which module they're testing</li> <li>Test specific forks and branches (for PR validation)</li> <li>Ensure the testing environment uses a compatible AI base version</li> <li>Avoid manual configuration and compatibility issues</li> </ul> <p>The challenge: whilst the ability to customise the AI base version and include additional modules is powerful, it can easily lead to version incompatibilities and broken environments. For example, testing ai_search that requires AI ^1.3 whilst manually configuring AI 2.0.x will fail.</p> <h3>Proposed resolution</h3> <p>Implement test module support where the module under test drives the environment configuration:</p> <p><strong>Test module as primary focus:</strong></p> <ul> <li><code>DP_TEST_MODULE</code> specifies which module is being tested (e.g., 'ai_search', 'ai_agents')</li> <li>This is the module under development/review - the reason for spinning up the environment</li> <li>Clone this module first, before AI base module</li> <li>Support fork/branch testing via <code>DP_TEST_MODULE_ISSUE_FORK</code> and <code>DP_TEST_MODULE_ISSUE_BRANCH</code></li> </ul> <p><strong>Automatic environment compatibility:</strong></p> <ul> <li>Parse test module's composer.json to determine its AI version requirement</li> <li>Automatically use that AI version for the environment (unless explicitly overridden)</li> <li>This prevents version mismatches and broken environments</li> </ul> <p><strong>Safety validation (if AI version explicitly overridden):</strong></p> <ul> <li>If tester explicitly set <code>DP_AI_MODULE_VERSION</code> that conflicts with test module &rarr; show error (note, this may not be the best solution as there will likely be scenarios we need to do this)</li> <li>Error message explains the conflict and suggests fixes</li> <li>This prevents accidentally breaking the test environment with incompatible versions</li> </ul> <p><strong>PR/Issue testing workflow:</strong></p> <ul> <li>Set test module name: <code>DP_TEST_MODULE=ai_search</code></li> <li>Set fork and branch: <code>DP_TEST_MODULE_ISSUE_FORK=3526789</code>, <code>DP_TEST_MODULE_ISSUE_BRANCH=123-fix-bug</code></li> <li>Environment automatically configures compatible AI version (if empty)</li> <li>Test module is marked as compatible and installed</li> </ul> <p><strong>Key environment variables:</strong></p> <ul> <li><code>DP_TEST_MODULE</code>: The module being tested (the main focus)</li> <li><code>DP_TEST_MODULE_VERSION</code>: Specific version/branch (empty = latest dev branch)</li> <li><code>DP_TEST_MODULE_ISSUE_FORK</code>: Fork/issue number for PR testing</li> <li><code>DP_TEST_MODULE_ISSUE_BRANCH</code>: Branch name for PR testing</li> <li><code>DP_AI_MODULE_VERSION</code>: Can override AI version (but validated for compatibility)</li> </ul> <h3>Remaining tasks</h3> <ul> <li>[x] Implement test module cloning as Step 1 (before AI base)</li> <li>[x] Add fork and branch support for PR testing</li> <li>[x] Parse composer.json to extract AI version requirement</li> <li>[x] Convert composer constraints to git branch versions</li> <li>[x] Use detected version for AI base module installation</li> <li>[x] Implement safety validation when AI version explicitly set</li> <li>[x] Show clear error messages on version conflicts</li> <li>[x] Mark test module as automatically compatible</li> <li>[x] Test with various modules and PR branches</li> <li>[x] Test version conflict detection</li> <li>[x] Test with DDEV</li> <li>[ ] Test with DrupalPod/DrupalForge</li> </ul> <h3>Testing</h3> <p><strong>DDEV:</strong> Tested with:</p> <ul> <li>Testing ai_search PR &rarr; environment auto-configured with AI 1.3.x</li> <li>Testing ai_agents PR &rarr; environment auto-configured with AI 2.0.x</li> <li>Testing with fork/branch parameters &rarr; PR branch correctly checked out</li> <li>Explicit AI version matching test module &rarr; validated and allowed</li> <li>Explicit AI version conflicting with test module &rarr; error with clear message</li> <li>Test module without AI requirement &rarr; used fallback version</li> <li>Verified test module installed and working in all scenarios</li> </ul> <p><strong>DrupalPod/DrupalForge:</strong> Testing in progress with cloud environments.</p> > Related issue: [Issue #3568041](https://www.drupal.org/node/3568041)