drupal-functionaljs-test

Drupal FunctionalJavascript Test

What It Is

Extends BrowserTestBase but uses a real Chrome browser via WebDriver. JavaScript executes completely. AJAX works. CSS animations are disabled.

Speed: 10-170 seconds per class. Use ONLY when there is no alternative.

Critical Difference from BrowserTestBase

statusCodeEquals() does NOT work in WebDriverTestBase. The Selenium2 driver does not have access to HTTP status codes. Verify access with pageTextContains() or elementExists().

Base Template

<?php
declare(strict_types=1);

namespace Drupal\Tests\MODULE\FunctionalJavascript;

use Drupal\FunctionalJavascriptTests\WebDriverTestBase;
use Drupal\user\UserInterface;

/**
 * Tests DESCRIPTION.
 *
 * @group MODULE
 */
class NameTest extends WebDriverTestBase {

  protected $defaultTheme = 'stark';
  protected static $modules = ['node', 'MODULE'];

  protected UserInterface $adminUser;

  protected function setUp(): void {
    parent::setUp();
    $this->adminUser = $this->drupalCreateUser(['access content', 'administer MODULE']);
  }

  public function testAjaxInteraction(): void {
    $this->drupalLogin($this->adminUser);
    $this->drupalGet('route');

    $page = $this->getSession()->getPage();
    $assert = $this->assertSession();

    $page->selectFieldOption('field', 'value');
    $assert->assertWaitOnAjaxRequest();

    $element = $assert->waitForElementVisible('css', '.result');
    $this->assertNotEmpty($element);
  }

}

GOLDEN RULE: Never sleep(), Always Waits

The #1 cause of flaky tests. NEVER sleep(). ALWAYS use waits:

$assert = $this->assertSession();

// Wait for AJAX (most used)
$assert->assertWaitOnAjaxRequest();

// Wait for element in DOM
$element = $assert->waitForElement('css', '.my-element');
$this->assertNotEmpty($element);

// Wait for VISIBLE element
$element = $assert->waitForElementVisible('css', '.dropdown');

// Wait for element to disappear
$assert->waitForElementRemoved('css', '.spinner');

// Specific waits
$assert->waitForButton('Submit');
$assert->waitForLink('Next');
$assert->waitForField('field_name');
$assert->waitForId('my-id');
$assert->waitForText('Done');

// Autocomplete
$assert->waitOnAutocomplete();

// Custom JS condition
$this->getSession()->wait(5000, 'jQuery("#el").is(":visible")');