README.md 5.58 KB
Newer Older
1
2
# Running tests

3
## Setting up
4

5
6
7
8
### PHP dependencies

You need the Drupal core development dependencies installed, in order to run
any tests. You can install them using Composer by running
9
10
11
```
composer install
```
12
13
in the Drupal root directory. These dependencies should not be installed on a
production site.
14

15
### Test directory
16

17
18
Create a directory called sites/simpletest and make sure that it is writable by
the web server and/or all users.
19

20
### PHPUnit configuration
21

22
23
24
25
Copy the core/phpunit.xml.dist file to phpunit.xml, and place it somewhere
convenient (inside the core directory may not be the best spot, since that
directory may be managed by Composer or Git). You can use the -c option on the
command line to tell PHPUnit where this file is (use the full path).
26

27
28
29
30
31
32
33
34
Settings to change in this file:
* SIMPLETEST_BASE_URL: The URL of your site
* SIMPLETEST_DB: The URL of your Drupal database
* The bootstrap attribute of the top-level phpunit tag, to take into account
  the location of the file
* BROWSERTEST_OUTPUT_DIRECTORY: Set to sites/simpletest/browser_output;
  you will also want to uncomment the printerClass attribute of the
  top-level phpunit tag.
35

36
### Additional setup for JavaScript tests
37

38
To run JavaScript tests  based on the
39
40
\Drupal\FunctionalJavascriptTests\WebDriverTestBase base class, you will need
to install the following additional software:
41

42
43
44
45
* Google Chrome or Chromium browser
* chromedriver (tested with version 2.45) -- see
  https://sites.google.com/a/chromium.org/chromedriver/
* PHP 7.1 or higher
46

47
## Running unit, functional, and kernel tests
48

49
50
The PHPUnit executable is vendor/bin/phpunit -- you will need to locate your
vendor directory (which may be outside the Drupal root).
51

52
53
Here are commands to run one test class, list groups, and run all the tests in
a particular group:
54
```
55
56
57
./vendor/bin/phpunit -c /path/to/your/phpunit.xml path/to/your/class/file.php
./vendor/bin/phpunit --list-groups
./vendor/bin/phpunit -c /path/to/your/phpunit.xml --group Groupname
58
59
```

60
61
More information on running tests can be found at
https://www.drupal.org/docs/8/phpunit/running-phpunit-tests
62

63
## Running Functional JavaScript tests
64

65
66
67
68
You can run JavaScript tests that are based on the
\Drupal\FunctionalJavascriptTests\WebDriverTestBase base class in the same way
as other PHPUnit tests, except that before you start, you will need to start
chromedriver using port 4444, and keep it running:
69
```
70
/path/to/chromedriver --port=4444
71
```
72

73
## Running Nightwatch tests
74

75
76
77
78
* Ensure your vendor directory is populated
  (e.g. by running `composer install`)
* Install [Node.js](https://nodejs.org/en/download/) and
  [yarn](https://yarnpkg.com/en/docs/install). The versions required are
79
80
81
  specified inside core/package.json in the `engines` field. You can use
  [nvm](https://github.com/nvm-sh/nvm) and [yvm](https://github.com/tophat/yvm)
  to manage your local versions of these.
82
83
84
85
86
87
* Install
  [Google Chrome](https://www.google.com/chrome/browser/desktop/index.html)
* Inside the `core` folder, run `yarn install`
* Configure the nightwatch settings by copying `.env.example` to `.env` and
  editing as necessary.
* Ensure you have a web server running (as instructed in `.env`)
88
89
* Again inside the `core` folder, run `yarn test:nightwatch --env local` to run
  the tests.
90
91
92
93
94
95
96
97
98
99
100
101
  By default this will output reports to `core/reports`
* Nightwatch will run tests for core, as well as contrib and custom modules and
  themes. It will search for tests located under folders with the pattern
  `**/tests/**/Nightwatch/(Tests|Commands|Assertions)`
* To run only core tests, run `yarn test:nightwatch --tag core`
* To skip running core tests, run `yarn test:nightwatch --skiptags core`
* To run a single test, run e.g.
  `yarn test:nightwatch tests/Drupal/Nightwatch/Tests/exampleTest.js`

Nightwatch tests, as well as custom commands, assertions and pages, can be
placed in any folder with the pattern
`**/tests/**/Nightwatch/(Tests|Commands|Assertions|Pages)`. For example:
102
103
104
105
106
```
tests/Nightwatch/Tests
src/tests/Nightwatch/Tests
tests/src/Nightwatch/Tests
tests/Nightwatch/Commands
107
108
tests/src/Nightwatch/Assertions
tests/src/Nightwatch/Pages
109
110
```

111
112
113
114
115
116
117
118
119
120
121
122
123
It's helpful to follow existing patterns for test placement, so for the action
module they would go in `core/modules/action/tests/src/Nightwatch`.
The Nightwatch configuration, as well as global tests, commands, and assertions
which span many modules/systems, are located in `core/tests/Drupal/Nightwatch`.

If your core directory is located in a subfolder (e.g. `docroot`), then you can
edit the search directory in `.env` to pick up tests outside of your Drupal
directory. Tests outside of the `core` folder will run in the version of node
you have installed. If you want to transpile with babel (e.g. to use `import`
statements) outside of core, then add your own babel config to the root of your
project. For example, if core is located under `docroot/core`, then you could
run `yarn add babel-preset-env` inside `docroot`, then copy the babel settings
from `docroot/core/package.json` into `docroot/package.json`.
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

## Troubleshooting test running

If you run into file permission problems while running tests, you may need to
invoke the phpunit executable with a user in the same group as the web server
user, or with access to files owned by the web server user. For example:
```
sudo -u www-data ./vendor/bin/phpunit -c /path/to/your/phpunit.xml --group Groupname
```

If you have permission problems accessing files after running tests, try
putting
```
$settings['file_chmod_directory'] = 02775;
```
in your settings.php or local.settings.php file.

You may need to use absolute paths in your phpunit.xml file, and/or in your
phpunit command arguments.