weitzman/drupal-test-traits

Traits for testing Drupal sites that have user content (versus unpopulated sites).

Maintainers

Details

git.drupalcode.org/project/dtt/

Source

Installs: 3 900 563

Dependents: 21

Suggesters: 0

Security: 0

2.5.0 2024-10-30 23:28 UTC

Requires

  • php: >=8.1

Requires (Dev)

Conflicts

MIT 664201b00140f9b935fcb9f3eef012c6638ec0c5

  • Moshe Weitzman <weitzman.woop@tejasa.com>

This package is auto-updated.

Last update: 2025-04-16 04:41:56 UTC

README

Traits for testing Drupal sites that have user content (versus unpopulated sites).

Behat is great for facilitating conversations between business managers and developers. Those are useful conversations, but many organizations simply can't or won't converse via Gherkin. When you are on the hook for product quality and not conversations, this is a testing approach for you.

Installation

  • Install via Composer: composer require weitzman/drupal-test-traits --dev

Authoring tests

Pick a test type:

  • ExistingSite. See ExampleTest.php. Start here. These tests can be small unit tests up to larger functional tests (via BrowserKit). Tests of this type should be placed in tests/src/ExistingSite.
  • ExistingSiteSelenium2DriverTest. See ExampleSelenium2DriverTest.php. These tests make use of any browser which can run in [WebDriver] mode (Chrome, Firefox or Edge) via Selenium or browser specific drivers like chromedriver. They are suited to testing Ajax and similar client side interactions. This browser setup can also be used to run Drupal 8 core JS testing using nightwatch. These tests run slower than ExistingSite. To use this test type you need to composer require 'behat/mink-selenium2-driver' --dev. Tests of this type should be placed in tests/src/ExistingSiteJavascript.

Extend the base class that corresponds to your pick above: ExistingSiteBase.php, ExistingSiteSelenium2DriverTestBase.php. You may extend it directly from your test class or create a base class for your project that extends one of these.

Scaffold your tests quickly via our built-in Drush generators: drush generate test:existing or drush generate test:existing-js.

Running tests

  1. Create or edit phpunit.xml to include new testsuites for existing-site and existing-site-javascript (example phpunit.xml).
  2. Specify the URL to your existing site with DTT_BASE_URL=http://example.com. For ExistingSiteSelenium2DriverTest tests, also specify DTT_MINK_DRIVER_ARGS=["firefox", null, "http://selenium:4444/wd/hub"]. You can also change timeouts like this: DTT_API_OPTIONS={"socketTimeout": 360, "domWaitTimeout": 3600000} (note the JSON string). You can specify these environment variables one of three ways:
    • Add them to your phpunit.xml (example phpunit.xml).
    • Add them to your .env (supported by drupal-project and Docker).
    • Specify them at runtime: DTT_BASE_URL=http://127.0.0.1:8888; DTT_API_URL=http://localhost:9222 vendor/bin/phpunit ...
  3. Run phpunit with the --bootstrap option: vendor/bin/phpunit --bootstrap=vendor/weitzman/drupal-test-traits/src/bootstrap-fast.php .... This bootstrap can also be referenced in your phpunit.xml (example phpunit.xml). Depending on your setup, you may wish to run phpunit as the web server user: su -s /bin/bash www-data -c "vendor/bin/phpunit ...". If you get 'Class not found' errors, please see comments at top of bootstrap-fast.php

You should limit these test runs to your custom functionality only; testing Core and Contrib modules is already the purview of DrupalCI. To do so, tell phpunit to only look for tests in a certain path, or use @group annotations to limit the scope. The following examples depend on a properly configured phpunit.xml (example phpunit.xml):

vendor/bin/phpunit web/modules/custom
vendor/bin/phpunit --group CustomTestGroup

Debugging tests

  • HTML requests can be logged. To do so, set the enviroment variable BROWSERTEST_OUTPUT_DIRECTORY=/tmp and either of
    • Drupal 10-: Add --printer '\\Drupal\\Tests\\Listeners\\HtmlOutputPrinter' to the phpunit call.
    • Drupal 11+: Add a PHPUnit extension
  • To disable deprecation notices, set the environment variable SYMFONY_DEPRECATIONS_HELPER=disabled. Alternatively, you can specify these in your phpunit.xml (example phpunit.xml).
  • To write the current HTML of the page to a file, use $this->capturePageContent(). If using HtmlOutputPrinter this will be saved to the browser_output directory. Alternatively you can specify DTT_HTML_OUTPUT_DIRECTORY=/path/to/output_directory which is required when using a different printer, such as Teamcity, which is enforced by PHPStorm.
  • To take a screenshot of the current page under ExistingSiteSelenium2DriverTest, use \weitzman\DrupalTestTraits\ScreenShotTrait::captureScreenshot. Be careful when using this to debug tests that are "randomly" failing. Most likely, these tests are failing due to missing waitForElementVisible checks, as the act of taking a screenshot gives the browser additional time to finish rendering the page.
  • By default, tests whose execution throw PHP warnings/errors to the Drupal watchdog will fail (requires dblog module). If you want to disable this, set $failOnPhpWatchdogMessages to FALSE in your test or custom base class.

Available traits

  • DrupalTrait Bootstraps Drupal so that its APIs are available. Also offers an entity cleanup API so databases are kept relatively free of testing content.

  • BrowserKitTrait Makes BrowserKitTrait available for browser control, and offers a few helper methods.

  • Selenium2DriverTrait Makes Selenium2Driver available for browser control with Selenium. Suitable for functional JS testing.

  • NodeCreationTrait Create nodes that are deleted at the end of the test method.

  • TaxonomyCreationTrait Create terms and vocabularies that are deleted at the end of the test method.

  • UserCreationTrait Create users and roles that are deleted at the end of the test method.

  • ConfigTrait Set Drupal config that persists just for the duration of a test. An example usage may be found in \weitzman\DrupalTestTraits\Mail\MailCollectionTrait::startMailCollection.

  • EntityCrawlerTrait Enables rendering of entities (without http) and then offers output assertions powered by Symfony Crawler. See example test.

  • MailCollectionTrait Enables the collection of emails during tests. Assertions can be made against contents of these as core's AssertMailTrait is included.

  • ScreenShotTrait Allows for the capture of screenshots when the Selenium2 driver. The destination directory can be set with DTT_SCREENSHOT_REPORT_DIRECTORY, which can also be set in phpunit.xml (example phpunit.xml). Defaults to /sites/simpletest/browser_output.

  • AuthTrait Override drupalLogout() so that it is compatible with sites bypass the Drupal login form (e.g. OpenID Connect and similar). Replaces https://gitlab.com/weitzman/logintrait.

Contributed Packages

Submit a merge request to get your trait added to this list.

Use type="drupal-dtt" in your package's composer.json in order to appear in this list.

  • LoginTrait. Provides login/logout via user reset URL instead of forms. Useful when TFA/SAML are enabled. This package is not needed since Drupal 10.3+ avoids forms by default.
  • QueueRunnerTrait. Provides methods to clear and run queues during tests.
  • Drupal Test Utils. A trait to add Dynamic Page Cache cacheability testing.

Contributing

Contributions to this project are welcome! Please file issues and merge requests.

Colophon