>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3611386. --> Reported by: [abhisekmazumdar](https://www.drupal.org/user/3557964) >>> <h2>Problem/Motivation</h2> <p>The 1.0.x-dev automated test suite does not run. Every layer &mdash; Unit, Kernel, and Functional &mdash; fails, because the tests were never updated after the agent migration in <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/ai_answers/-/work_items/3610874" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/ai_answers/-/work_items/3610874</a></span> (<code>ai_assistant_api</code>/<code>AiAssistant</code> &rarr; <code>ai_agents</code>/<code>AiAgent</code>). Right now a broken change to <code>AnswerService</code> or <code>RagSettingsResolver</code> would ship with a green-looking local run, because nothing actually executes.</p> <p>Running the full suite today:</p> <pre><pre>ddev exec bash -c "<br>&nbsp; SIMPLETEST_BASE_URL=https://drupal11.ddev.site \<br>&nbsp; SIMPLETEST_DB=mysql://db:db@db/db \<br>&nbsp; phpunit --bootstrap /var/www/html/web/core/tests/bootstrap.php \<br>&nbsp; /var/www/html/web/modules/custom/ai_answers/tests/src<br>"</pre></pre><p>produces 12 errors across 3 test classes plus the shared fixture trait.</p> <p>While tracing the breakage this also surfaced a separate, real bug: the <strong>"Retrieval query prefix" field is dead</strong>. <code>AiAnswersAgentForm</code> still exposes it and <code>AgentSettingsRegistry</code> still stores it, but <code>AnswerService</code> never reads <code>retrieval_prefix</code> anywhere &mdash; the method that used to apply it (<code>applyRetrievalPrefix()</code>) was deleted during the migration and nothing replaced it. Retrieval now happens inside the agent's own <code>rag_search</code> tool call, which has no injection point for a query prefix. This should probably be its own issue (rewire the field into the tool call, or remove it) &mdash; noted here only because a stale test (<code>testApplyRetrievalPrefix</code>) is what surfaced it.</p> <h2>Steps to reproduce</h2> <ol> <li>Enable <code>ai_answers</code> in a DDEV environment with <code>ai_agents</code> installed.</li> <li>Run the command above.</li> <li>Observe 12 errors: <code>ServiceNotFoundException</code> (missing <code>plugin.manager.ai_agents</code> service reference), <code>TypeError</code> (fixtures pass <code>AiAssistant</code> where <code>AiAgent</code> is now type-hinted), <code>ReflectionException</code> (tests call <code>AnswerService</code> methods &mdash; <code>applyRetrievalPrefix()</code>, <code>collectSources()</code> &mdash; that no longer exist), and <code>PluginNotFoundException</code> (the <code>ai_assistant</code> entity type is gone).</li> </ol> <h2>Proposed resolution</h2> <h3>Part A &mdash; fix the broken suite</h3> <ol> <li><strong><code>tests/src/Traits/AssistantTestTrait.php</code></strong>: replace with an <code>AgentTestTrait</code> that builds <code>ai_agent</code> config entity fixtures (the shape already prototyped inline in <code>RagSettingsResolverTest::createAgent()</code>) plus a helper that enables AI Answers via <code>AgentSettingsRegistry::saveSettings()</code> &mdash; settings are config-based now, not third-party settings on an entity.</li> <li><strong><code>tests/src/Kernel/RagSettingsResolverTest.php</code></strong>: <code>RagSettingsResolver::resolve()</code> now takes <code>(AiAgent $agent, string $viewMode)</code> and only supports the "agentic" shape (<code>tools</code>/<code>tool_usage_limits</code> read directly off the agent entity). <code>testResolvesLegacyShape()</code> tests a code path (<code>actions_enabled.rag_action</code>) that was deleted entirely during the migration &mdash; drop it, don't fix it.</li> <li><strong><code>tests/src/Kernel/AnswerServiceGatingTest.php</code></strong>: <code>AnswerService</code>'s constructor grew from 9 to 13 parameters (<code>AiAgentManager</code>, <code>AgentSettingsRegistry</code>, <code>AgentRunContext</code> are new). The "no usable sources" scenario needs a new trigger: retrieval now happens inside the agent's real execution loop (<code>AiAgentEntityWrapper::solve()</code>), so the old trick (a legacy RAG action pointing at a missing index) no longer applies. Use <code>ai_test</code>'s mock provider (already referenced as <code>echoai</code> in the old trait) to deterministically drive an agent run that doesn't call <code>rag_search</code>.</li> <li><strong><code>tests/src/Unit/AnswerServiceLogicTest.php</code></strong>: <code>collectSources()</code> doesn't exist; its score-gate/access-gate/cap logic is now split three ways &mdash; <code>sourcesFromToolResults()</code> (score gate, works off a plain array shaped by the tool result, not a <code>search_api</code> <code>ItemInterface</code>), access-gating moved into <code>renderReferences()</code>, and <code>applyEntityCap()</code> is unchanged (that sub-test still passes as-is). Drop <code>testApplyRetrievalPrefix()</code> (see Problem/Motivation) and rewrite <code>testCollectSources()</code> against <code>sourcesFromToolResults()</code>'s actual signature.</li> <li><strong><code>tests/src/Functional/AiAnswersEndpointsTest.php</code></strong>: the JSON request body key changed from <code>assistant</code> to <code>agent</code> (see <code>AiAnswersController.php</code>). Update to <code>AgentTestTrait</code> and the new key.</li> <li>Add the kernel test called for in <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/ai_answers/-/work_items/3610863" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/ai_answers/-/work_items/3610863</a></span> once the suite is working: authenticated user starts a conversation, asks a follow-up with the returned <code>conversation_id</code>, assert no <code>OutOfBoundsException</code>. That fix already landed without a test because the suite was broken at the time.</li> </ol> <p>Suggested order: <code>AgentTestTrait</code> first (everything else depends on it), then <code>RagSettingsResolverTest</code> (smallest, validates the trait), then <code>AnswerServiceGatingTest</code> (needs a working agent run), then <code>AnswerServiceLogicTest</code> (pure logic, no container), then <code>AiAnswersEndpointsTest</code>.</p> <h3>Part B &mdash; lock in undocumented design decisions with new tests</h3> <p>Several UI-layer conventions currently exist only as docblock prose, enforced by nothing. A previous incident (<span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/ai_answers/-/work_items/3610864" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/ai_answers/-/work_items/3610864</a></span>: a CSS selector styling a <code>hidden</code>-attributed element without a <code>:not([hidden])</code> guard, so the element was visible before the JS ever ran) is exactly the failure mode these would catch. None of these need a database or container &mdash; all are plain Unit tests against static PHP/CSS/Twig source:</p> <ul> <li><strong>Suggested-questions parsing</strong> (<code>QuestionBlock::getSuggestedQuestions()</code>): one question per line, trimmed, blanks dropped, order preserved, CRLF-safe. Pure logic, not yet tested.</li> <li><strong>Theme variable contract</strong>: <code>AiAnswersThemeHooks::theme()</code>'s declared variable keys for <code>ai_answers_question</code>/<code>ai_answers_answer</code> must stay a superset of what <code>QuestionBlock::build()</code>/<code>AnswerBlock::build()</code> actually render. Forgetting to update one when adding a variable to the other currently fails silently at render time.</li> <li><strong><code>data-ai-answers-role</code> / <code>hidden</code> attribute contract</strong>: both Twig templates carry explicit docblock warnings that JS and CSS depend on specific <code>data-ai-answers-*</code> attributes and <code>hidden</code> attributes. Parse the two <code>.html.twig</code> files' raw source and assert the markers each template's docblock promises are actually present.</li> <li><strong><code>:not([hidden])</code> CSS guard convention</strong>: every CSS selector styling an element the corresponding Twig template marks <code>hidden</code> must scope its <code>display</code> rule with <code>:not([hidden])</code>, or the element renders visible before JS ever toggles it (exactly <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/ai_answers/-/work_items/3610864" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/ai_answers/-/work_items/3610864</a></span>). Regression-proof that fix and enforce the convention for the next hideable element someone adds.</li> </ul> <p>Deferred (need real entity/render fixtures, so these belong with Part A's Kernel work rather than as standalone Unit tests):</p> <ul> <li><strong>DOM-id wiring contract</strong>: <code>AnswerBlock</code> derives its wrapper id as <code>Html::cleanCssIdentifier('ai-answers-answer-' . $instance_uuid)</code>; <code>QuestionBlock::getAnswerBlockOptions()</code> independently recomputes that exact same formula to build its target dropdown. Two classes duplicating one formula with nothing keeping them in sync.</li> <li><strong>"Cacheable static shell" contract</strong>: both blocks' docblocks state the render array must stay a static, fully-cacheable shell (answer/references/feedback arrive over the API via JS, never baked into cached markup). Nothing currently asserts <code>build()</code> returns this shape (<code>#attached.library</code>, <code>#attached.drupalSettings</code>, <code>#cache.contexts</code>).</li> </ul> <p>Also noted, not actionable here: the JS dispatch convention ("chip clicks and form submission must go through the same <code>dispatchAsk()</code>/<code>submit()</code> path, no new mechanism") is a real design decision but this repo has no JS test runner (no <code>package.json</code>/Jest/etc.) to enforce it. Flagging as a tooling gap rather than folding a JS test framework into this issue.</p> <h2>Remaining tasks</h2> <ul> <li>Part A: rewrite <code>AssistantTestTrait</code> &rarr; <code>AgentTestTrait</code>, fix all 4 test classes, add the #3610863 regression test.</li> <li>Part B: add the 4 new Unit contract tests described above.</li> <li>File (or fold in) a follow-up for the dead <code>retrieval_prefix</code> field.</li> </ul> <h2>User interface changes</h2> <p>None.</p> <h2>API changes</h2> <p>None.</p> <h2>Data model changes</h2> <p>None.</p>