BrowserTestBase.php

<?php

declare (strict_types=1);
namespace Drupal\Tests;

use Behat\Mink\Driver\BrowserKitDriver;
use Behat\Mink\Element\Element;
use Behat\Mink\Mink;
use Behat\Mink\Selector\SelectorsHandler;
use Behat\Mink\Session;
use Drupal\Component\Serialization\Json;
use Drupal\Component\Utility\UrlHelper;
use Drupal\Core\Database\Database;
use Drupal\Core\Test\FunctionalTestSetupTrait;
use Drupal\Core\Test\TestSetupTrait;
use Drupal\Core\Url;
use Drupal\Core\Utility\Error;
use Drupal\Tests\block\Traits\BlockCreationTrait;
use Drupal\Tests\node\Traits\ContentTypeCreationTrait;
use Drupal\Tests\node\Traits\NodeCreationTrait;
use Drupal\Tests\Traits\PhpUnitWarnings;
use Drupal\Tests\user\Traits\UserCreationTrait;
use Drupal\TestTools\Comparator\MarkupInterfaceComparator;
use Drupal\TestTools\TestVarDumper;
use GuzzleHttp\Cookie\CookieJar;
use PHPUnit\Framework\TestCase;
use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
use Symfony\Component\HttpFoundation\Exception\SessionNotFoundException;
use Symfony\Component\VarDumper\VarDumper;

/**
 * Provides a test case for functional Drupal tests.
 *
 * Tests extending BrowserTestBase must exist in the
 * Drupal\Tests\your_module\Functional namespace and live in the
 * modules/your_module/tests/src/Functional directory.
 *
 * Tests extending this base class should only translate text when testing
 * translation functionality. For example, avoid wrapping test text with t()
 * or TranslatableMarkup().
 *
 * Using Symfony's dump() function in functional test test code will produce
 * output on the command line; using dump() in site code will produce output in
 * the requested web page, which can then be inspected in the HTML output from
 * the test.
 *
 * @ingroup testing
 */
abstract class BrowserTestBase extends TestCase {
    use FunctionalTestSetupTrait;
    use UiHelperTrait {
        FunctionalTestSetupTrait::refreshVariables insteadof UiHelperTrait;
    }
    use TestSetupTrait;
    use BlockCreationTrait {
        placeBlock as drupalPlaceBlock;
    }
    use RandomGeneratorTrait;
    use NodeCreationTrait {
        getNodeByTitle as drupalGetNodeByTitle;
        createNode as drupalCreateNode;
    }
    use ContentTypeCreationTrait {
        createContentType as drupalCreateContentType;
    }
    use ConfigTestTrait;
    use TestRequirementsTrait;
    use UserCreationTrait {
        createRole as drupalCreateRole;
        createUser as drupalCreateUser;
    }
    use XdebugRequestTrait;
    use PhpUnitWarnings;
    use PhpUnitCompatibilityTrait;
    use ExpectDeprecationTrait;
    use ExtensionListTestTrait;
    
    /**
     * Time limit in seconds for the test.
     *
     * @var int
     */
    protected $timeLimit = 500;
    
    /**
     * The translation file directory for the test environment.
     *
     * This is set in BrowserTestBase::prepareEnvironment().
     *
     * @var string
     */
    protected $translationFilesDirectory;
    
    /**
     * The config importer that can be used in a test.
     *
     * @var \Drupal\Core\Config\ConfigImporter
     */
    protected $configImporter;
    
    /**
     * Modules to install.
     *
     * The test runner will merge the $modules lists from this class, the class
     * it extends, and so on up the class hierarchy. It is not necessary to
     * include modules in your list that a parent class has already declared.
     *
     * @var string[]
     *
     * @see \Drupal\Tests\BrowserTestBase::installDrupal()
     */
    protected static $modules = [];
    
    /**
     * The profile to install as a basis for testing.
     *
     * @var string
     */
    protected $profile = 'testing';
    
    /**
     * The theme to install as the default for testing.
     *
     * Defaults to the install profile's default theme, if it specifies any.
     *
     * @var string
     */
    protected $defaultTheme;
    
    /**
     * An array of custom translations suitable for SettingsEditor::rewrite().
     *
     * @var array
     *
     * @see \Drupal\Core\Site\SettingsEditor::rewrite()
     */
    protected $customTranslations;
    
    /**
     * Mink class for the default driver to use.
     *
     * Should be a fully-qualified class name that implements
     * Behat\Mink\Driver\DriverInterface.
     *
     * Value can be overridden using the environment variable MINK_DRIVER_CLASS.
     *
     * @var string
     */
    protected $minkDefaultDriverClass = BrowserKitDriver::class;
    
    /**
     * Mink default driver params.
     *
     * If it's an array its contents are used as constructor params when default
     * Mink driver class is instantiated.
     *
     * Can be overridden using the environment variable MINK_DRIVER_ARGS. In this
     * case that variable should be a JSON array, for example:
     * '["firefox", null, "http://localhost:4444/wd/hub"]'.
     *
     * @var array
     */
    protected $minkDefaultDriverArgs;
    
    /**
     * Mink session manager.
     *
     * This will not be initialized if there was an error during the test setup.
     *
     * @var \Behat\Mink\Mink|null
     */
    protected $mink;
    
    /**
     * {@inheritdoc}
     *
     * Browser tests are run in separate processes to prevent collisions between
     * code that may be loaded by tests.
     */
    protected $runTestInSeparateProcess = TRUE;
    
    /**
     * {@inheritdoc}
     */
    protected $preserveGlobalState = FALSE;
    
    /**
     * The base URL.
     *
     * @var string
     */
    protected $baseUrl;
    
    /**
     * The original array of shutdown function callbacks.
     *
     * @var array
     */
    protected $originalShutdownCallbacks = [];
    
    /**
     * The original container.
     *
     * Move this to \Drupal\Core\Test\FunctionalTestSetupTrait once TestBase no
     * longer provides the same value.
     *
     * @var \Symfony\Component\DependencyInjection\ContainerInterface
     */
    protected $originalContainer;
    
    /**
     * {@inheritdoc}
     */
    public static function setUpBeforeClass() : void {
        parent::setUpBeforeClass();
        VarDumper::setHandler(TestVarDumper::class . '::cliHandler');
    }
    
    /**
     * Initializes Mink sessions.
     */
    protected function initMink() {
        $driver = $this->getDefaultDriverInstance();
        if ($driver instanceof BrowserKitDriver) {
            // Turn off curl timeout. Having a timeout is not a problem in a normal
            // test running, but it is a problem when debugging. Also, disable SSL
            // peer verification so that testing under HTTPS always works.
            
            /** @var \GuzzleHttp\Client $client */
            $client = $this->container
                ->get('http_client_factory')
                ->fromOptions([
                'timeout' => NULL,
                'verify' => FALSE,
            ]);
            // Inject a Guzzle middleware to generate debug output for every request
            // performed in the test.
            $handler_stack = $client->getConfig('handler');
            $handler_stack->push($this->getResponseLogHandler());
            $driver->getClient()
                ->setClient($client);
        }
        $selectors_handler = new SelectorsHandler([
            'hidden_field_selector' => new HiddenFieldSelector(),
        ]);
        $session = new Session($driver, $selectors_handler);
        $this->mink = new Mink();
        $this->mink
            ->registerSession('default', $session);
        $this->mink
            ->setDefaultSessionName('default');
        $this->registerSessions();
        $this->initFrontPage();
        // Copies cookies from the current environment, for example, XDEBUG_SESSION
        // in order to support Xdebug.
        // @see BrowserTestBase::initFrontPage()
        $cookies = $this->extractCookiesFromRequest(\Drupal::request());
        foreach ($cookies as $cookie_name => $values) {
            foreach ($values as $value) {
                $session->setCookie($cookie_name, $value);
            }
        }
        return $session;
    }
    
    /**
     * Visits the front page when initializing Mink.
     *
     * According to the W3C WebDriver specification a cookie can only be set if
     * the cookie domain is equal to the domain of the active document. When the
     * browser starts up the active document is not our domain but 'about:blank'
     * or similar. To be able to set our User-Agent and Xdebug cookies at the
     * start of the test we now do a request to the front page so the active
     * document matches the domain.
     *
     * @see https://w3c.github.io/webdriver/webdriver-spec.html#add-cookie
     * @see https://www.w3.org/Bugs/Public/show_bug.cgi?id=20975
     */
    protected function initFrontPage() {
        $session = $this->getSession();
        $session->visit($this->baseUrl);
    }
    
    /**
     * Gets an instance of the default Mink driver.
     *
     * @return \Behat\Mink\Driver\DriverInterface
     *   Instance of default Mink driver.
     *
     * @throws \InvalidArgumentException
     *   When provided default Mink driver class can't be instantiated.
     */
    protected function getDefaultDriverInstance() {
        // Get default driver params from environment if available.
        if ($arg_json = $this->getMinkDriverArgs()) {
            $this->minkDefaultDriverArgs = json_decode($arg_json, TRUE);
        }
        // Get and check default driver class from environment if available.
        if ($minkDriverClass = getenv('MINK_DRIVER_CLASS')) {
            if (class_exists($minkDriverClass)) {
                $this->minkDefaultDriverClass = $minkDriverClass;
            }
            else {
                throw new \InvalidArgumentException("Can't instantiate provided {$minkDriverClass} class by environment as default driver class.");
            }
        }
        if ($this->minkDefaultDriverClass === BrowserKitDriver::class) {
            $driver = new $this->minkDefaultDriverClass(new DrupalTestBrowser());
        }
        elseif (is_array($this->minkDefaultDriverArgs)) {
            // Use ReflectionClass to instantiate class with received params.
            $reflector = new \ReflectionClass($this->minkDefaultDriverClass);
            $driver = $reflector->newInstanceArgs($this->minkDefaultDriverArgs);
        }
        else {
            $driver = new $this->minkDefaultDriverClass();
        }
        return $driver;
    }
    
    /**
     * Gets the Mink driver args from an environment variable.
     *
     * The environment variable can be overridden in a derived class so it is
     * possible to use a different value for a subset of tests, e.g. the
     * JavaScript tests.
     *
     * @return string|false
     *   The JSON-encoded argument string. False if it is not set.
     */
    protected function getMinkDriverArgs() {
        return getenv('MINK_DRIVER_ARGS');
    }
    
    /**
     * Registers additional Mink sessions.
     *
     * Tests wishing to use a different driver or change the default driver should
     * override this method.
     *
     * @code
     *   // Register a new session that uses the MinkPonyDriver.
     *   $pony = new MinkPonyDriver();
     *   $session = new Session($pony);
     *   $this->mink->registerSession('pony', $session);
     * @endcode
     */
    protected function registerSessions() {
    }
    
    /**
     * {@inheritdoc}
     */
    protected function setUp() : void {
        parent::setUp();
        $this->setUpAppRoot();
        // Allow tests to compare MarkupInterface objects via assertEquals().
        $this->registerComparator(new MarkupInterfaceComparator());
        $this->setupBaseUrl();
        // Install Drupal test site.
        $this->prepareEnvironment();
        $this->installDrupal();
        // Setup Mink.
        $this->initMink();
        // Set up the browser test output file.
        $this->initBrowserOutputFile();
        // Ensure that the test is not marked as risky because of no assertions. In
        // PHPUnit 6 tests that only make assertions using $this->assertSession()
        // can be marked as risky.
        $this->addToAssertionCount(1);
    }
    
    /**
     * {@inheritdoc}
     */
    public function __get(string $name) {
        if ($name === 'randomGenerator') {
            @trigger_error('Accessing the randomGenerator property is deprecated in drupal:10.2.0 and is removed from drupal:11.0.0. Use getRandomGenerator() instead. See https://www.drupal.org/node/3358445', E_USER_DEPRECATED);
            return $this->getRandomGenerator();
        }
    }
    
    /**
     * Sets up the root application path.
     */
    protected function setUpAppRoot() : void {
        if ($this->root === NULL) {
            $this->root = dirname(substr(__DIR__, 0, -strlen(__NAMESPACE__)), 2);
        }
    }
    
    /**
     * Ensures test files are deletable.
     *
     * Some tests chmod generated files to be read only. During
     * BrowserTestBase::cleanupEnvironment() and other cleanup operations,
     * these files need to get deleted too.
     *
     * @param string $path
     *   The file path.
     *
     * @see \Drupal\Core\File\FileSystemInterface::deleteRecursive()
     */
    public static function filePreDeleteCallback($path) {
        // When the webserver runs with the same system user as phpunit, we can
        // make read-only files writable again. If not, chmod will fail while the
        // file deletion still works if file permissions have been configured
        // correctly. Thus, we ignore any problems while running chmod.
        @chmod($path, 0700);
    }
    
    /**
     * Clean up the test environment.
     */
    protected function cleanupEnvironment() {
        // Remove all prefixed tables.
        $original_connection_info = Database::getConnectionInfo('simpletest_original_default');
        $original_prefix = $original_connection_info['default']['prefix'];
        $test_connection_info = Database::getConnectionInfo('default');
        $test_prefix = $test_connection_info['default']['prefix'];
        if ($original_prefix != $test_prefix) {
            $tables = Database::getConnection()->schema()
                ->findTables('%');
            foreach ($tables as $table) {
                if (Database::getConnection()->schema()
                    ->dropTable($table)) {
                    unset($tables[$table]);
                }
            }
        }
        // Delete test site directory.
        \Drupal::service('file_system')->deleteRecursive($this->siteDirectory, [
            $this,
            'filePreDeleteCallback',
        ]);
    }
    
    /**
     * {@inheritdoc}
     */
    protected function tearDown() : void {
        parent::tearDown();
        if ($this->container) {
            // Cleanup mock session started in DrupalKernel::preHandle().
            try {
                
                /** @var \Symfony\Component\HttpFoundation\Session\Session $session */
                $session = $this->container
                    ->get('request_stack')
                    ->getSession();
                $session->clear();
                $session->save();
            } catch (SessionNotFoundException) {
                @trigger_error('Pushing requests without a session onto the request_stack is deprecated in drupal:10.3.0 and an error will be thrown from drupal:11.0.0. See https://www.drupal.org/node/3337193', E_USER_DEPRECATED);
            }
        }
        // Destroy the testing kernel.
        if (isset($this->kernel)) {
            $this->cleanupEnvironment();
            $this->kernel
                ->shutdown();
        }
        // Ensure that internal logged in variable is reset.
        $this->loggedInUser = FALSE;
        if ($this->mink) {
            $this->mink
                ->stopSessions();
        }
        // Restore original shutdown callbacks.
        if (function_exists('drupal_register_shutdown_function')) {
            $callbacks =& drupal_register_shutdown_function();
            $callbacks = $this->originalShutdownCallbacks;
        }
    }
    
    /**
     * Returns Mink session.
     *
     * @param string $name
     *   (optional) Name of the session. Defaults to the active session.
     *
     * @return \Behat\Mink\Session
     *   The active Mink session object.
     */
    public function getSession($name = NULL) {
        return $this->mink
            ->getSession($name);
    }
    
    /**
     * Get session cookies from current session.
     *
     * @return \GuzzleHttp\Cookie\CookieJar
     *   A cookie jar with the current session.
     */
    protected function getSessionCookies() {
        $domain = parse_url($this->getUrl(), PHP_URL_HOST);
        $session_id = $this->getSession()
            ->getCookie($this->getSessionName());
        $cookies = CookieJar::fromArray([
            $this->getSessionName() => $session_id,
        ], $domain);
        return $cookies;
    }
    
    /**
     * Obtain the HTTP client for the system under test.
     *
     * Use this method for arbitrary HTTP requests to the site under test. For
     * most tests, you should not get the HTTP client and instead use navigation
     * methods such as drupalGet() and clickLink() in order to benefit from
     * assertions.
     *
     * Subclasses which substitute a different Mink driver should override this
     * method and provide a Guzzle client if the Mink driver provides one.
     *
     * @return \GuzzleHttp\ClientInterface
     *   The client with BrowserTestBase configuration.
     *
     * @throws \RuntimeException
     *   If the Mink driver does not support a Guzzle HTTP client, throw an
     *   exception.
     */
    protected function getHttpClient() {
        
        /** @var \Behat\Mink\Driver\DriverInterface $mink_driver */
        $mink_driver = $this->getSession()
            ->getDriver();
        if ($this->isTestUsingGuzzleClient()) {
            return $mink_driver->getClient()
                ->getClient();
        }
        throw new \RuntimeException('The Mink client type ' . get_class($mink_driver) . ' does not support getHttpClient().');
    }
    
    /**
     * Helper function to get the options of select field.
     *
     * @param \Behat\Mink\Element\NodeElement|string $select
     *   Name, ID, or Label of select field to assert.
     * @param \Behat\Mink\Element\Element $container
     *   (optional) Container element to check against. Defaults to current page.
     *
     * @return array
     *   Associative array of option keys and values.
     */
    protected function getOptions($select, ?Element $container = NULL) {
        if (is_string($select)) {
            $select = $this->assertSession()
                ->selectExists($select, $container);
        }
        $options = [];
        
        /** @var \Behat\Mink\Element\NodeElement $option */
        foreach ($select->findAll('xpath', '//option') as $option) {
            $label = $option->getText();
            $value = $option->getAttribute('value') ?: $label;
            $options[$value] = $label;
        }
        return $options;
    }
    
    /**
     * Installs Drupal into the test site.
     */
    public function installDrupal() {
        $this->initUserSession();
        $this->prepareSettings();
        $this->doInstall();
        $this->initSettings();
        $this->container = $container = $this->initKernel(\Drupal::request());
        $this->initConfig($container);
        $this->installDefaultThemeFromClassProperty($container);
        $this->installModulesFromClassProperty($container);
        // Clear the static cache so that subsequent cache invalidations will work
        // as expected.
        $this->container
            ->get('cache_tags.invalidator')
            ->resetChecksums();
        // Generate a route to prime the URL generator with the correct base URL.
        // @todo Remove in https://www.drupal.org/project/drupal/issues/3207896.
        Url::fromRoute('<front>')->setAbsolute()
            ->toString();
        // Explicitly call register() again on the container registered in \Drupal.
        // @todo This should already be called through
        //   DrupalKernel::prepareLegacyRequest() -> DrupalKernel::boot() but that
        //   appears to be calling a different container.
        $this->container
            ->get('stream_wrapper_manager')
            ->register();
    }
    
    /**
     * Prevents serializing any properties.
     *
     * Browser tests are run in a separate process. To do this PHPUnit creates a
     * script to run the test. If it fails, the test result object will contain a
     * stack trace which includes the test object. It will attempt to serialize
     * it. Returning an empty array prevents it from serializing anything it
     * should not.
     *
     * @return array
     *   An empty array.
     *
     * @see vendor/phpunit/phpunit/src/Util/PHP/Template/TestCaseMethod.tpl.dist
     */
    public function __sleep() {
        return [];
    }
    
    /**
     * Performs an xpath search on the contents of the internal browser.
     *
     * The search is relative to the root element (HTML tag normally) of the page.
     *
     * @param string $xpath
     *   The xpath string to use in the search.
     * @param array $arguments
     *   An array of arguments with keys in the form ':name' matching the
     *   placeholders in the query. The values may be either strings or numeric
     *   values.
     *
     * @return \Behat\Mink\Element\NodeElement[]
     *   The list of elements matching the xpath expression.
     */
    protected function xpath($xpath, array $arguments = []) {
        $xpath = $this->assertSession()
            ->buildXPathQuery($xpath, $arguments);
        return $this->getSession()
            ->getPage()
            ->findAll('xpath', $xpath);
    }
    
    /**
     * Configuration accessor for tests. Returns non-overridden configuration.
     *
     * @param string $name
     *   Configuration name.
     *
     * @return \Drupal\Core\Config\Config
     *   The configuration object with original configuration data.
     */
    protected function config($name) {
        return $this->container
            ->get('config.factory')
            ->getEditable($name);
    }
    
    /**
     * Gets the JavaScript drupalSettings variable for the currently-loaded page.
     *
     * @return array
     *   The JSON decoded drupalSettings value from the current page.
     */
    protected function getDrupalSettings() {
        $html = $this->getSession()
            ->getPage()
            ->getContent();
        if (preg_match('@<script type="application/json" data-drupal-selector="drupal-settings-json">([^<]*)</script>@', $html, $matches)) {
            $settings = Json::decode($matches[1]);
            if (isset($settings['ajaxPageState']['libraries'])) {
                $settings['ajaxPageState']['libraries'] = UrlHelper::uncompressQueryParameter($settings['ajaxPageState']['libraries']);
            }
            return $settings;
        }
        return [];
    }
    
    /**
     * Retrieves the current calling line in the class under test.
     *
     * @return array
     *   An associative array with keys 'file', 'line' and 'function'.
     */
    protected function getTestMethodCaller() {
        $backtrace = debug_backtrace();
        // Find the test class that has the test method.
        while ($caller = Error::getLastCaller($backtrace)) {
            // If we match PHPUnit's TestCase::runTest, then the previously processed
            // caller entry is where our test method sits.
            if (isset($last_caller) && isset($caller['function']) && $caller['function'] === 'PHPUnit\\Framework\\TestCase->runTest()') {
                // Return the last caller since that has to be the test class.
                $caller = $last_caller;
                break;
            }
            // If the test method is implemented by a test class's parent then the
            // class name of $this will not be part of the backtrace.
            // In that case we process the backtrace until the caller is not a
            // subclass of $this and return the previous caller.
            if (isset($last_caller) && (!isset($caller['class']) || !is_subclass_of($this, $caller['class']))) {
                // Return the last caller since that has to be the test class.
                $caller = $last_caller;
                break;
            }
            if (isset($caller['class']) && $caller['class'] === static::class) {
                break;
            }
            // Otherwise we have not reached our test class yet: save the last caller
            // and remove an element from to backtrace to process the next call.
            $last_caller = $caller;
            array_shift($backtrace);
        }
        return $caller;
    }
    
    /**
     * Transforms a nested array into a flat array suitable for submitForm().
     *
     * @param array $values
     *   A multi-dimensional form values array to convert.
     *
     * @return array
     *   The flattened $edit array suitable for BrowserTestBase::submitForm().
     */
    protected function translatePostValues(array $values) {
        $edit = [];
        // The easiest and most straightforward way to translate values suitable for
        // BrowserTestBase::submitForm() is to actually build the POST data
        // string and convert the resulting key/value pairs back into a flat array.
        $query = http_build_query($values);
        foreach (explode('&', $query) as $item) {
            [
                $key,
                $value,
            ] = explode('=', $item);
            $edit[urldecode($key)] = urldecode($value);
        }
        return $edit;
    }

}