Mercurial > hg > cmmr2012-drupal-site

comparison core/tests/README.md @ 5:12f9dff5fda9 tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update to Drupal core 8.7.1
author Chris Cannam
date Thu, 09 May 2019 15:34:47 +0100
parents a9cd425dd02b
children
comparison
equal deleted inserted replaced
4:a9cd425dd02b 5:12f9dff5fda9
1 # Running tests 1 # Running tests
2 2
3 ## Functional tests 3 ## Setting up
4 4
5 * Run the functional tests: 5 ### PHP dependencies
6 ```
7 export SIMPLETEST_DB='mysql://root@localhost/dev_d8';
8 export SIMPLETEST_BASE_URL='http://d8.dev';
9 ./vendor/bin/phpunit -c core --testsuite functional;
10 ```
11 6
12 Note: functional tests have to be invoked with a user in the same group as the 7 You need the Drupal core development dependencies installed, in order to run
13 web server user. You can either configure Apache (or nginx) to run as your own 8 any tests. You can install them using Composer by running
14 system user or run tests as a privileged user instead. 9 ```
10 composer install
11 ```
12 in the Drupal root directory. These dependencies should not be installed on a
13 production site.
15 14
16 Invoking tests with a user that is in the same group as the web server will 15 ### Test directory
17 require you to ensure Drupal keeps gid stickybits when creating new directories.
18 16
19 `$settings['file_chmod_directory'] = 02775;` 17 Create a directory called sites/simpletest and make sure that it is writable by
18 the web server and/or all users.
20 19
21 To develop locally, a straightforward - but also less secure - approach is to 20 ### PHPUnit configuration
22 run tests as your own system user. To achieve that, change the default Apache
23 user to run as your system user. Typically, you'd need to modify
24 `/etc/apache2/envvars` on Linux or `/etc/apache2/httpd.conf` on Mac.
25 21
26 Example for Linux: 22 Copy the core/phpunit.xml.dist file to phpunit.xml, and place it somewhere
23 convenient (inside the core directory may not be the best spot, since that
24 directory may be managed by Composer or Git). You can use the -c option on the
25 command line to tell PHPUnit where this file is (use the full path).
27 26
27 Settings to change in this file:
28 * SIMPLETEST_BASE_URL: The URL of your site
29 * SIMPLETEST_DB: The URL of your Drupal database
30 * The bootstrap attribute of the top-level phpunit tag, to take into account
31 the location of the file
32 * BROWSERTEST_OUTPUT_DIRECTORY: Set to sites/simpletest/browser_output;
33 you will also want to uncomment the printerClass attribute of the
34 top-level phpunit tag.
35
36 ### Additional setup for JavaScript tests
37
38 To run JavaScript tests based on the
39 \Drupal\FunctionalJavascriptTests\WebDriverTestBase base class, you will need
40 to install the following additional software:
41
42 * Google Chrome or Chromium browser
43 * chromedriver (tested with version 2.45) -- see
44 https://sites.google.com/a/chromium.org/chromedriver/
45 * PHP 7.1 or higher
46
47 ## Running unit, functional, and kernel tests
48
49 The PHPUnit executable is vendor/bin/phpunit -- you will need to locate your
50 vendor directory (which may be outside the Drupal root).
51
52 Here are commands to run one test class, list groups, and run all the tests in
53 a particular group:
28 ``` 54 ```
29 export APACHE_RUN_USER=<your-user> 55 ./vendor/bin/phpunit -c /path/to/your/phpunit.xml path/to/your/class/file.php
30 export APACHE_RUN_GROUP=<your-group> 56 ./vendor/bin/phpunit --list-groups
57 ./vendor/bin/phpunit -c /path/to/your/phpunit.xml --group Groupname
31 ``` 58 ```
32 59
33 Example for Mac: 60 More information on running tests can be found at
61 https://www.drupal.org/docs/8/phpunit/running-phpunit-tests
34 62
63 ## Running Functional JavaScript tests
64
65 You can run JavaScript tests that are based on the
66 \Drupal\FunctionalJavascriptTests\WebDriverTestBase base class in the same way
67 as other PHPUnit tests, except that before you start, you will need to start
68 chromedriver using port 4444, and keep it running:
35 ``` 69 ```
36 User <your-user> 70 /path/to/chromedriver --port=4444
37 Group <your-group>
38 ``` 71 ```
39 72
40 ## Functional javascript tests 73 ## Running Nightwatch tests
41 74
42 Javascript tests use the Selenium2Driver which allows you to control a 75 * Ensure your vendor directory is populated
43 big range of browsers. By default Drupal uses chromedriver to run tests. 76 (e.g. by running `composer install`)
44 For help installing and starting selenium, see http://mink.behat.org/en/latest/drivers/selenium2.html 77 * If you're running PHP 7.0 or greater you will need to upgrade PHPUnit with
78 `composer run-script drupal-phpunit-upgrade`
79 * Install [Node.js](https://nodejs.org/en/download/) and
80 [yarn](https://yarnpkg.com/en/docs/install). The versions required are
81 specificed inside core/package.json in the `engines` field
82 * Install
83 [Google Chrome](https://www.google.com/chrome/browser/desktop/index.html)
84 * Inside the `core` folder, run `yarn install`
85 * Configure the nightwatch settings by copying `.env.example` to `.env` and
86 editing as necessary.
87 * Ensure you have a web server running (as instructed in `.env`)
88 * Again inside the `core` folder, run `yarn test:nightwatch` to run the tests.
89 By default this will output reports to `core/reports`
90 * Nightwatch will run tests for core, as well as contrib and custom modules and
91 themes. It will search for tests located under folders with the pattern
92 `**/tests/**/Nightwatch/(Tests|Commands|Assertions)`
93 * To run only core tests, run `yarn test:nightwatch --tag core`
94 * To skip running core tests, run `yarn test:nightwatch --skiptags core`
95 * To run a single test, run e.g.
96 `yarn test:nightwatch tests/Drupal/Nightwatch/Tests/exampleTest.js`
45 97
46 * Make sure you have a recent version of chrome installed 98 Nightwatch tests, as well as custom commands, assertions and pages, can be
47 99 placed in any folder with the pattern
48 * Install selenium-server-standalone and chromedriver 100 `**/tests/**/Nightwatch/(Tests|Commands|Assertions|Pages)`. For example:
49
50 Example for Mac:
51
52 ```
53 brew install selenium-server-standalone;
54 brew install chromedriver;
55 ```
56
57 * Before running tests make sure that selenium-server is running
58 ```
59 selenium-server -port 4444
60 ```
61
62 * Set the correct driver args and run the tests:
63 ```
64 export MINK_DRIVER_ARGS_WEBDRIVER='["chrome", null, "http://localhost:4444/wd/hub"]';
65 ./vendor/bin/phpunit -c core --testsuite functional-javascript;
66 ```
67
68 * It is possible to use alternate browsers if the required dependencies are
69 installed. For example to use Firefox:
70
71 ```
72 export MINK_DRIVER_ARGS_WEBDRIVER='["firefox", null, "http://localhost:4444/wd/hub"]';
73 ./vendor/bin/phpunit -c core --testsuite functional-javascript;
74 ```
75
76 * To force all BrowserTestBase (including legacy JavascriptTestBase) tests to use
77 webdriver:
78
79 ```
80 export MINK_DRIVER_CLASS='Drupal\FunctionalJavascriptTests\DrupalSelenium2Driver';
81 ./vendor/bin/phpunit -c core --testsuite functional-javascript;
82 ```
83
84 ## Running legacy javascript tests
85
86 Older javascript test may use the PhantomJSDriver. To run these tests you will
87 have to install and start PhantomJS.
88
89 * Start PhantomJS:
90 ```
91 phantomjs --ssl-protocol=any --ignore-ssl-errors=true ./vendor/jcalderonzumba/gastonjs/src/Client/main.js 8510 1024 768 2>&1 >> /dev/null &
92 ```
93
94 * Then you can run the test:
95 ```
96 ./vendor/bin/phpunit -c core --testsuite functional-javascript;
97 ```
98
99 ## Running tests with a different user
100
101 If the default user is e.g. `www-data`, the above functional tests will have to
102 be invoked with sudo instead:
103
104 ```
105 export SIMPLETEST_DB='mysql://root@localhost/dev_d8';
106 export SIMPLETEST_BASE_URL='http://d8.dev';
107 sudo -u www-data -E ./vendor/bin/phpunit -c core --testsuite functional;
108 sudo -u www-data -E ./vendor/bin/phpunit -c core --testsuite functional-javascript;
109 ```
110
111 ## Nightwatch tests
112
113 - Ensure your vendor directory is populated (e.g. by running `composer install`)
114 - If you're running PHP 7.0 or greater you will need to upgrade PHPUnit with `composer run-script drupal-phpunit-upgrade`
115 - Install [Node.js](https://nodejs.org/en/download/) and [yarn](https://yarnpkg.com/en/docs/install). The versions required are specificed inside core/package.json in the `engines` field
116 - Install [Google Chrome](https://www.google.com/chrome/browser/desktop/index.html)
117 - Inside the `core` folder, run `yarn install`
118 - Configure the nightwatch settings by copying `.env.example` to `.env` and editing as necessary.
119 - Ensure you have a web server running (as instructed in `.env`)
120 - Again inside the `core` folder, run `yarn test:nightwatch` to run the tests. By default this will output reports to `core/reports`
121 - 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)`
122 - To run only core tests, run `yarn test:nightwatch --tag core`
123 - To skip running core tests, run `yarn test:nightwatch --skiptags core`
124 - To run a single test, run e.g. `yarn test:nightwatch tests/Drupal/Nightwatch/Tests/exampleTest.js`
125
126 Nightwatch tests can be placed in any folder with the pattern `**/tests/**/Nightwatch/(Tests|Commands|Assertions)`. For example:
127 ``` 101 ```
128 tests/Nightwatch/Tests 102 tests/Nightwatch/Tests
129 src/tests/Nightwatch/Tests 103 src/tests/Nightwatch/Tests
130 tests/src/Nightwatch/Tests 104 tests/src/Nightwatch/Tests
131 tests/Nightwatch/Commands 105 tests/Nightwatch/Commands
106 tests/src/Nightwatch/Assertions
107 tests/src/Nightwatch/Pages
132 ``` 108 ```
133 109
134 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`. 110 It's helpful to follow existing patterns for test placement, so for the action
135 The Nightwatch configuration, as well as global tests, commands, and assertions which span many modules/systems, are located in `core/tests/Drupal/Nightwatch`. 111 module they would go in `core/modules/action/tests/src/Nightwatch`.
112 The Nightwatch configuration, as well as global tests, commands, and assertions
113 which span many modules/systems, are located in `core/tests/Drupal/Nightwatch`.
136 114
137 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. 115 If your core directory is located in a subfolder (e.g. `docroot`), then you can
138 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, 116 edit the search directory in `.env` to pick up tests outside of your Drupal
139 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 117 directory. Tests outside of the `core` folder will run in the version of node
140 `docroot`, then copy the babel settings from `docroot/core/package.json` into `docroot/package.json`. 118 you have installed. If you want to transpile with babel (e.g. to use `import`
119 statements) outside of core, then add your own babel config to the root of your
120 project. For example, if core is located under `docroot/core`, then you could
121 run `yarn add babel-preset-env` inside `docroot`, then copy the babel settings
122 from `docroot/core/package.json` into `docroot/package.json`.
123
124 ## Troubleshooting test running
125
126 If you run into file permission problems while running tests, you may need to
127 invoke the phpunit executable with a user in the same group as the web server
128 user, or with access to files owned by the web server user. For example:
129 ```
130 sudo -u www-data ./vendor/bin/phpunit -c /path/to/your/phpunit.xml --group Groupname
131 ```
132
133 If you have permission problems accessing files after running tests, try
134 putting
135 ```
136 $settings['file_chmod_directory'] = 02775;
137 ```
138 in your settings.php or local.settings.php file.
139
140 You may need to use absolute paths in your phpunit.xml file, and/or in your
141 phpunit command arguments.