Chris@0: # Running tests Chris@0: Chris@18: ## Setting up Chris@0: Chris@18: ### PHP dependencies Chris@0: Chris@18: You need the Drupal core development dependencies installed, in order to run Chris@18: any tests. You can install them using Composer by running Chris@18: ``` Chris@18: composer install Chris@18: ``` Chris@18: in the Drupal root directory. These dependencies should not be installed on a Chris@18: production site. Chris@0: Chris@18: ### Test directory Chris@17: Chris@18: Create a directory called sites/simpletest and make sure that it is writable by Chris@18: the web server and/or all users. Chris@17: Chris@18: ### PHPUnit configuration Chris@0: Chris@18: Copy the core/phpunit.xml.dist file to phpunit.xml, and place it somewhere Chris@18: convenient (inside the core directory may not be the best spot, since that Chris@18: directory may be managed by Composer or Git). You can use the -c option on the Chris@18: command line to tell PHPUnit where this file is (use the full path). Chris@0: Chris@18: Settings to change in this file: Chris@18: * SIMPLETEST_BASE_URL: The URL of your site Chris@18: * SIMPLETEST_DB: The URL of your Drupal database Chris@18: * The bootstrap attribute of the top-level phpunit tag, to take into account Chris@18: the location of the file Chris@18: * BROWSERTEST_OUTPUT_DIRECTORY: Set to sites/simpletest/browser_output; Chris@18: you will also want to uncomment the printerClass attribute of the Chris@18: top-level phpunit tag. Chris@18: Chris@18: ### Additional setup for JavaScript tests Chris@18: Chris@18: To run JavaScript tests based on the Chris@18: \Drupal\FunctionalJavascriptTests\WebDriverTestBase base class, you will need Chris@18: to install the following additional software: Chris@18: Chris@18: * Google Chrome or Chromium browser Chris@18: * chromedriver (tested with version 2.45) -- see Chris@18: https://sites.google.com/a/chromium.org/chromedriver/ Chris@18: * PHP 7.1 or higher Chris@18: Chris@18: ## Running unit, functional, and kernel tests Chris@18: Chris@18: The PHPUnit executable is vendor/bin/phpunit -- you will need to locate your Chris@18: vendor directory (which may be outside the Drupal root). Chris@18: Chris@18: Here are commands to run one test class, list groups, and run all the tests in Chris@18: a particular group: Chris@0: ``` Chris@18: ./vendor/bin/phpunit -c /path/to/your/phpunit.xml path/to/your/class/file.php Chris@18: ./vendor/bin/phpunit --list-groups Chris@18: ./vendor/bin/phpunit -c /path/to/your/phpunit.xml --group Groupname Chris@0: ``` Chris@0: Chris@18: More information on running tests can be found at Chris@18: https://www.drupal.org/docs/8/phpunit/running-phpunit-tests Chris@0: Chris@18: ## Running Functional JavaScript tests Chris@18: Chris@18: You can run JavaScript tests that are based on the Chris@18: \Drupal\FunctionalJavascriptTests\WebDriverTestBase base class in the same way Chris@18: as other PHPUnit tests, except that before you start, you will need to start Chris@18: chromedriver using port 4444, and keep it running: Chris@0: ``` Chris@18: /path/to/chromedriver --port=4444 Chris@0: ``` Chris@0: Chris@18: ## Running Nightwatch tests Chris@14: Chris@18: * Ensure your vendor directory is populated Chris@18: (e.g. by running `composer install`) Chris@18: * If you're running PHP 7.0 or greater you will need to upgrade PHPUnit with Chris@18: `composer run-script drupal-phpunit-upgrade` Chris@18: * Install [Node.js](https://nodejs.org/en/download/) and Chris@18: [yarn](https://yarnpkg.com/en/docs/install). The versions required are Chris@18: specificed inside core/package.json in the `engines` field Chris@18: * Install Chris@18: [Google Chrome](https://www.google.com/chrome/browser/desktop/index.html) Chris@18: * Inside the `core` folder, run `yarn install` Chris@18: * Configure the nightwatch settings by copying `.env.example` to `.env` and Chris@18: editing as necessary. Chris@18: * Ensure you have a web server running (as instructed in `.env`) Chris@18: * Again inside the `core` folder, run `yarn test:nightwatch` to run the tests. Chris@18: By default this will output reports to `core/reports` Chris@18: * Nightwatch will run tests for core, as well as contrib and custom modules and Chris@18: themes. It will search for tests located under folders with the pattern Chris@18: `**/tests/**/Nightwatch/(Tests|Commands|Assertions)` Chris@18: * To run only core tests, run `yarn test:nightwatch --tag core` Chris@18: * To skip running core tests, run `yarn test:nightwatch --skiptags core` Chris@18: * To run a single test, run e.g. Chris@18: `yarn test:nightwatch tests/Drupal/Nightwatch/Tests/exampleTest.js` Chris@14: Chris@18: Nightwatch tests, as well as custom commands, assertions and pages, can be Chris@18: placed in any folder with the pattern Chris@18: `**/tests/**/Nightwatch/(Tests|Commands|Assertions|Pages)`. For example: Chris@17: ``` Chris@17: tests/Nightwatch/Tests Chris@17: src/tests/Nightwatch/Tests Chris@17: tests/src/Nightwatch/Tests Chris@17: tests/Nightwatch/Commands Chris@18: tests/src/Nightwatch/Assertions Chris@18: tests/src/Nightwatch/Pages Chris@17: ``` Chris@17: Chris@18: It's helpful to follow existing patterns for test placement, so for the action Chris@18: module they would go in `core/modules/action/tests/src/Nightwatch`. Chris@18: The Nightwatch configuration, as well as global tests, commands, and assertions Chris@18: which span many modules/systems, are located in `core/tests/Drupal/Nightwatch`. Chris@17: Chris@18: If your core directory is located in a subfolder (e.g. `docroot`), then you can Chris@18: edit the search directory in `.env` to pick up tests outside of your Drupal Chris@18: directory. Tests outside of the `core` folder will run in the version of node Chris@18: you have installed. If you want to transpile with babel (e.g. to use `import` Chris@18: statements) outside of core, then add your own babel config to the root of your Chris@18: project. For example, if core is located under `docroot/core`, then you could Chris@18: run `yarn add babel-preset-env` inside `docroot`, then copy the babel settings Chris@18: from `docroot/core/package.json` into `docroot/package.json`. Chris@18: Chris@18: ## Troubleshooting test running Chris@18: Chris@18: If you run into file permission problems while running tests, you may need to Chris@18: invoke the phpunit executable with a user in the same group as the web server Chris@18: user, or with access to files owned by the web server user. For example: Chris@18: ``` Chris@18: sudo -u www-data ./vendor/bin/phpunit -c /path/to/your/phpunit.xml --group Groupname Chris@18: ``` Chris@18: Chris@18: If you have permission problems accessing files after running tests, try Chris@18: putting Chris@18: ``` Chris@18: $settings['file_chmod_directory'] = 02775; Chris@18: ``` Chris@18: in your settings.php or local.settings.php file. Chris@18: Chris@18: You may need to use absolute paths in your phpunit.xml file, and/or in your Chris@18: phpunit command arguments.