Commit e7076173 authored by Andrew Berry's avatar Andrew Berry Committed by Moshe Weitzman
Browse files

Clarify webdriver / chromedriver and screenshot debugging

parent 9e90ba12
Pipeline #636728052 failed with stage
in 7 minutes
......@@ -22,15 +22,15 @@ Traits for testing Drupal sites that have user content (versus unpopulated sites
Pick a test type:
- **ExistingSite**. See [ExampleTest.php](./tests/ExampleTest.php). Start here. These tests can be small unit tests up to larger functional tests (via [Goutte](http://goutte.readthedocs.io/en/latest/)). Tests of this type should be placed in `tests/src/ExistingSite`.
- **ExistingSiteSelenium2DriverTest**. See [ExampleSelenium2DriverTest.php](tests/ExampleSelenium2DriverTest.php). These tests make use of any browser which can run in web driver mode (Chrome, FireFox or Edge) via Selenium, so are suited to testing Ajax and similar client side interactions. This browser setup can also be used to run Drupal 8 core JS testing using [nightwatch](https://www.drupal.org/node/2968570). These tests run slower than ExistingSite. To use this test type you need to `composer require 'behat/mink-selenium2-driver' --dev`. Tests of this type should be placed in `tests/src/ExistingSiteJavascript`.
- **ExistingSiteWebDriverTest**. See [ExampleWebDriverTest.php](tests/ExampleWebDriverTest.php). These tests make use of a headless Chrome browser, so are suited to testing Ajax and similar client side interactions. These tests run slower than ExistingSite. To use this test type you need to `composer require 'dmore/chrome-mink-driver' --dev`. Tests of this type should be placed in `tests/src/ExistingSiteJavascript`.
- **ExistingSiteSelenium2DriverTest**. See [ExampleSelenium2DriverTest.php](tests/ExampleSelenium2DriverTest.php). These tests make use of any browser which can run in [WebDriver] mode (Chrome, Firefox or Edge) via [Selenium](https://www.selenium.dev) or browser specific drivers like [chromedriver](https://chromedriver.chromium.org). They are suited to testing Ajax and similar client side interactions. This browser setup can also be used to run Drupal 8 core JS testing using [nightwatch](https://www.drupal.org/node/2968570). These tests run slower than ExistingSite. To use this test type you need to `composer require 'behat/mink-selenium2-driver' --dev`. Tests of this type should be placed in `tests/src/ExistingSiteJavascript`.
- (deprecated) **ExistingSiteWebDriverTest**. See [ExampleWebDriverTest.php](tests/ExampleWebDriverTest.php). These tests make use of a headless Chrome browser but using [Chrome's Debugger Protocol](https://packagist.org/packages/dmore/chrome-mink-driver). They are suited to testing Ajax and similar client side interactions. These tests run slower than ExistingSite. To use this test type you need to `composer require 'dmore/chrome-mink-driver' --dev`. Tests of this type should be placed in `tests/src/ExistingSiteJavascript`. Contrary to its name, this test type does not use the WebDriver protocol at all.
Extend the base class that corresponds to your pick above: [ExistingSiteBase.php](src/ExistingSiteBase.php), [ExistingSiteSelenium2DriverTestBase.php](src/ExistingSiteSelenium2DriverTestBase.php), or [ExistingSiteWebDriverTestBase.php](src/ExistingSiteWebDriverTestBase.php). You may extend it directly from your test class or create a base class for your project that extends one of these. To choose between Selenium2 or WebDriver for JS testing, read [testing Drupal with WebDriver browser mode vs Headless browser mode](https://www.previousnext.com.au/blog/testing-drupal-webdriver-browser-mode-vs-headless-browser-mode).
## Running tests
1. Create or edit `phpunit.xml` to include new testsuites for `existing-site` and `existing-site-javascript` ([example phpunit.xml](docs/phpunit.xml)).
2. Specify the URL to your existing site with `DTT_BASE_URL=http://example.com`. For ExistingSiteSelenium2DriverTest tests, also specify `DTT_MINK_DRIVER_ARGS=["firefox", null, "http://selenium:9222/wd/hub"]`. For ExistingSiteWebDriverTest tests, also specify `DTT_API_URL=http://localhost:9222`. You can also change timeouts like this: `DTT_API_OPTIONS={"socketTimeout": 360, "domWaitTimeout": 3600000}` (note the JSON string). You can specify these environment variables one of three ways:
2. Specify the URL to your existing site with `DTT_BASE_URL=http://example.com`. For ExistingSiteSelenium2DriverTest tests, also specify `DTT_MINK_DRIVER_ARGS=["firefox", null, "http://selenium:4444/wd/hub"]`. For ExistingSiteWebDriverTest tests, also specify `DTT_API_URL=http://localhost:9222`. You can also change timeouts like this: `DTT_API_OPTIONS={"socketTimeout": 360, "domWaitTimeout": 3600000}` (note the JSON string). You can specify these environment variables one of three ways:
- Add them to your `phpunit.xml` ([example phpunit.xml](docs/phpunit.xml)).
- Add them to your `.env` (supported by [drupal-project](https://github.com/drupal-composer/drupal-project/blob/8.x/.env.example) and [Docker](https://docs.docker.com/compose/env-file/)).
- Specify them at runtime: `DTT_BASE_URL=http://127.0.0.1:8888; DTT_API_URL=http://localhost:9222 vendor/bin/phpunit ...`
......@@ -47,7 +47,7 @@ vendor/bin/phpunit --group CustomTestGroup
- All HTML requests can be logged. To do so, add `BROWSERTEST_OUTPUT_DIRECTORY=/tmp` and `--printer '\\Drupal\\Tests\\Listeners\\HtmlOutputPrinter'` to the `phpunit` call. To disable deprecation notices, include `SYMFONY_DEPRECATIONS_HELPER=disabled`. Alternatively, you can specify these in your `phpunit.xml` ([example phpunit.xml](docs/phpunit.xml)).
- To write the current HTML of the page to a file, use `$this->capturePageContent()`. If using HtmlOutputPrinter this will be saved to the browser_output directory. Alternatively you can specify `DTT_HTML_OUTPUT_DIRECTORY=/path/to/output_directory` which is required when using a different printer, such as Teamcity, which is enforced by PHPStorm.
- To take a screenshot of the current page under ExistingSiteSelenium2DriverTest or ExistingSiteWebDriverTest, use `\weitzman\DrupalTestTraits\ScreenShotTrait::captureScreenshot`.
- To take a screenshot of the current page under ExistingSiteSelenium2DriverTest or ExistingSiteWebDriverTest, use `\weitzman\DrupalTestTraits\ScreenShotTrait::captureScreenshot`. Be careful when using this to debug tests that are "randomly" failing. Most likely, these tests are failing due to missing [`waitForElementVisible`](https://api.drupal.org/api/drupal/core%21tests%21Drupal%21FunctionalJavascriptTests%21JSWebAssert.php/function/JSWebAssert%3A%3AwaitForElementVisible/9.3.x) checks, as the act of taking a screenshot gives the browser additional time to finish rendering the page.
## Available traits
......@@ -61,7 +61,7 @@ vendor/bin/phpunit --group CustomTestGroup
Makes [Selenium2Driver](https://github.com/minkphp/MinkSelenium2Driver) available for browser control with Selenium. Suitable for functional JS testing.
- **WebDriverTrait**
Makes [ChromeDriver]([ChromeDriver](https://gitlab.com/DMore/chrome-mink-driver/)) available for browser control without the overhead of Selenium. Suitable for functional JS testing.
Makes [Chrome Mink Driver](https://gitlab.com/DMore/chrome-mink-driver/) available for browser control without the overhead of Selenium by using Chrome's debugger protocol. Suitable for functional JS testing.
- **NodeCreationTrait**
Create nodes that are deleted at the end of the test method.
......
......@@ -9,6 +9,10 @@ use Drupal\FunctionalJavascriptTests\JSWebAssert;
* - Copy its code into your own base class.
* - Have your base class extend this class.
* - Your tests may extend this class directly.
*
* This class uses the WebDriver protocol to interact with browsers. It can
* be used with any system that implements webdriver, such as chromedriver or
* Selenium.
*/
abstract class ExistingSiteSelenium2DriverTestBase extends ExistingSiteBase
{
......
......@@ -9,6 +9,13 @@ use Drupal\FunctionalJavascriptTests\JSWebAssert;
* - Copy its code into your own base class.
* - Have your base class extend this class.
* - Your tests may extend this class directly.
*
* Note that this class does not use the WebDriver protocol. Instead, it uses
* the Chrome Debugger protocol. For WebDriver support, see
* \weitzman\DrupalTestTraits\ExistingSiteSelenium2DriverTestBase.
*
* @deprecated Deprecated in 1.6.0, will be removed in 2.0. Use
* \weitzman\DrupalTestTraits\ExistingSiteSelenium2DriverTestBase instead.
*/
abstract class ExistingSiteWebDriverTestBase extends ExistingSiteBase
{
......
......@@ -8,7 +8,9 @@ use Drupal\taxonomy\Entity\Vocabulary;
use weitzman\DrupalTestTraits\ExistingSiteWebDriverTestBase;
/**
* A WebDriver test suitable for testing Ajax and client-side interactions.
* A Chrome Mink Driver test suitable for testing Ajax and client-side interactions.
*
* This test uses Chrome's debugger protocol to execute tests.
*/
class ExampleWebDriverTest extends ExistingSiteWebDriverTestBase
{
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment