Testing

The AI Context module includes unit, kernel, and functional tests.

Test structure

tests/src/
├── Unit/                  # Fast, isolated tests (no Drupal bootstrap)
├── Kernel/                # Integration tests (partial Drupal bootstrap)
├── Functional/            # Full browser tests (complete Drupal installation)
├── FunctionalJavascript/  # JavaScript interaction tests
└── Traits/                # Shared test helpers

Setup

Create the browser output directory for functional test HTML snapshots:

ddev exec mkdir -p /var/www/html/web/sites/simpletest/browser_output

Create a local phpunit.xml with DDEV database and browser output settings. Run from the Drupal project root (not from inside the module directory).

Copy and patch the template in one step:

ddev exec bash -c "sed \
  -e 's|name=\"SIMPLETEST_BASE_URL\" value=\"\"|name=\"SIMPLETEST_BASE_URL\" value=\"http://localhost\"|' \
  -e 's|name=\"SIMPLETEST_DB\" value=\"\"|name=\"SIMPLETEST_DB\" value=\"mysql://db:db@db:3306/db\"|' \
  -e 's|name=\"outputDirectory\" value=\"sites/simpletest/browser_output\"|name=\"outputDirectory\" value=\"web/sites/simpletest/browser_output\"|' \
  web/core/phpunit.xml.dist > web/core/phpunit.xml"

Split across lines for readability; it must run as a single command.

Or, apply the same changes manually:

Copy the PHPUnit config template:

ddev exec cp web/core/phpunit.xml.dist web/core/phpunit.xml

Open web/core/phpunit.xml and, in the <php> section, set:

<env name="SIMPLETEST_BASE_URL" value="http://localhost"/>
<env name="SIMPLETEST_DB" value="mysql://db:db@db:3306/db"/>

In the same file, find the HtmlOutputLogger bootstrap extension and set the browser output directory (must match the path created above):

<parameter name="outputDirectory" value="web/sites/simpletest/browser_output"/>

Running tests with DDEV

Run all tests

ddev exec phpunit --configuration=web/core \
  web/modules/contrib/ai_context/tests

Run by test type

# Unit tests (fastest)
ddev exec phpunit --configuration=web/core \
  web/modules/contrib/ai_context/tests/src/Unit

# Kernel tests
ddev exec phpunit --configuration=web/core \
  web/modules/contrib/ai_context/tests/src/Kernel

# Functional tests (slowest)
ddev exec phpunit --configuration=web/core \
  web/modules/contrib/ai_context/tests/src/Functional

Run a single test file

ddev exec phpunit --configuration=web/core \
  web/modules/contrib/ai_context/tests/src/Kernel/AiContextScopeManagerTest.php

Run a specific test method

ddev exec phpunit --configuration=web/core \
  --filter=testPathMatchesPattern \
  web/modules/contrib/ai_context/tests/src/Unit/AiContextScopeSiteSectionTest.php

Verbose output

# Show test names
ddev exec phpunit --configuration=web/core \
  web/modules/contrib/ai_context/tests/src/Unit --testdox

# Show detailed failure info
ddev exec phpunit --configuration=web/core \
  web/modules/contrib/ai_context/tests/src/Kernel -v

Running without DDEV

# Using PHPUnit directly
vendor/bin/phpunit web/modules/contrib/ai_context/tests

# Using Drupal's test runner
php core/scripts/run-tests.sh --verbose --color --module ai_context

Conventions

Use intent-first method names
Add #[RunTestsInSeparateProcesses] for Kernel, Functional, and FunctionalJavascript test classes
Use Arrange/Act/Assert comment blocks in non-trivial tests
Call assertConfigObjectSchemaIsValid() after settings-form submits
Reuse shared helpers from tests/src/Traits/

Test modules

The tests/modules/ directory holds helper modules used by the automated test suite and for local development while working on ai_context code.

When you are building or debugging a feature, these modules let you load fixtures, example context, or extra scope plugins on a local site before you write or extend PHPUnit tests.

These modules are not discovered during normal site bootstrap. PHPUnit kernel and functional tests enable them automatically via each test class's $modules property.

To enable a test module manually on a local site, turn on test extension discovery first. Add this to settings.local.php on a throwaway local site only — not production:

$settings['extension_discovery_scan_tests'] = TRUE;

Then enable the module with Drush:

ddev exec drush en MODULE_MACHINE_NAME -y
ddev exec drush cr

Disable when finished:

ddev exec drush pmu MODULE_MACHINE_NAME -y
ddev exec drush cr

Index

Machine name	Audience	Purpose
`ai_context_test`	PHPUnit	Fixed AI provider fixtures for automated tests.
`ai_context_test_support`	PHPUnit	Form alters used by functional and JavaScript tests.
`ai_context_test_scope_values`	PHPUnit	Implements `hook_ai_context_scope_values_alter()` for scope-value alter tests.
`ai_context_test_scope`	Manual / dev	Adds a `test_scope` scope plugin (`alpha`, `beta`) for verifying scope settings UI and behavior.
`ai_context_test_items`	Manual / dev	Imports 13 example context items from the DrupalCon Chicago 2026 Driesnote demo via `default_content`.

PHPUnit-only modules

ai_context_test, ai_context_test_support, and ai_context_test_scope_values are enabled by individual test classes. You do not need to install them manually to run the test suite.

ai_context_test_scope_values exposes a state flag (ai_context_test_scope_values.enabled) that kernel tests toggle when exercising the scope values alter hook.

Manual verification modules

Use these on a local site while developing or before adding automated tests.

ai_context_test_scope — adds a test_scope scope plugin (alpha, beta) for verifying scope settings UI and behavior. See tests/modules/ai_context_test_scope/README.md for plugin details, routes, and enable/disable commands.

ai_context_test_items — imports 13 example context items from the DrupalCon Chicago 2026 Driesnote demo (FinDrop) via default_content. Useful when you need realistic context data while working on selection, rendering, or UI without building fixtures by hand. See tests/modules/ai_context_test_items/README.md for the item list, requirements, setup, uninstall notes, and UUID conflict guidance.

Test coverage by component

Component	Test type	Description
`AiContextScopeManager`	Kernel	Plugin discovery, sorting, value aggregation
`AiContextScopeResolver`	Kernel	Score calculation, filtering, sorting
`AiContextScopePluginTest`	Kernel	Individual scope plugin behavior
`AiContextScopeEntityTest`	Kernel	Scope field get/set, persistence, revisions
`AiContextSelectorTranslationTest`	Kernel	Translation functionality
`AiContextRendererTest`	Kernel	Context rendering with max tokens
`AiContextScopeSiteSectionTest`	Unit	Path pattern matching algorithm
`AiContextScopeScoreCalculationTest`	Unit	Scope scoring algorithm
`MarkdownRendererTest`	Unit	Markdown to HTML conversion
`AiContextScopeContextItemFormTest`	Functional	Scope selection UI
`AiContextScopeAgentFormTest`	Functional	Agent subscription UI
`AiContextItemCrudTest`	Functional	CRUD operations
`AiContextItemFormTest`	Functional	Entity form behavior

Test coverage

See the tests folder to see which tests are covered by the test suite.