Drupal development & testing environment

Docker based Drupal environment for local development and testing.

Supported testing frameworks: PHPUnit, Behat

It is recommended to use in combination with the pronovix/drupal-qa Composer plugin.

Notice: Always pull a specific tag or commit from this repository! There could be breaking changes!

Requirements

• Docker >= 18.03
• Docker Compose

Usage

$ git clone https://github.com/Pronovix/docker-drupal-dev.git drupal-dev
$ mkdir build;
$ ln -s drupal-dev/docker-compose.yml
$ ln -s drupal-dev/Dockerfile
$ printf "COMPOSE_PROJECT_NAME=[YOUR_PROJECT_NAME]\n#You can find examples for available customization in the drupal-dev/examples/.env file.\n" > .env && source .env
$ docker-compose up -d --build

Replace [YOUR_PROJECT_NAME] with a string that only contains lowercase letters and dashes. It must not contain spaces or any special characters. Ex.: my_awesome_project

Installing Drupal 8 inside the running PHP container

$ docker-compose exec php composer create-project drupal-composer/drupal-project:8.x-dev ../build -n

Now continue with an optional, but highly recommended step. Symlink settings*.php files and development.services.yml.dist from the drupal folder to build/web/sites. Symlink settings*.php files and development.services.yml.dist from the drupal folder to build/web/sites. Symlinks must be relative to the destination path in a way that they could be accessed inside the php container as well.

$ ln -s ../../../../drupal-dev/drupal/settings.php build/web/sites/default/settings.php
$ ln -s ../../../../drupal-dev/drupal/settings.shared.php build/web/sites/default/settings.shared.php
$ ln -s ../../../../drupal-dev/drupal/settings.testing.php build/web/sites/default/settings.testing.php
$ ln -s ../../../drupal-dev/drupal/development.services.yml.dist build/web/sites/development.services.yml.dist

(If settings.php file already exists then delete it or rename it to settings.local.php.)

If you successfully symlinked these files then your environment is ready to be used. You can install the site on the UI or with Drush.

You can install the site with the minimal install profile like this with Drush: docker-compose exec php drush si minimal -y. If the build/config folder does not exist you have to add --db-url=$SIMPLETEST_DB to the end of the command because Drush is not going to read the configuration from the symlinked settings.php. (This is probably a bug.)

Accessing to the dev environment inside a browser

Check the current port of the running webserver container with docker-compose ps webserver:

              Name                            Command               State           Ports        
-------------------------------------------------------------------------------------------------
my_module_webserver   /docker-entrypoint.sh sudo ...   Up      0.0.0.0:32794->80/tcp

Note: The exposed port changes every time when the webserver container restarts.

If you generate a login URL with Drush then replace the webserver in the login url with localhost:[PORT], like: http:/localhost:32794/user/reset/1/1561455114/sKYjEf26WZ6bzuh-KrNY425_3KCppiCHI8SxKZ158Lw/login.

Running tests

PHPUnit

In this configuration everything is preconfigured for running any Drupal 8's PHPUnit tests, included but not limited to PHPUnit Javascript tests. If you have PHPUnit installed as a Composer dependency in your project, then running PHPUnit tests is simple, here is a few examples:

$ docker-compose run --rm php ./vendor/bin/phpunit -c web/core -v --debug --printer '\Drupal\Tests\Listeners\HtmlOutputPrinter' web/core/modules/node # Run all tests of the node module.
$ docker-compose run --rm php ./vendor/bin/phpunit -c web/core -v --debug --printer 'Drupal\Tests\Listeners\HtmlOutputPrinter' web/core/modules/node/tests/src/Functional/NodeCreationTest.php # Run one specific test from the node module.
$ docker-compose run --rm php ./vendor/bin/phpunit -c web/core -v --debug --printer '\Drupal\Tests\Listeners\HtmlOutputPrinter' --testsuite kernel # Run all kernel tests.

You can find more information about available PHPUnit CLI parameters and configuration options in the official PHPUnit documentation.

Behat

docker-compose.yml contains some sane default Behat settings that make it possible to run Behat tests inside the PHP container smoothly. Check BEHAT_PARAMS environment variable in the definition of the php container.

Usage

1. Copy the behat.yml.dist file to the build folder with cp drupal-dev/examples/behat/behat.yml.dist build/behat.yml.dist. You can also add your behat.yml with overrides to this directory if you have one.
2. For demonstration purposes copy the drupal-dev/examples/behat/login.feature to build/behat with mkdir build/behat && cp drupal-dev/examples/behat/login.feature build/behat.
3. Make sure the site is in an installed state. You can ensure that by importing a database or installing a site manually of with Config Installer.
4. Run all Behat tests from the build/behat folder: docker-compose exec php php vendor/bin/behat.

You can find more information about available Behat CLI parameters and configuration options in the official Behat and Drupal Behat extension documentation.

Notes

• It is recommended to install the pronovix/drupal-qa package with Composer because it ships a bunch of useful Behat extensions that could make your life easier when you are testing a site.