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/wont 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:

  1. ExistingSiteBrowser. See ExampleTest.php. Start here. These tests can be small unit tests up to larger Functional tests (via Goutte).
  2. ExistingSiteSelenium2. 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'
  3. ExistingSiteWebDriver. 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'

Extend the base class that corresponds to your pick above: ExistingSiteBase.php, ExistingSiteWebDriverTestBase.php, or ExistingSiteSelenium2DriverTestBase.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 ExistingSiteWebDriverTestBase.php, or ExistingSiteSelenium2DriverTestBase.php for JS (Ajax and similar client side interactions) testing read testing Drupal with WebDriver browser mode vs Headless browser mode.

Running tests

  • You must specify the URL to your site as an environment variable: DTT_BASE_URL=http://example.com. For ExistingSiteJavascript also specify DTT_MINK_DRIVER_ARGS=["firefox", null, "http://selenium:9222/wd/hub"] or DTT_API_URL=http://localhost:9222. Here are three ways to do that:
    • Specify in a phpunit.xml. See example.
    • Enter that line into a .env file. These files are supported by drupal-project and Docker.
    • Specify environment variables at runtime: DTT_BASE_URL=http://127.0.0.1:8888;DTT_API_URL=http://localhost:9222 vendor/bin/phpunit ...
  • Run phpunit with a --bootstrap option like so: vendor/bin/phpunit --bootstrap=vendor/weitzman/drupal-test-traits/src/bootstrap.php web/modules/custom
  • Optional. 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 ..."

Debugging tests

  • For ExistingSite, all HTML requests can be logged:
    • Define the environment variable BROWSERTEST_OUTPUT_DIRECTORY. See .env.example or docs/phpunit.xml for guidance.
    • Add --printer '\\Drupal\\Tests\\Listeners\\HtmlOutputPrinter' to the phpunit call. Alternatively specify same in a phpunit.xml. Add SYMFONY_DEPRECATIONS_HELPER=disabled to silence deprecation notices.
  • For ExistingSiteSelenium2 or ExistingSiteWebDriver , use file_put_contents('public://screenshot.jpg', $this->getSession()->getScreenshot()); to take screenshot of the current page.
  • To check the current HTML of the page use file_put_contents('public://' . drupal_basename($session->getCurrentUrl()) . '.html', $this->getCurrentPageContent());

Available traits

  • DrupalTrait
    Bootstraps Drupal so that its API's 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
    Make Selenium2Driver available for browser control with Selenium. Suitable for functional javascript testing.

  • WebDriverTrait
    Make ChromeDriver available for browser control without the overhead of Selenium. Suitable for functional javascript testing.

  • NodeCreationTrait
    Create nodes that are automatically deleted at end of 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.

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 this list.

  • LoginTrait. Provides login/logout via user reset URL instead of forms. Useful when TFA/SAML are enabled.
  • More packages

Contributing

Contributions to the 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