weitzman/drupal-test-traits

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


README

Build status project-stage-badge license-badge

Introduction

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.

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 Goutte). 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 web driver mode (Chrome, FireFox or Edge) via Selenium, so 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'. Tests of this type should be placed in tests/src/ExistingSiteJavascript.
  • ExistingSiteWebDriverTest. See ExampleWebDriverTest.php. These tests make use of a headless Chrome browser, so are suited to testing Ajax and similar client side interactions. These tests run slower than ExistingSite. To use this test type you need to composer require 'dmore/chrome-mink-driver'. 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, or ExistingSiteWebDriverTestBase.php. You may extend it directly from your test class or create a base class for your project that extends one of these. To choose between Selenium2 or WebDriver for JS testing, read testing Drupal with WebDriver browser mode vs Headless browser mode.

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:9222/wd/hub"]. For ExistingSiteWebDriverTest tests, also specify DTT_API_URL=http://localhost:9222. 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

  • All HTML requests can be logged. To do so, add BROWSERTEST_OUTPUT_DIRECTORY=/tmp and --printer '\\Drupal\\Tests\\Listeners\\HtmlOutputPrinter' to the phpunit call. To disable deprecation notices, include SYMFONY_DEPRECATIONS_HELPER=disabled. Alternatively, you can specify these in your phpunit.xml (example phpunit.xml).
  • To check the current HTML of the page, use file_put_contents('public://' . drupal_basename($this->getSession()->getCurrentUrl()) . '.html', $this->getCurrentPageContent());.
  • To take a screenshot of the current page under ExistingSiteSelenium2DriverTest or ExistingSiteWebDriverTest, use file_put_contents('public://screenshot.jpg', $this->getSession()->getScreenshot());.

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.

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

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

  • WebDriverTrait
    Makes ChromeDriver available for browser control without the overhead of 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.

  • 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 using Webdriver or Selenium2 drivers. 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.

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.

Contributing

Contributions to this project are welcome! Please file issues and pull requests. All pull requests are automatically tested via GitLab CI.

See docker-compose.yml for a handy development environment.

See the #testing channel on Drupal Slack for discussion about this project.

Colophon