weitzman / drupal-test-traits
Traits for testing Drupal sites that have user content (versus unpopulated sites).
Requires
- php: >=8.1
- 2.x-dev
- 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-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: 2023-11-14 04:47:39 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
- All HTML requests can be logged. To do so, add
BROWSERTEST_OUTPUT_DIRECTORY=/tmp
and--printer '\\Drupal\\Tests\\Listeners\\HtmlOutputPrinter'
to thephpunit
call. To disable deprecation notices, includeSYMFONY_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.
MailCollectionTrait
Enables the collection of emails during tests. Assertions can be made against contents of these as core'sAssertMailTrait
is included.ScreenShotTrait
Allows for the capture of screenshots when the Selenium2 driver. The destination directory can be set withDTT_SCREENSHOT_REPORT_DIRECTORY
, which can also be set inphpunit.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.
- QueueRunnerTrait. Provides methods to clear and run queues during tests.
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 use the composer plugin for local dev and CI. See Local Dev Docs.
- 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), and the community.
- License: MIT license