drupal-unit-test

Environment

All commands via ssh web. Use $DDEV_DOCROOT for paths. Detect test gaps: ssh web drush audit:run phpunit --filter="module:MODULE" --format=json

Drupal 10+11 Compatibility (CRITICAL)

Use PHPDoc annotations only — NEVER PHP 8 attributes. Drupal 10 = PHPUnit 9.x (no attribute support).

Use THIS	NOT this
@coversDefaultClass \My\Class	#[CoversClass(MyClass::class)]
@covers ::methodName	#[Covers('methodName')]
@group mymodule	#[Group('mymodule')]
@dataProvider providerName	#[DataProvider('providerName')]

Workflow

1. Read source class in src/
2. Check existing tests in tests/src/Unit/
3. Generate test class following templates below
4. Run test (Form ROOT — requires project phpunit.xml; if missing, use Form CORE from the drupal-testing skill): ssh web ./vendor/bin/phpunit $DDEV_DOCROOT/modules/custom/MODULE/tests/src/Unit/Service/MyServiceTest.php
5. Run PHPCS — always try Audit module first:

   # Preferred: Audit module (check if installed first)
   ssh web drush audit:run phpcs --filter="module:MODULE" --format=json
   # Fallback only if Audit module not installed:
   ssh web ./vendor/bin/phpcs --standard=Drupal,DrupalPractice $DDEV_DOCROOT/modules/custom/MODULE/tests/src/Unit/
   

File Structure & Namespace

$DDEV_DOCROOT/modules/custom/MODULE/tests/src/Unit/
├── Service/MyServiceTest.php        # Drupal\Tests\MODULE\Unit\Service
├── Plugin/Block/MyBlockTest.php     # Drupal\Tests\MODULE\Unit\Plugin\Block
├── Form/MyFormTest.php              # Drupal\Tests\MODULE\Unit\Form
└── Controller/MyControllerTest.php  # Drupal\Tests\MODULE\Unit\Controller

Template: Service Test (Complete Example)

<?php

declare(strict_types=1);

namespace Drupal\Tests\mymodule\Unit\Service;

use Drupal\Core\Config\ConfigFactoryInterface;
use Drupal\Core\Config\ImmutableConfig;
use Drupal\mymodule\Service\MyService;
use Drupal\Tests\UnitTestCase;

/**
 * Tests the MyService class.
 *
 * @coversDefaultClass \Drupal\mymodule\Service\MyService
 * @group mymodule
 */
class MyServiceTest extends UnitTestCase {

  protected MyService $service;
  protected ConfigFactoryInterface $configFactory;

  /**
   * {@inheritdoc}
   */
  protected function setUp(): void {
    parent::setUp();
    $this->configFactory = $this->createMock(ConfigFactoryInterface::class);
    $this->service = new MyService($this->configFactory);
  }

  /**
   * @covers ::process
   */
  public function testProcessValidInput(): void {
    $config = $this->createMock(ImmutableConfig::class);
    $config->method('get')->willReturn('value');
    $this->configFactory->method('get')->willReturn($config);
    $result = $this->service->process('test');
    $this->assertIsArray($result);
    $this->assertNotEmpty($result);
  }

  /**
   * @covers ::process
   * @dataProvider processDataProvider
   */
  public function testProcessScenarios(string $input, bool $expectEmpty): void {
    $config = $this->createMock(ImmutableConfig::class);
    $config->method('get')->willReturn('default');
    $this->configFactory->method('get')->willReturn($config);
    $result = $this->service->process($input);
    $this->assertEquals($expectEmpty, empty($result));
  }

  /**
   * @return array
   *   Test scenarios.
   */
  public static function processDataProvider(): array {
    return [
      'valid input' => ['valid', FALSE],
      'another case' => ['other', FALSE],
    ];
  }

}