weitzman / drupal-test-traits
Traits for testing Drupal sites that have user content (versus unpopulated sites).
Requires
- php: >=8.1
Requires (Dev)
- drupal/mailsystem: ^4
- drush/drush: ^12.5 || ^13
- phpspec/prophecy-phpunit: ^2
- webflo/drupal-finder: ^1.3.1
Conflicts
- drupal/core: <=10.2
- 2.x-dev
- 2.5.0
- 2.4.2
- 2.4.1
- 2.4.0
- 2.3.1
- 2.3.0
- 2.2.0
- 2.1.0
- 2.0.2
- 2.0.1
- 2.0.0
- 2.0.0-rc2
- 2.0.0-rc1
- 1.x-dev
- 1.6.0
- 1.5.0
- 1.4.0
- 1.3.1
- 1.3.0
- 1.2.1
- 1.2.0
- 1.1.0
- 1.0.0
- 1.0.0-rc.1
- 1.0.0-beta.2
- 1.0.0-beta.1
- 1.0.0-alpha.2
- 1.0.0-alpha.1
- dev-addLoginTrait
- dev-dtt-3449983-3449983-config-trait
- dev-teardown
- dev-fail-on-php-messages
- dev-auto
- dev-ci-chrome
- dev-chrome-update
- dev-terminator
- dev-logger-drupal-to-headers
- dev-gitlabci
- dev-php73
- dev-bump
- dev-version-pin
- dev-38-custom-profile
- dev-patch-1
- dev-35-add-assert-count
- dev-phenaproxima/drupal-test-traits-master
- dev-s2d-headers
- dev-debug
This package is auto-updated.
Last update: 2024-10-31 15:47:55 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.
- Blog: Introducing Drupal Test Traits
- Blog: Introducing Drupal Test Traits: Drupal extension for testing existing sites
- Video: Drupalcon presentation - Introducing Drupal Test Traits.
- Video: The road to zero friction testing with Drupal Test Traits
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 intests/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
- Create or edit
phpunit.xml
to include new testsuites forexisting-site
andexisting-site-javascript
(example phpunit.xml). - Specify the URL to your existing site with
DTT_BASE_URL=http://example.com
. For ExistingSiteSelenium2DriverTest tests, also specifyDTT_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 ...
- Add them to your
- 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 yourphpunit.xml
(example phpunit.xml). Depending on your setup, you may wish to runphpunit
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 thephpunit
call. - Drupal 11+: Add a PHPUnit extension
- Drupal 10-: Add
- To disable deprecation notices, set the environment variable
SYMFONY_DEPRECATIONS_HELPER=disabled
. Alternatively, you can specify these in yourphpunit.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 specifyDTT_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 missingwaitForElementVisible
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
toFALSE
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 inphpunit.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.
- All merge requests are automatically tested via GitLab CI.
- Discuss DTT at the #testing channel on Drupal Slack.
- DDEV
- See
.ddev
directory for a handy development environment. DDEV Docs. We also include the a ddev poser command which temporarily adds Drupal to composer.json and does acomposer install
. - You may watch browser tests (e.g. ExistingSiteSelenium2DriverTestBase) at https://dtt.ddev.site:7900.
- See
Colophon
- Author: Moshe Weitzman.
- Maintainers: Moshe Weitzman, Jibran Ijaz (jibran), Adam Bramley (acbramley), Michael Strelan (mstrelan), and the community.
- License: MIT license