<!-- markdownlint-disable MD024 -->

# QA-1: test coverage matrix

Analysed at commit `1e59c52a` (2026-11-13). Since then SEC (#421) and UI (#420) added tests: tool allowlist and settings tools capability (unit, integration), password-protected posts in the auto-sync e2e, and Jest grew from 204 to 413 tests (primitives, dialogs, split files). The gaps below are unchanged by that work unless noted.

## Summary

- **Tests today:** about 780 across five layers.
    - PHPUnit unit: 81 files, 350 test methods.
    - PHPUnit integration: 12 files, 96 tests. 15 call real providers; the other 81 run against WordPress stubs, not real WordPress.
    - Jest: 46 files, 204 tests.
    - Playwright e2e: 10 specs, about 85 tests.
    - Storybook: 8 files, 51 stories.
- **Well covered:** the chatbot request pipeline (preparer, runners, dispatch, session cookie, guardrails, theme), the admin assistant settings tools, the wizard, settings save, logging, `EnvResolver`, provider clients, and the MCP JSON-RPC core and OAuth store.
- **Largest gaps, by risk:**
  1. MCP: 14 of 16 tools have no test. `TokenAuth`, `Capabilities`, `McpRoutes`, `OAuthRouter` and `McpAdminRestApi` have no test, and neither does the authorize GET consent flow.
  2. WP-CLI: of about 35 subcommands, only `mcp token create` is tested.
  3. Vectorisation is never run against a real vector database. `ContentProcessor` (chunking), `PdfTextExtractor`, `DocumentLibrary`, `EmbeddingQueue`, the Embedding REST API and Qdrant in `VectorService` have no tests.
  4. Security and privacy code with no test: - `Ai/Security` (banned IPs and words) - `UserTools`, which uses `eval()` on code the admin configures - `ChatbotFeedback` public REST endpoints - `ChatbotSessionRetention` - migration `Version2026093001`, which erases visitor IPs - `HumanHandoff`, which sends email - settings import
  5. Environments: - e2e runs only on PHP 8.0, WordPress 6.8 and SQLite (Playground). - The integration suite runs only on PHP 8.4. - Nothing tests Polylang, WooCommerce, CF7, Gravity Forms or multisite. - Storybook is built but never run as tests.
- **Findings to settle before QA-5 and QA-3:**
    - **CF7, Gravity Forms and ElasticPress integration classes are dormant.** `premium/app/Integrations/ContactForm7Integration.php`, `GravityFormsIntegration.php` and `ElasticPressIntegration.php` are commented out in `app/Admin/Integrations/IntegrationManager.php` and `app/Admin/config/integrations.php`, and are not registered in `premium/app/Lib/services.php`. The `form` and `gravity_form` renderables are still in `src/chatbot/renderables/defaultRegistry.js`. ElasticPress search itself is live through `KeywordSearch/ElasticPressProvider.php`. Decide whether these ship before writing tests for them.
    - **`IntegrationManager::pluginStatus()` will warn on unknown IDs.** It reads `$this->integrations[$pluign_id]` without `isset`, so an unknown ID raises an "undefined array key" warning on PHP 8.
    - **A documented `db run` example will likely fail.** `DbCommand` documents `wp kimaai db run --version=2026012702` and says the version "must exist in Migrator::updates()", but `Version2026012702` (the cookbook migration) is not in `Migrator::updates()`.
    - **No code handles multisite.** There is no `is_multisite`, `switch_to_blog` or `wp_initialize_site`. Sub-sites rely on `Migrator::maybeUpdate()` on `init` to create their tables lazily. This is untested.

## Test layers and how they run

| Layer               | Config                                                                                                                  | Runs in                                                                        | PHP / WP / DB                                                                 |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| PHPUnit unit        | `phpunit.xml`, bootstrap `tests/bootstrap-provider-sdk.php` (hand-written WP stubs, loads `premium/premium-loader.php`) | `npm run check` (local) and `npm run check:all` (AI box, `ci/remote-check.sh`) | PHP 8.0, 8.1, 8.2, 8.3, 8.4; no WP, no DB                                     |
| PHPUnit integration | `phpunit.integration.xml`, bootstrap `tests/bootstrap-integration.php` (same stubs, `kimaai_fs()` stub = free)          | `check:all` only                                                               | PHP 8.4 only; real OpenAI/OpenRouter (with `.env.test`) and Ollama (required) |
| Jest                | `jest.config.js`, `tests/js/**`                                                                                         | `check`, `check:all`                                                           | jsdom                                                                         |
| Playwright e2e      | `tests/e2e/playwright.config.ts`, `@wp-playground/cli`                                                                  | `check:all` only                                                               | PHP 8.0, WP 6.8, SQLite (Playground); premium via `forcePluginPremium`        |
| Storybook           | `.storybook/main.js` (addon-a11y)                                                                                       | `check:all` builds it only                                                     | no test-runner                                                                |
| Plugin Check        | `ci/docker-compose.yml`                                                                                                 | `check:all`                                                                    | `wordpress:php8.3-apache`, MariaDB 11.4                                       |

`.github/workflows/` run no tests. `main.yml` only deploys on tags.

## Coverage matrix

Legend: numbers in brackets are test counts. "ind." means only indirect coverage, for example as a dependency or through a filter. "none" means no test. Gap ratings: **H** high (user-facing or security-relevant with no test), **M** medium, **L** low.

### AI providers

| Feature                                                     | Source                                                                                    | Unit                                                                           | Integration                                                                    | Jest                                 | E2E                                                                           | Storybook              | Gap                                                                                           |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------- |
| Factory, capabilities                                       | `app/Ai/Providers/Factory.php`, `Support/*`                                               | FactoryTest (3)                                                                | ind.                                                                           | none                                 | none                                                                          | none                   | L                                                                                             |
| OpenAI client (responses, chat, images, embeddings, models) | `Providers/OpenAI/*`                                                                      | OpenAiClientTest (6), ResponsesStreamParserTest (3)                            | OpenAiIntegrationTest (3), Stream (1), Embedding (1), Image (1), ModelList (1) | none                                 | admin-settings saves env; chatbot-widget real reply @slow (skips without key) | none                   | L                                                                                             |
| OpenRouter client                                           | `Providers/OpenRouter/*`                                                                  | OpenRouterClientTest (1, headers only)                                         | chat (1), stream (1), image (1), models (1)                                    | none                                 | admin-settings saves env                                                      | none                   | M                                                                                             |
| Ollama client                                               | `Providers/Ollama/*`                                                                      | OllamaClientTest (1)                                                           | chat (1), stream (1), embed (1), models (1)                                    | none                                 | wizard saves Ollama env (2); tool-calling real (unreliable on qwen2.5:3b)     | none                   | M (known reasoning-leak bug has no regression test)                                           |
| AiService                                                   | `app/Ai/AiService.php`                                                                    | AiServiceDefaultModelTest (1), AiServiceInstructionResolutionTest (4)          | none                                                                           | none                                 | ind.                                                                          | none                   | M (`run`, `saveChatResponse`, `saveImageResponse`, `testConnection`)                          |
| EnvResolver                                                 | `app/Ai/EnvResolver.php`                                                                  | EnvResolverTest (11)                                                           | none                                                                           | none                                 | none                                                                          | none                   | L                                                                                             |
| AiModels                                                    | `app/Ai/AiModels.php`                                                                     | AiModelsTest (7), AiModelsTemperatureTest (2)                                  | none                                                                           | none                                 | wizard gpt-5.5 (1)                                                            | none                   | L                                                                                             |
| UsageTracker                                                | `app/Ai/UsageTracker.php`                                                                 | UsageTrackerTest (3, extraction only)                                          | none                                                                           | none                                 | none                                                                          | none                   | M (persistence and aggregation feed `usage report` and `usage_stats`)                         |
| Streaming                                                   | `Stream/*`, `Support/SseParser.php`, `ChatbotSseEmitter`, `ChatbotStreamingRequestRunner` | ResponsesStreamParser (3), OpenAiClient stream (2), StreamingRequestRunner (2) | StreamChatIntegrationTest (3)                                                  | sse (3), useChat streaming (about 4) | none                                                                          | FrontendStreamingStory | M to H (`ChatCompletionsStreamParser`, `SseParser` untested directly; no e2e stream)          |
| Connection test REST                                        | `app/Ai/RestApi.php`                                                                      | none                                                                           | none                                                                           | useTestConnection (3)                | wizard blocks invalid env (1)                                                 | none                   | M                                                                                             |
| HTTP transport                                              | `Http/CurlHttpClient.php`                                                                 | none (FakeHttpClient replaces it)                                              | ind.                                                                           | n/a                                  | ind.                                                                          | n/a                    | done in QA-8: `WordPressHttpClient` (WordPress HTTP API; cURL only for streaming), unit tests |

### Chatbot (free)

| Feature                         | Source                                                       | Unit                                                                                                           | Integration               | Jest                                                | E2E                                                                | Storybook                        | Gap                                                       |
| ------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------- | --------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------- | --------------------------------------------------------- |
| REST routes and dispatch        | `ChatBot/ChatBot.php`                                        | ChatBotDispatchTest (3), ChatBotRouteArgsTest (2), ChatBotQuickActionsPayloadTest (2)                          | none                      | createWpConfig (3)                                  | chatbot-widget (5), session-cookie REST (7)                        | Chatbot (16)                     | L                                                         |
| Request preparer                | `ChatbotRequestPreparer.php`                                 | 9                                                                                                              | none                      | none                                                | ind.                                                               | none                             | L                                                         |
| Normal runner                   | `ChatbotNormalRequestRunner.php`                             | 3                                                                                                              | FinalMessageChainTest (4) | useChat (about 10)                                  | widget                                                             | none                             | L                                                         |
| Streaming runner, SSE emitter   | `ChatbotStreamingRequestRunner.php`, `ChatbotSseEmitter.php` | 2                                                                                                              | none                      | useChat streaming                                   | none                                                               | story                            | M                                                         |
| CLI SSE emitter                 | `ChatbotCliSseEmitter.php`                                   | none                                                                                                           | none                      | n/a                                                 | n/a                                                                | n/a                              | M (QA-3)                                                  |
| Rate limiting                   | `ChatbotRateLimiter.php`, `ChatbotRateLimitModel`            | RateLimiterTest (4), Preparer (3)                                                                              | none                      | none                                                | none                                                               | none                             | M                                                         |
| Session cookie                  | `ChatBot.php`                                                | ChatbotSessionCookieTest (9)                                                                                   | none                      | none                                                | chatbot-session-cookie (11)                                        | none                             | L                                                         |
| Session retention               | `ChatbotSessionRetention.php`                                | none (only unscheduling in SchemaUninstallTest)                                                                | none                      | none                                                | none                                                               | none                             | **H** (privacy, scheduled deletion)                       |
| Content awareness               | `ChatbotContentAwareness.php`                                | 4                                                                                                              | none                      | none                                                | none                                                               | none                             | L to M                                                    |
| Guardrails                      | `OutputGuardrails.php`                                       | 6                                                                                                              | FinalMessageChainTest     | none                                                | enterprise-kb (1)                                                  | none                             | L                                                         |
| Banned IPs and words            | `app/Ai/Security.php`                                        | none (mocked as dependency)                                                                                    | none                      | none                                                | none                                                               | none                             | **H**                                                     |
| Instruction composer            | `InstructionComposer.php`                                    | 7                                                                                                              | none                      | none                                                | enterprise-kb (2)                                                  | none                             | L                                                         |
| Tool calling                    | `ChatBot/Tools/*`, `app/Ai/ToolRegistry.php`                 | ChatbotToolRegistryTest (3), ToolCallOrchestratorTest (6); ToolCommandHandler and ToolContinuationBuilder ind. | none                      | useChat tool trace (1)                              | chatbot-tool-calling.real (one per provider, needs keys or Ollama) | none                             | M (default tools such as `wp_get_post` have no unit test) |
| Feedback and CSAT REST          | `ChatbotFeedback.php`, `ChatFeedbackModel`, `ChatCsatModel`  | none                                                                                                           | none                      | wpFeedbackApi (1), useChat feedback (2)             | none                                                               | FrontendWithMessageFeedbackStory | **H** (public write endpoints, validation)                |
| Request language (multilingual) | `ChatbotRequestLanguage.php`, `Admin/SettingsI18n.php`       | ChatbotRequestLanguageTest (7, WPML via filters)                                                               | none                      | none                                                | none                                                               | none                             | M (Polylang paths untested)                               |
| Theme                           | `ChatbotTheme.php`, `ChatbotAssets.php`                      | ChatbotThemeTest (7), ChatbotAssetsTest (7)                                                                    | none                      | chatbotTheme (6)                                    | colour vars (1), a11y light/dark (2)                               | Foundations (5)                  | L (no RTL anywhere)                                       |
| AI disclosure                   | `ChatbotAssets.php`, Composer, FloatingMountShell            | none                                                                                                           | none                      | ChatInput, ChatbotPreview, FloatingAttentionPopover | chatbot-a11y (2)                                                   | none                             | L                                                         |
| White label                     | `premium/app/Features/WhiteLabel.php`                        | WhiteLabelTest (3)                                                                                             | none                      | none                                                | white-label (1)                                                    | none                             | L                                                         |
| Widget settings propagation     | `ChatbotAssets.php`, `config/chatbot.php`                    | ChatbotAssetsTest                                                                                              | none                      | normalizeChatbotConfig (10), deriveCapabilities (5) | chatbot-settings (32)                                              | Chatbot                          | L                                                         |
| GDPR consent                    | front end                                                    | none                                                                                                           | none                      | none                                                | chatbot-settings (1)                                               | 2 stories                        | L to M                                                    |
| Quick actions                   | `NormalizesQuickActions`, `ChatbotPremium`                   | AdminAssistantQuickActions (2), ChatbotPremiumQuickActions (2)                                                 | none                      | wpQuickActionsApi (3), useQuickActionsStart (3)     | popover quick actions (1)                                          | QuickActionsBarStory             | L                                                         |
| Chat history admin              | `ChatbotAdmin.php`                                           | none                                                                                                           | none                      | useChatHistory (4), useChatSessions (5)             | none                                                               | none                             | M (admin delete routes)                                   |
| Provider error normaliser       | `ChatbotProviderErrorNormalizer.php`                         | 2                                                                                                              | none                      | sse error (1)                                       | none                                                               | FrontendErrorStateStory          | L                                                         |

### Admin (free)

| Feature                          | Source                                                                     | Unit                                                                                                                                                                                           | Integration                                                    | Jest                                                                                                                        | E2E                                               | Storybook                                                      | Gap                                                                                              |
| -------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Admin assistant                  | `app/AdminAssistant/*`                                                     | ConfigProvider (3), HistoryModel (2), QuickActions (2), RequestPreparer (10), AdminAssistantTest (2), SettingsPreviewResolverBatch (4), AssistantRenderables (3), BuildsAssistantAiPayload (3) | AdminAssistantSettingsToolsTest (49), WorkflowManagerTest (17) | ActionBridge (2), createWpAdminAssistantConfig (8), wpAdminTransport (3), wpAdminHelpCenterApi (3), AdminSessionsScreen (6) | admin-settings (2)                                | AdminChatbot (12), AdminAssistantPlayable (1), Renderables (4) | L to M (`AdminAssistantSessionRollbackService` and `BuildsAdminAssistantHistoryExport` untested) |
| Setup wizard                     | `Admin/Wizard/*`                                                           | WizardTest (7)                                                                                                                                                                                 | none                                                           | WizardApp (4)                                                                                                               | setup-wizard (9), admin-settings (2)              | none                                                           | L                                                                                                |
| Settings save and sanitise       | `Admin/Settings.php`, `SettingsUiConfigProvider.php`                       | EndpointSanitization (3), UnknownKeyPreservation (5), UiConfigProvider (9), ChatbotAiEnvOptions (3)                                                                                            | none                                                           | useSettings (10), SettingsUiShell (7), helpers (8), RepeatableTable (8)                                                     | admin-settings (4), enterprise-kb schema save (1) | Fields (6)                                                     | L                                                                                                |
| Settings export                  | `Settings.php` `/settings-export`                                          | SettingsSensitiveExportTest (6)                                                                                                                                                                | none                                                           | none                                                                                                                        | none                                              | none                                                           | L                                                                                                |
| Settings import                  | `Settings.php` `/settings-import`, `src/admin/components/ExportSettings/*` | none                                                                                                                                                                                           | none                                                           | none                                                                                                                        | none                                              | none                                                           | **H**                                                                                            |
| Admin theme                      | `Admin/AdminTheme.php`                                                     | none                                                                                                                                                                                           | none                                                           | AdminThemeToggle (6), useAdminTheme (3)                                                                                     | none                                              | none                                                           | M                                                                                                |
| Logging                          | `app/Logging/*`                                                            | LogAdminRoutes (3), LogCleanupScheduler (4), LogFileManager (6)                                                                                                                                | none                                                           | ShowLogFile (2), useLogFiles (6)                                                                                            | none                                              | none                                                           | L                                                                                                |
| Uninstall                        | `Schema.php`                                                               | SchemaUninstallTest (5)                                                                                                                                                                        | none                                                           | none                                                                                                                        | none                                              | none                                                           | L                                                                                                |
| WooCommerce integration (free)   | `Admin/Integrations/WooCommerceIntegration.php`                            | none                                                                                                                                                                                           | none                                                           | none                                                                                                                        | none                                              | none                                                           | M                                                                                                |
| IntegrationManager               | `Admin/Integrations/IntegrationManager.php`                                | none                                                                                                                                                                                           | none                                                           | none                                                                                                                        | none                                              | none                                                           | M (unknown-key warning)                                                                          |
| AddonManager                     | `app/Addons/*`                                                             | none                                                                                                                                                                                           | none                                                           | n/a                                                                                                                         | none                                              | n/a                                                            | M                                                                                                |
| Debug info, admin assets, Logger | `DebugInfo.php`, `Admin/Assets.php`, `Logger.php`                          | none                                                                                                                                                                                           | none                                                           | n/a                                                                                                                         | ind.                                              | n/a                                                            | L                                                                                                |
| Version and runtime              | `kimaai.php`, vendor patches                                               | VersionConsistency (2), SymfonyPatchApplied (2), SymfonyPhp84Deprecation (1)                                                                                                                   | none                                                           | n/a                                                                                                                         | n/a                                               | n/a                                                            | L                                                                                                |

### Database

| Feature                                        | Unit                               | Integration / e2e             | Gap                                                              |
| ---------------------------------------------- | ---------------------------------- | ----------------------------- | ---------------------------------------------------------------- |
| `Migrator` queue logic                         | MigratorTest (5)                   | e2e activation on SQLite only | M (never run on MySQL or MariaDB except Plugin Check activation) |
| `SchemaRegistry::applySchema`, `Db` helpers    | none                               | ind.                          | M                                                                |
| 2026012801 feedback and CSAT tables            | none                               | ind.                          | M                                                                |
| 2026050501 rollback table                      | none                               | ind.                          | M                                                                |
| 2026072701 gpt-5-chat-latest remap             | none                               | none                          | M                                                                |
| 2026072901 presets removal                     | PresetsRemovalMigrationTest (2)    | none                          | L                                                                |
| 2026093001 erase visitor IPs                   | none                               | none                          | **H** (privacy)                                                  |
| 2026111301 Replicate removal                   | ReplicateRemovalMigrationTest (11) | none                          | L                                                                |
| 2026111302 powered-by opt-in                   | PoweredByOptInMigrationTest (4)    | chatbot-settings (1)          | L                                                                |
| 2026012702 cookbook migration (not registered) | none                               | none                          | L (fix doc drift)                                                |

### Premium: embedding and vector store

| Feature                        | Source                        | Unit                                               | Integration              | Jest                                                       | E2E                                      | Gap                                         |
| ------------------------------ | ----------------------------- | -------------------------------------------------- | ------------------------ | ---------------------------------------------------------- | ---------------------------------------- | ------------------------------------------- |
| Embedding generator            | `EmbeddingGenerator.php`      | 2                                                  | provider embed tests (2) | none                                                       | ind. (fake HTTP)                         | M                                           |
| Sync core and environments     | `Embedding.php`               | EmbeddingEnvironmentTest (11), ChatbotFallback (1) | none                     | useEmbedding (2), useEmbeddingEnv (3), EmbeddingHeader (1) | ind.                                     | **H** (`sync()` never against a real store) |
| Auto-sync                      | `PostEmbedSync.php`           | PostEmbedSyncTest (1)                              | none                     | none                                                       | embedding-auto-sync (6, fake vectors)    | L to M                                      |
| Prune stale chunks             | `Embedding::pruneStaleChunks` | 5                                                  | none                     | none                                                       | none                                     | M (no real store)                           |
| PDF extraction                 | `PdfTextExtractor.php`        | none                                               | none                     | none                                                       | none                                     | **H**                                       |
| Document library               | `DocumentLibrary.php`         | none                                               | none                     | none                                                       | none                                     | **H**                                       |
| Queue                          | `EmbeddingQueue.php`          | none                                               | none                     | none                                                       | ind.                                     | **H**                                       |
| Content templates              | `TemplateFlattener.php`       | 4                                                  | none                     | none                                                       | page renders (1)                         | L                                           |
| Chunking and rendering         | `ContentProcessor.php`        | none                                               | none                     | none                                                       | ind.                                     | **H**                                       |
| Sanitiser                      | `ContentSanitizer.php`        | none                                               | none                     | none                                                       | none                                     | M                                           |
| Index health and reconcile     | `IndexHealth.php`             | none                                               | none                     | HealthPanel (2)                                            | weekly reconcile (1)                     | M                                           |
| Diagnostics                    | `EmbeddingDiagnostics.php`    | 4                                                  | none                     | HealthPanel, SyncPanel (2)                                 | none                                     | L                                           |
| Meta filter                    | `MetaFilter.php`              | 4                                                  | none                     | none                                                       | none                                     | L                                           |
| VectorService Pinecone         | `VectorService.php`           | VectorServiceTest (6)                              | none                     | none                                                       | stubbed via `kimaai_vector_service_call` | M                                           |
| VectorService Qdrant           | `VectorService.php`           | none (diagnostics only)                            | none                     | none                                                       | none                                     | **H**                                       |
| Embedding REST API (20 routes) | `Embedding/RestApi.php`       | none                                               | none                     | hooks mocked                                               | ind.                                     | **H** (permissions)                         |

### Premium: retrieval, chatbot extras, eval, analytics, integrations

| Feature                                      | Source                                   | Unit           | Integration                | Jest                  | E2E                 | Gap                                                |
| -------------------------------------------- | ---------------------------------------- | -------------- | -------------------------- | --------------------- | ------------------- | -------------------------------------------------- |
| Hybrid fusion                                | `FunctionCall/HybridFusion.php`          | 3              | none                       | none                  | toggles visible (1) | L                                                  |
| Keyword search (manager and 4 providers)     | `FunctionCall/KeywordSearch/*`           | none           | none                       | none                  | none                | M to H                                             |
| Query condenser                              | `QueryCondenser.php`                     | none           | QueryCondenserFlowTest (6) | none                  | none                | L                                                  |
| Tool router (knowledge search)               | `ToolRouter.php`                         | ind. (1)       | none                       | none                  | ind.                | **H**                                              |
| User tools                                   | `UserTools.php` (uses `eval`)            | none           | none                       | none                  | none                | **H**                                              |
| Answer quality, citations                    | `AnswerQuality.php`, `SourceTracker.php` | none           | FinalMessageChainTest (4)  | none                  | none                | M                                                  |
| Human handoff                                | `HumanHandoff.php`                       | none           | none                       | none                  | none                | **H**                                              |
| Pinned answers                               | `PinnedAnswers.php`                      | similarity (5) | PinnedAnswersFlowTest (5)  | none                  | page renders (1)    | L                                                  |
| Eval runner                                  | `Eval/EvalRunner.php`                    | statics (6)    | none                       | none                  | page renders        | M                                                  |
| Eval scheduler                               | `EvalScheduler.php`                      | none           | none                       | none                  | none                | M                                                  |
| Knowledge-gap miner                          | `KnowledgeGapMiner.php`                  | none           | none                       | none                  | none                | M                                                  |
| Feedback analytics                           | `ChatbotFeedback/*`                      | none           | none                       | useAnalyticsQuery (4) | none                | M                                                  |
| WooCommerce cards, recommendations, similar  | `Integrations/WooCommerce/*`             | none           | none                       | none                  | none                | M to H (server HTML via `dangerouslySetInnerHTML`) |
| CF7, Gravity Forms, ElasticPress integration | `Integrations/*.php`                     | none           | none                       | none                  | none                | dormant, decision first                            |

### MCP server (premium/app/Mcp)

| Component                                                   | Unit                                                                                                                              | E2E  | Gap                                                                                                   |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------------------------------------------------------------- |
| `McpServer` JSON-RPC                                        | McpServerTest (9: initialise, scope-gated list, call ok, denied, exception, unknown, notification, parse error, method not found) | none | L                                                                                                     |
| `McpRoutes` (REST `/mcp`, `WWW-Authenticate`)               | none                                                                                                                              | none | **H**                                                                                                 |
| `Auth/TokenAuth` (bearer and cookie)                        | none                                                                                                                              | none | **H**                                                                                                 |
| `Auth/TokenStore`                                           | 6                                                                                                                                 | none | L                                                                                                     |
| `Auth/Scopes`, `AuthContext`                                | 4, 3                                                                                                                              | none | L                                                                                                     |
| `Auth/Capabilities` (`kimaai_mcp` cap)                      | none                                                                                                                              | none | **H**                                                                                                 |
| `OAuth/OAuthServer`                                         | 10 (metadata, register, code, PKCE mismatch, binding, grant, refresh, approve, deny, nonce)                                       | none | M to H (authorize GET, login redirect, scope narrowing, redirect URI rules, S256 enforcement, expiry) |
| `OAuth/OAuthStore`                                          | 9                                                                                                                                 | none | L                                                                                                     |
| `OAuth/Pkce`                                                | 3                                                                                                                                 | none | L                                                                                                     |
| `OAuth/OAuthRouter` (`template_redirect`, well-known, CORS) | none                                                                                                                              | none | **H**                                                                                                 |
| `Admin/McpAdminRestApi` (overview, settings, tokens)        | none                                                                                                                              | none | **H**                                                                                                 |
| `Admin/McpSettings`                                         | 1                                                                                                                                 | none | M                                                                                                     |
| `Audit/AuditLogger`, `McpAuditModel`                        | ind. (McpServerTest checks calls)                                                                                                 | none | M                                                                                                     |
| `McpModule` (90-day prune)                                  | none                                                                                                                              | none | M                                                                                                     |
| `Redaction/PiiRedactor`                                     | 6                                                                                                                                 | none | M (not tested inside tools or audit)                                                                  |
| `GroundednessLogger`, `GroundednessLogModel`                | none                                                                                                                              | none | M                                                                                                     |
| Jest `src/admin/mcp/McpApp.jsx`                             | none                                                                                                                              | none | **H**                                                                                                 |

#### MCP tools

| Tool class            | Name                 | Scope                         | Tests                                     | Gap                           |
| --------------------- | -------------------- | ----------------------------- | ----------------------------------------- | ----------------------------- |
| AddEvalCaseTool       | `add_eval_case`      | write                         | AddEvalCaseToolTest (2, category default) | M                             |
| AskChatbotTool        | `ask_chatbot`        | read                          | AskChatbotToolTest (2, trace summary)     | M                             |
| CheckCoverageTool     | `check_coverage`     | read                          | none                                      | M                             |
| DiagnoseQueryTool     | `diagnose_query`     | read                          | none                                      | M                             |
| EvalHistoryTool       | `eval_history`       | read                          | none                                      | L                             |
| FeedbackOverviewTool  | `feedback_overview`  | read, redacts unless read:raw | none                                      | **H**                         |
| GetIncidentTool       | `get_incident`       | read, read:raw                | none                                      | **H**                         |
| GetSettingsTool       | `get_settings`       | read                          | none                                      | **H** (secrets must not leak) |
| InspectRetrievalTool  | `inspect_retrieval`  | read                          | none                                      | M                             |
| KnowledgeGapsTool     | `knowledge_gaps`     | read, redacts unless read:raw | none                                      | **H**                         |
| ListConversationsTool | `list_conversations` | read, redacts unless read:raw | none                                      | **H**                         |
| ReembedTool           | `reembed`            | write                         | none                                      | **H**                         |
| RollbackChangeTool    | `rollback_change`    | write                         | none                                      | **H**                         |
| RunEvalTool           | `run_eval`           | write                         | none                                      | **H**                         |
| UpdateSettingsTool    | `update_settings`    | write                         | none                                      | **H**                         |
| UsageStatsTool        | `usage_stats`        | read                          | none                                      | M                             |

### WP-CLI commands

All are registered with `registerCommand` in `premium/app/Lib/services.php` and loaded by `app/Loader.php::loadCommands()`.

| Command                         | Subcommands and options                                                                                                                                                                                                                                | Tests                           | Gap   |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | ----- |
| `wp kimaai` (KimaAICLI)         | `run <chat\|image\|embed>` (`--provider --model --payload --file --param --raw --pretty`); `chat` (`--session-id --post-id --lang --provider --model --command --force-tool --parallel-tool-calls --callback --callback-args --stream --raw --pretty`) | none                            | **H** |
| `wp kimaai vectors` (Vectors)   | `sync` (`--env --collection --namespace --post_type --post_id --modified_after --limit --force --dry_run`), `query`, `fetch`, `delete` (`--ids --filter --all`), `stats`, `health`, `freshness`, `reconcile`                                           | none                            | **H** |
| `wp kimaai vectors config`      | `get` (`--env --all --format`)                                                                                                                                                                                                                         | none                            | M     |
| `wp kimaai vectors collections` | `list`, `create`, `delete`                                                                                                                                                                                                                             | none                            | M     |
| `wp kimaai vectors items`       | `list` (`--namespace --search --orderby --order --page --per-page --fields --format`), `get`, `delete` (`--local-only`)                                                                                                                                | none                            | M     |
| `wp kimaai db`                  | `status`, `migrate` (`--one-step`), `scenario` (`--enable --disable --reset`), `run` (`--version --scenario --reset-scenarios`)                                                                                                                        | none                            | M     |
| `wp kimaai eval`                | `run` (`--file --stored --only --limit --lang --judge --log`), `history` (`--limit`)                                                                                                                                                                   | none                            | M     |
| `wp kimaai gaps`                | `report` (`--days --min-cluster --format`)                                                                                                                                                                                                             | none                            | M     |
| `wp kimaai usage`               | `report` (`--days`)                                                                                                                                                                                                                                    | none                            | M     |
| `wp kimaai mcp token`           | `create` (`--label --scopes`), `list`, `revoke <id>`                                                                                                                                                                                                   | McpCommandTest (2, create only) | M     |

Addon commands come through `AddonManager::boot()` on `cli_init`: untested.

### Environments

| Dimension             | Covered today                                                           | Missing                                                                               |
| --------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| PHP                   | unit on 8.0 to 8.4; integration on 8.4; e2e on 8.0; Plugin Check on 8.3 | integration on 8.0; e2e on 8.4                                                        |
| WordPress             | e2e 6.8; Plugin Check latest image                                      | 6.0 (minimum in `kimaai.php`), latest and 7.0 ("Tested up to") in e2e                 |
| Database              | SQLite (Playground); MariaDB 11.4 for Plugin Check activation only      | migrations and `dbDelta` on MariaDB or MySQL 8                                        |
| WPML                  | filter-based fake in ChatbotRequestLanguageTest                         | `SettingsI18n`, ToolRouter language, embedding languages                              |
| Polylang              | none                                                                    | everything (`pll_*` paths in `SettingsI18n`, `ToolRouter`, `AbstractWpQueryProvider`) |
| WooCommerce           | none                                                                    | product cards, recommendations, similar                                               |
| CF7, Gravity Forms    | none                                                                    | dormant code                                                                          |
| Multisite             | none                                                                    | network activation, sub-site lazy schema, per-site options, uninstall                 |
| Free vs premium build | e2e forces premium; integration stubs free                              | e2e on the staged free plugin (`ci/stage-free-plugin.mjs`)                            |

## What to add, prioritised

### QA-2: MCP (write tools first, then auth and transport, then read tools)

**1. Write tools**, unit, new folder `tests/unit/Mcp/Tools/`:

- `UpdateSettingsToolTest`
    - `testAppliesScalarOperationAndReturnsRollbackSessionId`
    - `testAppliesFreeTextAppendEdit`
    - `testRejectsUnknownPathWithoutPartialWrite`
    - `testRejectsInvalidEnumValue`
    - `testRejectsPremiumOnlyPathOnFreeInstall`
    - `testAuditSummaryDoesNotContainSecretValues`
- `RollbackChangeToolTest`
    - `testRevertsEveryChangeOfTheSession`
    - `testUnknownSessionReturnsError`
    - `testSecondRollbackChangesNothing`
- `ReembedToolTest`
    - `testSinglePostIsQueued`
    - `testPostTypeTarget`
    - `testModifiedAfterTarget`
    - `testRejectsCallWithoutTarget`
    - `testEnvironmentMismatchReturnsError`
- `RunEvalToolTest`
    - `testRunsStoredCasesAndReturnsSummary`
    - `testCategoryFilterAndLimit`
    - `testNoStoredCasesReturnsEmptySummary`
    - `testRunIsPersisted`
- `AddEvalCaseToolTest` additions
    - `testRejectsMissingTurns`
    - `testDuplicateCaseIdBehaviour`
    - `testReturnsRollbackSessionId`

**2. Auth and transport**, unit:

- `TokenAuthTest`
    - `testValidBearerReturnsContextWithStoredScopes`
    - `testRevokedTokenIsRejected`
    - `testUnknownTokenIsRejected`
    - `testMalformedAuthorizationHeaderIsRejected`
    - `testOAuthAccessTokenResolves`
    - `testExpiredOAuthAccessTokenIsRejected`
    - `testCookieAuthRequiresNonceAndCapability`
    - `testUserWithoutMcpCapabilityIsRejected`
    - `testSuccessfulAuthTouchesLastUsed`
- `CapabilitiesTest`
    - `testEnsureGrantsCapToAdministratorsOnce`
    - `testVersionBumpRegrants`
    - `testUserCanRequiresCap`
- `McpRoutesTest`
    - `testUnauthenticatedRequestGets401WithResourceMetadataHeader`
    - `testDisabledEndpointIsNotServed`
    - `testPostDispatchesJsonRpc`
    - `testUnsupportedMethodIsRejected`
- `OAuthServerTest` additions
    - `testAuthorizeGetRedirectsAnonymousUserToLogin`
    - `testAuthorizeGetRendersConsentWithEscapedClientName`
    - `testAuthorizeGetRejectsUnknownClient`
    - `testAuthorizeGetRejectsUnregisteredRedirectUri`
    - `testAuthorizeGetRequiresS256Challenge`
    - `testAuthorizeGetRejectsResponseTypeOtherThanCode`
    - `testNonAdminRequestedScopesAreNarrowedToRead`
    - `testUserWithoutMcpCapGetsAccessDenied`
    - `testRegisterRejectsHttpRedirectExceptLoopback`
    - `testExpiredAuthCodeIsRejected`
    - `testRotatedRefreshTokenCannotBeReused`
- `OAuthRouterTest`
    - `testServesAuthorizationServerMetadata`
    - `testServesProtectedResourceMetadata`
    - `testOptionsPreflightSendsCorsHeaders`
    - `testTokenAndRegisterOnlyAcceptPost`
    - `testIgnoresUnrelatedUris`
- `McpAdminRestApiTest`
    - `testAllRoutesRequireManageOptions`
    - `testCreateTokenReturnsRawTokenOnce`
    - `testRevokeTokenRemovesIt`
    - `testSaveSettingsSanitisesInput`

**3. Scope matrix and contract**, unit:

- `McpScopeMatrixTest`: a data provider over the 16 tools times {read, read:raw, write, admin}, asserting both `tools/list` visibility and the `tools/call` allow or deny result.
- `ToolSchemaContractTest`
    - `testEveryToolHasUniqueSnakeCaseName`
    - `testInputSchemaIsObjectSchema`
    - `testRequiredFieldsExistInProperties`
    - `testWriteToolsRequireWriteScope`

**4. Audit and PII**, unit:

- `AuditLoggerTest`
    - `testArgsAreRedactedBeforeStorage`
    - `testSummaryIsTruncatedTo500Chars`
    - `testStoresStatusUserAndTokenLabel`
- `McpModuleTest`
    - `testPrunesAuditRowsOlderThan90Days`
    - `testPruneRunsAtMostOncePerDay`
- `GroundednessLoggerTest`
    - `testLogsUngroundedAnswerTruncatedTo8000Chars`
    - `testDoesNothingWhenDisabled`
- Redaction inside tools, for each of `FeedbackOverviewTool`, `GetIncidentTool`, `KnowledgeGapsTool` and `ListConversationsTool`:
    - `testRedactsWithoutReadRaw`
    - `testReturnsRawWithReadRaw`
    - `testResponseFlagsRedactedTrue`

**5. Read tools**, unit:

- `GetSettingsToolTest`
    - `testListsWritableSettingsOnly`
    - `testNeverReturnsApiKeys`
- `CheckCoverageToolTest`
    - `testReportsHealthChecks`
    - `testPostChunkCountPerNamespace`
    - `testUnknownEnvironment`
- `DiagnoseQueryToolTest`
    - `testClassifiesMissingContent`
    - `testClassifiesWeakTerminology`
    - `testClassifiesRoutingProblem`
- `InspectRetrievalToolTest`
    - `testReturnsRankedChunksWithScores`
    - `testRespectsTopK`
- `EvalHistoryToolTest`
    - `testNewestFirstWithLimit`
- `UsageStatsToolTest`
    - `testDailyTotalsAndMonthTotal`
    - `testDaysIsClamped`
- `AskChatbotToolTest` addition
    - `testRunsPipelineWithFakeProvider`

**6. e2e**, Playground with premium:

- `mcp-oauth.spec.ts`
    - "a client registers, authorises with PKCE and lists tools"
    - "denying consent returns access_denied to the client"
    - "a non-admin user only gets the read scope"
    - "a revoked token gets 401"
- `mcp-admin.spec.ts`
    - "enabling the endpoint and minting a token shows it once"
    - "the token list hides the raw token and revoke removes it"
    - "a denied tool call appears in the audit log"
- Optional: an interoperability smoke test with the MCP Inspector CLI against Playground.

### QA-3: WP-CLI

Infrastructure: reuse `ci/docker-compose.yml` (WordPress, MariaDB and the `cli` service), mount the premium build, and add a `tests/cli` suite. It runs `wp ...` and asserts on exit code and `--format=json` output. Add unit tests with an extracted `FakeWpCli` (see the infrastructure gaps below) for argument parsing.

- **Smoke:** `test_help_lists_all_ten_kimaai_namespaces_on_premium`, `test_free_build_registers_no_kimaai_commands`.
- **`wp kimaai run`:**
    - `test_run_chat_with_ollama_prints_answer`
    - `test_run_embed_prints_vector_of_expected_dimension`
    - `test_run_image_without_provider_errors`
    - `test_run_unknown_type_errors`
    - `test_run_payload_file_and_param_are_merged`
    - `test_run_raw_and_pretty_output`
- **`wp kimaai chat`:**
    - `test_chat_creates_session_and_continues_with_session_id`
    - `test_chat_stream_prints_sse_frames` (covers `ChatbotCliSseEmitter`)
    - `test_chat_force_tool_runs_wp_get_post`
    - `test_chat_lang_sets_request_language`
    - `test_chat_invalid_callback_args_json_errors`
- **`wp kimaai vectors`:**
    - `test_sync_dry_run_counts_without_upserting`
    - `test_sync_single_post`
    - `test_sync_post_type_filter`
    - `test_sync_modified_after`
    - `test_sync_force_reembeds`
    - `test_sync_limit`
    - `test_query_text_returns_matches`
    - `test_query_filter_json`
    - `test_fetch_by_id`
    - `test_delete_ids`, `test_delete_all_requires_flag`
    - `test_stats`
    - `test_health_ok_and_unreachable`
    - `test_freshness_reports_stale_posts`
    - `test_reconcile_removes_orphans`
- **`vectors config`:** `test_get_masks_api_keys`, `test_get_all_json`.
- **`vectors collections`:** `test_list_create_delete_round_trip`.
- **`vectors items`:** `test_list_pagination_and_search`, `test_get_unknown_id_errors`, `test_delete_local_only_keeps_remote`.
- **`db`:**
    - `test_status_shows_current_version`
    - `test_migrate_runs_pending`
    - `test_migrate_one_step`
    - `test_scenario_enable_disable_reset`
    - `test_run_unknown_version_errors`
    - `test_run_documented_example_version` (exposes the 2026012702 doc drift)
- **`eval`:**
    - `test_run_from_file`
    - `test_run_stored_only_category_and_limit`
    - `test_run_lang`
    - `test_run_judge_with_ollama`
    - `test_run_log_writes_file`
    - `test_history_limit`
- **`gaps`:** `test_report_days_min_cluster_and_json_format`.
- **`usage`:** `test_report_days`.
- **`mcp token`:** `test_list_hides_hash`, `test_revoke_unknown_id_errors`, `test_create_with_scopes_sanitises`.

### QA-4: vectorisation end to end (Qdrant in Docker, Ollama embeddings)

Infrastructure: add a pinned `qdrant/qdrant` service to `ci/docker-compose.yml`. Point the embedding environment at `OLLAMA_BASE_URL` with `nomic-embed-text:v1.5`. Give the suite its own collection per run.

1. **Unit, no infrastructure:**
      - `ContentProcessorTest`
          - `testChunkRespectsMaxBytes`
          - `testChunkBoundariesKeepSentences`
          - `testHtmlToTextPreservesHeadingsAndLists`
          - `testShortcodesAndScriptsAreStripped`
          - `testTruncateBytesIsUtf8Safe`
          - `testNormalizeFarsi`
      - `ContentSanitizerTest`
      - `PdfTextExtractorTest`, with fixture PDFs:
          - `testExtractsTextFromSimplePdf`
          - `testEncryptedPdfFailsGracefully`
          - `testImageOnlyPdfReturnsEmpty`
          - `testOversizedPdfIsSkipped`
      - `DocumentLibraryTest`
          - `testSupportedMimeTypes`
          - `testKnowledgeBaseFieldSaves`
          - `testExcludedDocumentsAreNotEmbedded`
      - `EmbeddingQueueTest`
          - `testEnqueueSchedulesOnePageAction`
          - `testStatusTransitions`
          - `testBumpCounts`
          - `testApplyModifiedAfter`
      - `IndexHealthTest`
          - `testReportFlagsOrphans`
          - `testPurgeOrphans`
          - `testScheduleEnsured`
      - `EmbeddingRestApiTest`
          - `testEveryRouteRequiresManageOptions`
          - `testSyncEnqueueValidatesArgs`
2. **Integration, PHPUnit, no WordPress:**
      - `VectorServiceQdrantIntegrationTest`
          - `testCreateCollectionWith768Dims`
          - `testUpsertQueryFetchDeleteRoundTrip`
          - `testMetaFilterRestrictsByPostType`
          - `testDescribeStatsCountsPoints`
          - `testHealthOkThen503WhenStopped`
          - `testDeleteByFilter`
          - `testDimensionMismatchIsReported`
      - `EmbeddingGeneratorOllamaIntegrationTest`
          - `testNomicEmbedReturns768Dims`
          - `testSameTextGivesSameVector`
3. **End to end, Docker WordPress plus WP-CLI:**
      - `test_full_sync_puts_posts_into_qdrant_and_query_finds_them`
      - `test_publish_auto_embeds_through_action_scheduler`
      - `test_shortening_a_post_prunes_stale_chunks_in_qdrant`
      - `test_unpublish_and_delete_purge_points`
      - `test_pdf_in_document_library_is_embedded`
      - `test_reconcile_purges_orphans`
      - `test_hybrid_search_merges_wp_core_keyword_and_vector_hits`
      - `test_query_condenser_rewrites_follow_up_with_ollama`
      - `test_chatbot_answer_cites_retrieved_post`
      - From QA-3, the `tests/cli` cases that need a reachable store: the sync options (`--dry_run`, `--post_id`, `--post_type`, `--modified_after`, `--force`, `--limit`), `vectors fetch`, `vectors stats`, `vectors health` when healthy, `vectors collections` list and create, and `vectors query` returning matches. QA-3 tests only how they fail while the store is unreachable.
4. **e2e:** extend the `kimaai_vector_service_call` stub so `query` returns seeded matches. Then add "knowledge search answer shows citations" and "embedding query panel shows scored results".

### QA-5: environments

- **PHP:** run the integration suite on 8.0 and 8.4. Make the e2e fixture's `php` configurable through an environment variable and run 8.0 and 8.4.
- **WordPress:** make the e2e `wp` configurable and run 6.0 (the minimum) and latest. Check that Playground supports 6.0 [source missing]; if not, use the Docker stack with a `wordpress:6.0` image. Add "Tested up to" smoke tests on 7.0.
- **Database:** `test_activation_creates_all_tables_on_mariadb`, `test_every_migration_runs_once_on_mariadb` (Docker stack, `wp kimaai db migrate`).
- **WPML (fake, commercial plugin):**
    - `SettingsI18nTest`
    - `testRegistersStringsWithWpml`
    - `testTranslatesWithWpml`
    - `testFallsBackToOriginal`
    - `ToolRouterLanguageTest::testUsesWpmlCurrentLanguage`
- **Polylang (free, install in a blueprint):**
    - Unit `testRegistersStringsWithPolylang` and `testAppliesPolylangLanguage`.
    - e2e "greeting is translated per language" and "retrieval only returns chunks in the visitor language".
- **WooCommerce (free, install in a blueprint):**
    - Unit `WooCommerceIntegrationProTest`
    - `testToolsOnlyRegisteredWhenFeatureEnabled`
    - `testCapturedRenderablesHydrateProductHtml`
    - `testInstructionsMentionEnabledFeatures`
    - Unit `ProductRecommendationsTest`, `ProductSimilarTest`, `ProductCardsTest`.
    - e2e "a product question renders product cards", using a fake AI response with a tool call.
- **CF7 and Gravity Forms:** first decide whether the integrations ship. If they do, register them, then:
    - CF7 is free: e2e "a form renderable submits through CF7".
    - Gravity Forms: add a `GFAPI` and `GFForms` stub and `GravityFormsIntegrationTest`
    - `testFormToolOnlyWhenEnabled`
    - `testRenderablesPersistAndHydrate`
- **Multisite smoke** (Playground `enableMultisite` step):
    - "network activation creates tables on every site"
    - "a new sub-site gets tables on first load"
    - "the chatbot answers on a sub-site"
    - "settings are isolated per site"
    - "uninstall cleans each site"
- **Free build:** e2e on `.ci-plugin/kimaai`: "free build shows no premium pages, MCP routes or CLI commands".

### QA-6: untested PHP, in priority order

1. `SecurityTest`
      - `testBlocksExactBannedIp`
      - `testBlocksCidrRange`
      - `testBannedWordsMatchCaseInsensitively`
      - `testIpDetectionIgnoresUntrustedForwardedHeaders` (confirm the intended behaviour first)
2. `UserToolsTest`
      - `testOnlySelectedFunctionsAreExposed`
      - `testSchemaInferredFromDocblockAndSignature`
      - `testInvokeRejectsUnknownFunction`
      - `testExistingFunctionIsNotRedefined`
      - `testCodeIsOnlyEvaluatedFromAdminSettings`
3. `ChatbotFeedbackTest`
      - `testMessageRatingMustBeMinusOneZeroOrOne`
      - `testCsatRatingRange`
      - `testInvalidIdentifiersAreRejected`
      - `testCommentIsSanitised`
      - `testDeleteRoutesRequireCapability`
4. `ChatbotSessionRetentionTest`
      - `testDeletesSessionsOlderThanRetention`
      - `testDeletesInBatches`
      - `testZeroRetentionKeepsEverything`
      - `testScheduleFollowsSetting`
5. `Version2026093001Test`
      - `testErasesStoredIps`
      - `testKeepsPlaygroundMarker`
      - `testRunningTwiceIsHarmless`
6. `HumanHandoffTest`, with a fake `wp_mail`:
      - `testNegativeFeedbackQueuesEscalation`
      - `testUngroundedAnswerQueuesEscalation`
      - `testFlushSendsOneMailPerSession`
      - `testDisabledSendsNothing`
7. Settings import: `SettingsImportTest`
      - `testImportRejectsInvalidJson`
      - `testImportSanitisesEveryField`
      - `testImportKeepsExistingSecretsWhenOmitted`
      - `testImportRequiresManageOptions`
8. `ToolRouterTest`
      - `testKnowledgeSearchQueriesVectorStore`
      - `testFallsBackSafelyWhenStoreUnavailable`
      - `testHybridMergesKeywordLeg`
      - `testLanguageFilterAppliedWhenMultilingual`
9. `KeywordSearchManagerTest`
      - `testAutomaticPrefersElasticPressThenSearchWpThenRelevanssiThenCore`
      - `testExplicitEngineIsUsed`
      - `testSearchRedirectAttemptIsHandled`
      - one test class per provider
10. `KnowledgeGapMinerTest` - `testClustersSimilarQuestions` - `testRanksByNegativeFeedbackThenVolume` - `testExcludesEvalSessions` - `testMinClusterSize`
11. `EvalRunnerTest` - `testRunCaseAgainstFakeChatbot` - `testJudgeUsesConfiguredModel` - `testPersistRunAndHistory`
12. `EvalSchedulerTest` - `testScheduleEnsured` - `testRunBatchRespectsLimit`
13. `FeedbackAnalyticsServiceTest` - `testOverviewCounts` - `testCsatSummary` - `testIncidentWindow` - `testSaveAdminMetaRequiresCapability` - plus the route permission tests
14. `AdminThemeTest` - `testDefaultTheme` - `testUpdatePersistsPerUser` - `testRejectsUnknownValue` - `testRequiresCapability`
15. `AddonManagerTest` - `testRegisteredAddonIsBooted` - `testCommandsRegisteredOnCliInit` - `testNonAddonIsIgnored`
16. `IntegrationManagerTest` - `testPluginStatusDetectsInstalledInactivePlugin` - `testUnknownKeyReturnsEmptyWithoutWarning` (fails today)
17. `ChatbotAdminTest` - `testHistoryRoutesRequireCapability` - `testDeleteSessionRemovesRows`
18. `AiServiceTest` - `testRunSavesChatResponse` - `testSaveImageResponse` - `testTestConnectionReportsProviderError`
19. `UsageTrackerTest` additions - `testPersistsPerDayTotals` - `testReportAggregatesDays`
20. `ChatCompletionsStreamParserTest`, `SseParserTest`, `ChatbotCliSseEmitterTest`.
21. `AdminAssistantSessionRollbackServiceTest`, `BuildsAdminAssistantHistoryExportTest`.
22. Migrations 2026012801, 2026050501 and 2026072701 (remap test); `SchemaRegistryTest::testApplySchemaIsIdempotent`; `DebugInfoTest`.

### QA-7: untested JS and e2e

**Jest:**

- Feedback pages: `Overview.test.jsx` ("renders KPI tiles", "shows empty state"), `MessageFeedback.test.jsx` ("filters by rating", "opens incident sidebar", "saves an admin note"), `Csat.test.jsx`, `KpiTiles`, `ScorePill`.
- MCP admin, `McpApp.test.jsx`:
    - "enables the endpoint"
    - "mints a token and shows it once"
    - "revokes after confirmation"
    - "shows the connection URL"
- Embedding panels:
    - `CollectionsPanel`: "creates and deletes with confirmation"
    - `QueryPanel`: "shows scored results", "shows sanitised error"
    - `SyncModal`, `DeleteModal`, `SyncStatusCell`
- Renderables:
    - `ChoiceCard`
    - `WorkflowCta`
    - `WooProductList`: "only renders HTML from a kimaai renderable payload"
    - `ContactForm7`, `GravityForm`: submission and error states
- Consent, CSAT and feedback:
    - `GDPRConsentBox`: "blocks the composer until accepted", "remembers acceptance"
    - `ChatCsatModal`: "submits rating", "does not reappear"
    - `ChatMessageFeedback`: "thumbs down asks for a comment", "rating locks"
- Transport and controllers:
    - `wpTransport`: "sends nonce and session", "parses SSE stream", "maps 429 to the rate-limit message"
    - `storageAdapter`, `useFeedbackController`, `useConversationController`, `useScrollManager`
- `MarkdownMessage`: "escapes raw HTML", "blocks javascript: links", "renders lists and code blocks".
- Settings import and export, `SettingsImportExport`: "exports without secrets by default", "import rejects invalid JSON", "import asks before overwriting".

**e2e:**

- "a streamed reply renders progressively". Needs a streaming fake: today the e2e fake client's `stream()` returns `[]`.
- "the rate limit shows a friendly message"
- "thumbs feedback is stored", "the CSAT survey is stored"
- "the chatbot mirrors in an RTL locale" and an RTL axe run
- "feedback analytics pages render with seeded rows"
- "chat history admin lists, opens and deletes a session"
- "settings export and import round trip"
- "content awareness passes the current page into the request"

**Storybook:**

- Add the Storybook test-runner (or the Vitest addon) to `check:all` so stories run, with a11y assertions.
- Add stories for the CSAT modal, message feedback, Woo, CF7, Gravity Forms, ChoiceCard and WorkflowCta renderables, an RTL decorator, and dark mode.

## Test infrastructure gaps

1. **`phpunit.xml` lists folders one by one.** All 8 current `tests/unit/*` folders are listed, so nothing is skipped today. But a new top-level folder (for example `tests/unit/Cli`, `tests/unit/Integrations`, `tests/unit/Eval`) would be skipped silently. Use `<directory suffix="Test.php">tests/unit</directory>`, or add a guard test that compares the folders against the config.
2. **The "integration" suite is not WordPress integration.** There is no WP test library (`WP_UnitTestCase`) and no real database. The ChatBot integration tests use the same in-memory stubs as the unit suite. Add a Docker WordPress layer (the Plugin Check compose file already exists) for CLI, migration and vector end-to-end tests.
3. **Missing shared fakes:**
      - a reusable `FakeWpdb` (only the ad hoc `SchemaUninstallFakeWpdb` exists)
      - `FakeWpCli` (buried in `tests/unit/Mcp/McpTestSupport.php`, with no `WP_CLI\Utils\format_items`, `line` or `halt`)
      - fake `wp_mail`
      - an Action Scheduler runner (only `as_*` scheduling stubs exist)
      - an in-memory vector store for PHP unit tests
      - `GFAPI`, `WPCF7` and WooCommerce product fakes
      - Polylang `pll_*` stubs
      - a streaming fake HTTP client for e2e
      - a `kimaai_vector_service_call` stub that returns query matches
4. **CI scope:**
      - No GitHub workflow runs tests; `check:all` is manual on the AI box.
      - Integration runs on PHP 8.4 only.
      - e2e runs on PHP 8.0, WP 6.8 and SQLite only.
      - Real-provider tests skip without `.env.test` (except Ollama, which fails the gate on purpose).
5. **No coverage measurement.** Neither PCOV/Xdebug clover nor Jest `--coverage` is wired up, so this matrix is based on references, not measured lines. Add PCOV to the PHP 8.4 unit run and `jest --coverage` to `check:all`, and publish the reports next to Storybook.
6. **Storybook is build-only.** `@storybook/addon-a11y` checks only run when someone opens Storybook.
7. **Known flakiness** (ROADMAP): parallel Playground workers download the same WordPress zip (pre-warm it in a Playwright global setup), and the Ollama tool-calling e2e on `qwen2.5:3b` is unreliable.
8. **Test placement:**
      - `tests/unit/Ai/HybridFusionTest.php` tests premium `FunctionCall`.
      - `tests/unit/ChatBot/EvalRunnerStaticsTest.php`, `PinnedAnswersSimilarityTest.php` and `WhiteLabelTest.php` test premium code.
      - Move them into premium-named folders when the folder config is simplified.
9. **No e2e on the free build.** All premium e2e depends on `forcePluginPremium`.

## Decisions (owner delegated, my recommendation, 2026-11-13)

1. **Dormant CF7, Gravity Forms and ElasticPress integration classes** stay dormant and get no tests in this track. They are not registered, so tests would cover code that cannot run. Whether they ship again (or go) is a later product question; it is listed under "Later" in the roadmap. ElasticPress keyword search (`KeywordSearch/ElasticPressProvider.php`) is live and is tested in QA-6.
2. **Order of work:** QA-2 (MCP, the largest security surface) first, then QA-6 (untested security and privacy PHP), QA-3 and QA-4 (both need the Docker WordPress with WP-CLI and Qdrant on the AI box), QA-7, QA-5, QA-8. The roadmap's item numbers stay.
3. **Infrastructure first where needed:** `phpunit.xml` scans `tests/unit` recursively so new folders cannot be skipped silently; shared fakes (`FakeWpdb`, `FakeWpCli`, fake `wp_mail`, an in-memory vector store) land with the first item that needs them.
4. **Findings already known** (`IntegrationManager::pluginStatus()` unknown-key warning, the `db run` example naming an unregistered migration, the flaky Ollama tool-calling e2e test, the thinking-model reasoning leak, the Playground download race) are fixed as `fix(…) (QA-n)` commits with a test each, in the item they belong to.
5. **Real paid services** stay out of the default runs: OpenAI and Pinecone only in the gate's smoke tests when `.env.test` is present; everything else runs against Ollama, Qdrant in Docker and fakes.
6. **Groundedness log stores the visitor's question and the answer unredacted** (found in QA-2). Kept as it is: the MCP `read:raw` scope exists to return raw rows (redaction happens on read for every other scope), the same question is already stored raw in the chat history, and the log is pruned after 90 days. Redacting at storage would break `read:raw` without removing the data from the site.
7. **`usage_stats` with `days=N`** returns the last N days that have usage, not the last N calendar days (found in QA-2). Kept; the tool description says "recent days", and changing it would change what MCP clients already read.
8. **Visitor IP behind a reverse proxy** (found in QA-6): the chatbot now reads `REMOTE_ADDR` and trusts `X-Forwarded-For` only from proxies listed in the `kimaai_trusted_proxies` filter (empty by default). Kept as the secure default. Sites behind Cloudflare or a proxy that does not rewrite `REMOTE_ADDR` see one IP for every visitor until they add the filter: the release notes must say so, and a setting for trusted proxies is listed under "Later".
9. **Who may save and run custom PHP tools** (`UserTools`, found in QA-6): saving and running them requires `edit_plugins`, WordPress's own rule for editing code. It is false when `DISALLOW_FILE_EDIT` is set and, on multisite, for anyone but super admins. Implemented in QA-6 part 2.
10. **Custom PHP tools after the update** (QA-6, decision 9 implemented): code is signed when someone with `edit_plugins` saves it and runs only with a valid signature while file editing is allowed. Tools saved before this change stop running until such a user saves the settings once. The release notes must say so.
11. **Schema changes never reach existing tables** (found in QA-6): the models generate `CREATE TABLE IF NOT EXISTS`, so `dbDelta` never compares columns and only hand-written `ALTER` migrations add columns. Fixed in QA-5 together with the MariaDB tests, because the change runs `dbDelta` column comparisons on every install and needs a real database to prove it adds and never drops.
12. **Paid calls in local runs** (found in QA-6): `.env.test` loaded automatically, so a local integration run made a few paid calls on 2026-11-13. It now loads only with `KIMAAI_PAID_TESTS=1`, which the gate sets.
13. **PDF size limit** (found in QA-4): `PdfTextExtractor` reads any PDF fully into memory. PDFs larger than 20 MB are skipped with a logged reason; the `kimaai_pdf_max_bytes` filter changes the limit.
14. **`vectors delete --all` on Qdrant** (QA-4): implemented with a delete-by-filter without conditions, which empties the environment's collection like Pinecone's delete-all empties its namespace.
15. **Uninstall on a multisite network** (QA-5): each site's own "Delete all data on uninstall" setting decides for that site; the main site's setting no longer decides for the whole network.
16. **The chatbot on right-to-left sites** (found in QA-7): the chat layout mirrors (message sides, the composer and its send button, the header controls, the popover text) and the launcher and the window stay where the position setting puts them, so "right" stays on the right. The chatbot CSS uses logical properties for the mirrored parts and physical sides for the position; `build/chatbot-rtl.css` stays unloaded, because rtlcss would flip the position too.
17. **Minimum WordPress raised to 6.2** (found in the QA review): the admin and the chatbot have used `createRoot` from `@wordpress/element` since before 1.5.13, and newer code uses `useId`; both exist only from WordPress 6.2 (React 18). On 6.0 and 6.1 the interface already failed. "Requires at least" is now 6.2, so WordPress.org no longer offers the update to those sites, and the opt-in minimum run (`--wp-min`) uses 6.2. The release notes must say so.
