Drupal Test Writing
This is a test D9 site which can be used for practicing test writing and running. This is to be used in tandem with the Drupal Testing Crash Course training at DrupalCamp Colorado.
Download the presentation slides:
Dependencies
- Docker 18.06+ - Instructions for installing Docker on your local system
- Latest version of DDEV-Local - Instructions for installing DDEV on your local system.
Note: If you want to improve performance of test running on MacOS, follow the instructions for using the new experimental mutagen functionality in Docker Desktop with DDEV-Local.
Getting Started
-
Clone this repo locally. (Note: You may want to consider forking this repo instead of directly cloning if you wish to open pull requests)
git clone [email protected]:WidgetsBurritos/drupal-test-writing.git
If you run into a permission denied error with the command above, try using https instead:
git clone https://github.com/WidgetsBurritos/drupal-test-writing.git
Then you will need to change into that directory:
cd drupal-test-writing
-
Start DDEV-Local
ddev start
The very first time
ddev start
is run, it will do a few different things, which can be found in scripts/post-start.sh:- Install a very simple D9 website, based on the snapshot located at
snapshot/dump.sql.gz
. Any subsequentddev start
runs will keep your database intact, unless you manually remove it. - Install all PHP dependencies via composer.
- Inject a
.env
andphpunit.xml
file in yourweb/core
directory, based on the templates intemplates/core.env
andtemplates/core.phpunit.xml
respectively. In a real project, you would want to ensure those files are handled properly and securely. Seeweb/core/.env.example
andweb/core/phpunit.xml.dist
for more information about those files. - Install all Node.js dependencies inside the
web/core
directory. This is needed for nightwatch tests to run. - Clear the Drupal cache.
- Install a very simple D9 website, based on the snapshot located at
-
Open the site in your browser:
ddev launch
-
You can then use the following sample credentials to test out various roles:
admin
/admin
- Has all the privilegesbobby
/bobby
- Has theMy Super Secret Privilege
permissioncarol
/carol
- Has theYet Another Privilege
permissiondavid
/david
- Has no roles or permissions set
-
Verify everything is running properly:
ddev composer check:everything
If everything is working correctly, you should see a response like this:
Attempting to load Drupal:
✓ Success
Attempting to run Drupal tests:
✓ Success
Attempting to run behat tests:
✓ Success
Attempting to run nightwatch.js tests:
- Connecting to chromedriver on port 9515...
ℹ Connected to chromedriver on port 9515 (226ms).
✓ Success
What We're Testing
Most of what we will be working with is located in a custom module called my_testing_module.
This module is intentionally broken for the sake of demonstrating test-driven development.
This module should do the following when you navigate to /my-message
:
- Shows a message for any authenticated users that says: "You are logged in"
- It's actually showing "You might be logged in" instead.
- Shows a message for users with the my super secret privilege permission that says: "You are super special."
- It's actually showing "You aren't all that special." instead. Well that's not very nice.
- Shows a message for users with the yet another privilege permission that says "You have yet another privilege."
- This one is working as expected.
- If multiple scenarios apply, it should show all of the above messages.
- It's actually only showing one of these messages.
- If a user is not logged in, they should get an access forbidden error.
- It's actually showing them the message shown to authenticated users.
Labs
The following labs are available to help provide some test writing examples:
- Writing unit tests with PHPUnit
- Writing kernel tests with PHPUnit
- Writing system tests with PHPUnit and Nightwatch.js
- Writing acceptance tests with behat
Test Runners
PHPUnit (PHP Testing)
PHPUnit is a tool for testing PHP functionality in Drupal.
There are a few different ways to run PHPUnit tests. This training uses the core/scripts/run-tests.sh
method, as that is what DrupalCI uses.
Run all PHPUnit tests:
If you want to run all PHPUnit-based tests for your module, you can do so with one of the following commands:
- From inside the DDEV-Local container (i.e. after running
ddev ssh
):php core/scripts/run-tests.sh --color --verbose --sqlite /tmp/a.sqlite my_testing_module
- From outside the DDEV-Local container:
ddev exec php core/scripts/run-tests.sh --color --verbose --sqlite /tmp/a.sqlite my_testing_module
Note: We're using the --sqlite
flag. When the test runner bootstraps Drupal, it will save results in a sqlite database, that we're just storing in the /tmp
directory for now. Alternatively we could download the SimpleTest module (contrib as of D9) and use mysql DB instead.
Run specific PHPUnit tests:
Running every test, all the time, can sometimes take a while. If you want to focus on a specific test you can do so by using the --class
flag instead:
- From inside the DDEV-Local container (i.e. after running
ddev ssh
):php core/scripts/run-tests.sh --color --verbose --sqlite /tmp/a.sqlite --class 'Drupal\Tests\my_testing_module\Functional\MyFunctionalTest'
- From outside the DDEV-Local container: (note the double-quotes on the
ddev exec
command)ddev exec "php core/scripts/run-tests.sh --color --verbose --sqlite /tmp/a.sqlite --class 'Drupal\Tests\my_testing_module\Functional\MyFunctionalTest'"
Nightwatch.js (Javascript Testing)
Nightwatch.js is a tool used for javascript testing in Drupal.
To add support for nightwatch testing in DDEV-Local, a docker-compose.chromedriver.yml file must be added into your .ddev
directory.
Read Matt Glaman's Running Drupal's Nightwatch test suite on DDEV article for more information about setting this up.
Run all Nightwatch.js tests
-
From inside the DDEV-Local container (i.e. after running
ddev ssh
):cd /var/www/html/web/core yarn test:nightwatch ../modules/custom/my_testing_module/tests/src/Nightwatch
-
From outside the DDEV-Local container (Note: You have to specify which directory to run inside using the
-d
flag, and all other paths are relative to that):ddev exec -d /var/www/html/web/core yarn test:nightwatch ../modules/custom/my_testing_module/tests/src/Nightwatch
Run specific Nightwatch.js tests
- From inside the DDEV-Local container (i.e. after running
ddev ssh
):
cd /var/www/html/web/core
yarn test:nightwatch ../modules/custom/my_testing_module/tests/src/Nightwatch/MyNightwatchTest.js
- From outside the DDEV-Local container (Note you have to specify which directory to run inside using the
-d
flag, and all other paths are relative to that):
ddev exec -d /var/www/html/web/core yarn test:nightwatch ../modules/custom/my_testing_module/tests/src/Nightwatch/MyNightwatchTest.js
Behat (Behavioral Testing w/ Cucumber)
Behat is a tool for behavorial testing in Drupal.
Run all behat tests
- From inside the DDEV-Local container (i.e. after running
ddev ssh
):
cd /var/www/html && behat
- From outside the DDEV-Local container (Note you have to specify which directory to run inside using the
-d
flag, and all other paths are relative to that):
ddev exec -d /var/www/html behat
Run specific behat tests
- From inside the DDEV-Local container (i.e. after running
ddev ssh
):
cd /var/www/html && behat features/drupal/cache.feature
- From outside the DDEV-Local container (Note you have to specify which directory to run inside using the
-d
flag, and all other paths are relative to that):
ddev exec -d /var/www/html behat