- Notifications
You must be signed in to change notification settings - Fork849
Chrome
This page covers specifics of using php-webdriver with Chrome/Chromium browser.
First you need to install Chrome / Chromium browser. However this is not enough, as each supported browser also needs itsbrowser driver, in this case it isChromeDriver. Browser driver is a binary file which enables the browser to be controlled using WebDriver protocol.
To use ChromeDriver, you will need todownloadchromedriver/chromedriver.exe executable. Make sure the path tochromedriver/chromedriver.exe is in your system PATH, so that you can easily start it. See officialSelenium documentation covering PATH setup.
ℹ️ Chromedriver may be available in some Linux distributions (for example aschromium-chromedriver package in Ubuntu), so you can install the latest version using your system package manager.
As with other browsers, there are multiple ways how to start ChromeDriver instance, each suitable for different scenario.
In this case php-webdriver takes care of starting and setting up chromedriver. This is suitable for simple cases, when you run the browser locally on your computer.
If you installed chromedriver in your system PATH, you can just start it like this:
$driver = ChromeDriver::start();$driver->get('https://google.com');
When ChromeDriver is installed elsewhere, define path to chromedriver executable usingWEBDRIVER_CHROME_DRIVER environment variable:
putenv('WEBDRIVER_CHROME_DRIVER=/path/to/chromedriver');$driver = ChromeDriver::start();
or you can define the environment variable before starting the PHP script:
$export WEBDRIVER_CHROME_DRIVER=/path/to/chromedriver$ php my-test.php// my-test.php$driver = ChromeDriver::start();// ... your code// Don't forget to always call quit() at the end so that the chromedriver process is terminated$driver->quit();
In this case you start chromedriver instance by yourself. It must be kept running while you start your tests. This scenario is suitable when you want to adjust the way chromedriver is started (for example the port number) or when you want to define the browser using `DesiredCapabilities object.
$ chromedriver --port=4444# or chromedriver.exe on WindowsNow start your PHP script in another terminal window:
// my-test.php$serverUrl ='http://localhost:4444';// if you don't start chromedriver with "--port=4444" as above, default port will be 9515$driver = RemoteWebDriver::create($serverUrl, DesiredCapabilities::chrome());
$ php my-test.php
If you want to run your browser instances remotely (for example as a grid on CI server) or you want to start specific version of browser/Selenium in Docker, seeSelenium server wiki page.
ChromeOptions is class managing additional capabilities specific to ChromeDriver. As such, those options are relevant only for Chromium-based browsers. The class has convenient methods for setting ChromeDriver-specific capabilities.
Full documentation of available ChromeOptions is availableofficial ChromeDriver homepage.
See below for examples how to set and use ChromeOptions in php-webdriver:
// Create an instance of ChromeOptions:$chromeOptions =newChromeOptions();// Configure $chromeOptions, see examples bellow:$chromeOptions->addArguments(...);// Create $capabilities and add configuration from ChromeOptions$capabilities = DesiredCapabilities::chrome();$capabilities->setCapability(ChromeOptions::CAPABILITY_W3C,$chromeOptions);// Start the browser with $capabilities// A) When using RemoteWebDriver::create()$driver = RemoteWebDriver::create($serverUrl,$capabilities);// B) When using ChromeDriver::start to start local Chromedriver$driver = ChromeDriver::start($capabilities);
$chromeOptions->setBinary('/home/user/Downloads/my_chrome_binary');
Add command-line arguments to use when starting Chrome usingaddArguments() .
Seefull list of Chrome arguments.
$chromeOptions->addArguments(['--headless']);
Since Chromedriver 139 in headless mode use:
$chromeOptions->addArguments(['--screen-info={1024x768}']);
SeeChromium docs for more information.
For non-headles Chromedriver:
$chromeOptions->addArguments(['--window-size=1024,768']);
$chromeOptions->addArguments(['--start-maximized']);
// Load extension from crx file$chromeOptions->addExtensions(['/path/to/chrome/extension1.crx','/path/to/chrome/extension2.crx',]);// Load base-64 extension from string$chromeOptions->addEncodedExtensions([$base64EncodedExtension]);
Other options, not exposed via ChromeOptions, could be set usingsetExperimentalOption().
SeeChromeDriver documentation for list of all options.
// Set profile preferences// Please note most `prefs` are not supported with Chrome in headless mode, see https://bugs.chromium.org/p/chromium/issues/detail?id=775911$chromeOptions->setExperimentalOption('prefs', ['enable_referrers' =>false,'intl.accept_languages' =>'cs,cs-CZ,en']);// Set other chrome-capability$chromeOptions->setExperimentalOption('excludeSwitches', ['disable-popup-blocking']);
Using php-webdriver, you can also execute commands fromChrome DevTools protocol.
This may be quite useful in case you need some simple Chrome quirks (like changing user agent, manipulating geolocation etc.),and you still want all features and benefits of Selenium and WebDriver.
Because CDP commands are executed on top of WebDriver HTTP protocol, it does not provide the benefits of CDP controldirectly via WebSockets (for example binding to CDP events). This is possible usingdedicated libraries, but this on the other hand works only with local Chrome and have other limitations.
$driver = ChromeDriver::start();$devTools =$driver->getDevTools();// returns ChromeDevToolsDriver instance
$driver = RemoteWebDriver::create($serverUrl, DesiredCapabilities::chrome());$devTools =newChromeDevToolsDriver($driver);
WithChromeDevToolsDriver instance in$devTools variable, you can execute various CDP commands.
See alsoofficial documentation.
$devTools->execute('Performance.enable');$metrics =$devTools->execute('Performance.getMetrics');
$coordinates = ['latitude' =>50.1028,'longitude' =>14.4566,'accuracy' =>1,];$devTools->execute('Emulation.setGeolocationOverride',$coordinates);$driver->get(/* URL of webpage which uses geolocation */);
Specifies whether to always send extra HTTP headers with the requests from this page.
$devTools->execute('Network.enable');$devTools->execute('Network.setExtraHTTPHeaders', ['headers' => (object) ['My-Header' =>'My-Value']]);// Following requests will include your additional headers:$driver->get(/* URL */);
Override browser user agent with the given string.
$devTools->execute('Network.setUserAgentOverride', ['userAgent' =>'Mozilla/5.0 (X11; Linux x86_64; rv:83.0) Gecko/20100101 Firefox/83.0']);