com.mark59.scripting.selenium.interfaces.DriverFunctionsSeleniumBuilder Maven / Gradle / Ivy
/*
* Copyright 2019 Mark59.com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.mark59.scripting.selenium.interfaces;
import java.nio.file.Path;
import java.util.Map;
import org.openqa.selenium.MutableCapabilities;
import org.openqa.selenium.PageLoadStrategy;
import org.openqa.selenium.Proxy;
import org.openqa.selenium.UnexpectedAlertBehaviour;
import com.mark59.scripting.selenium.SeleniumAbstractJavaSamplerClient;
import com.mark59.scripting.selenium.driversimpl.DriverFunctionsSeleniumChromeBuilder;
import com.mark59.scripting.selenium.driversimpl.DriverFunctionsSeleniumFirefoxBuilder;
/**
* Base builder class for configuring Selenium web drivers.
*
* Specifies configurable capabilities that the SeleniumDriverFactory knows how to use.
*
Eg, for chrome a 'service builder' is created, selenium 'options' are set, which are used
* by the service during driver creation
*
* @see DriverFunctionsSeleniumChromeBuilder
* @see DriverFunctionsSeleniumFirefoxBuilder
*
* @author Michael Cohen
* @author Philip Webb
* Written: Australian Winter 2019
*/
public interface DriverFunctionsSeleniumBuilder {
/**
* Sets the path to the WebDriver executable that is being configured.
*
* @param driverPath driver path to the WebDriver executable
* @return this
*/
DriverFunctionsSeleniumBuilder setDriverExecutable(Path driverPath);
/**
* Sets whether or not the Selenium WebDriver will start in headless mode,
* meaning that no GUI browser will be used.
*
* By default, headless mode will be set to 'true' by the factory.
*
* @param isHeadless indicates if the driver should start in headless mode
* @return this
*/
DriverFunctionsSeleniumBuilder setHeadless(boolean isHeadless);
/**
* Sets the page load strategy to be used by the WebDriver
*
* Page load strategy determines when the WebDriver will consider a page "loaded"
*
*
* Possible page load strategies are:
*
* - normal : WebDriver will wait for the page load event to fire
* - eager : WebDriver will wait for DOMContentLoaded event to fire
* - none : WebDriver will wait for the initial html load to complete
*
*
*
* Not all load strategies are implemented for all WebDrivers. Therefore when setting the PAGE_LOAD_STRATEGY
* parameter for a selenium script, the values to use will be:
*
* - PageLoadStrategy.NORMAL.toString() - this is the default, or
*
- PageLoadStrategy.NONE.toString()
*
*
* It is recommended that the "normal" page load strategy be used in simple cases.
* For more advanced/difficult web pages,the "none" strategy will need to be paired with a check to verify a desired
* element has loaded (else it will likely return in just a few milliseconds).
*
*
* @see PageLoadStrategy
* @param strategy type of wait strategy the WebDriver will adopt
* @return this
*/
DriverFunctionsSeleniumBuilder setPageLoadStrategy(PageLoadStrategy strategy);
/**
* Sets the page load strategy used by the WebDriver to "none".
* @see #setPageLoadStrategy
* @return this
*/
DriverFunctionsSeleniumBuilder setPageLoadStrategyNone();
/**
* Sets the page load strategy used by the WebDriver to "normal". (current default)
* @see #setPageLoadStrategy
* @return this
*/
DriverFunctionsSeleniumBuilder setPageLoadStrategyNormal();
/**
* Caters for the direct setting of the browser size via script argument BROWSER_DIMENSIONS.
*
* The argument value needs to be two integers, comma separated, otherwise a default of 1920,1080 will be used.
*
* For example to set a browser width x height of 800 x 600 (which incidentally, is the Chrome Headless 'maximize' default value
* being overridden with 1920,1080 in Mark59 ) you specify:
*
800,600
*
* Note that --start-maximized is not available - as just noted you can use "800,600" if you want to achieve the same
* effect in headless mode
*
* @see org.openqa.selenium.chrome.ChromeOptions#addArguments(java.util.List)
* @see SeleniumAbstractJavaSamplerClient
* @see org.openqa.selenium.Dimension
*
* @param width of the browser
* @param height of the browser
* @return this
*/
DriverFunctionsSeleniumBuilder setSize(int width, int height);
/**
*
Overrides the proxy to be used by the selenium WebDriver, and can passed via the 'PROXY' parameter.
* The proxy settings need to be formatted as a list of comma-delimited key-value pairs,
* and are passed directly to the selenium's proxy class constructor (strings values only)
*
* For example, defining a proxy pac url:
*
proxyType=PAC,proxyAutoconfigUrl=http://myawesomecompany.corp/proxy.pac
*
* Another example. Defining a http / https(ssl) proxy via the proxy host name
*
httpProxy=http://myawesomecompany.corp:8080,sslProxy=http://myawesomecompany.corp:8080
* Note: for Chrome at time of writing server user/password entry is not catered for with http and ssl proxy server setup.
*
* Hint: To not use a proxy server and always make direct connections, use chrome option argument "--no-proxy-server" in the ADDITIONAL_OPTIONS
* parameter
* Hint: To reset the value to blank in the Java Request PROXY option in Jmeter (ie, no proxy override), just type a space into the PROXY value field.
*
* @param proxy comma delimited list of proxy settings for WebDriver
*
* @see org.openqa.selenium.Proxy
* @see #setAdditionalOptions(java.util.List)
* @see SeleniumAbstractJavaSamplerClient
* @return this
*/
DriverFunctionsSeleniumBuilder setProxy(Proxy proxy);
/**
* Action to take for an unexpected alert.
*
*
From a selenium script, the only implemented JMeter parameter is 'UNHANDLED_PROMPT_BEHAVIOUR'. With values are should be
* one of the text values (case ignored) of UnexpectedAlertBehaviour.
*
If an invalid string value that does not represent a UnexpectedAlertBehaviour enum string value is passed as the argument,
* UnexpectedAlertBehaviour.IGNORE is assumed.
*
*
Selenium script example:
* jmeterAdditionalParameters.put(SeleniumDriverFactory.UNHANDLED_PROMPT_BEHAVIOUR , UnexpectedAlertBehaviour.IGNORE.toString());
*
* @param behaviour an UnexpectedAlertBehaviourr
*
* @see org.openqa.selenium.UnexpectedAlertBehaviour
* @see #setAdditionalOptions(java.util.List)
* @see SeleniumAbstractJavaSamplerClient
* @return this
*/
DriverFunctionsSeleniumBuilder setUnhandledPromptBehaviour(UnexpectedAlertBehaviour behaviour);
/**
*
Caters for the direct setting of any additional driver options from the JMeter additional parameters.
* Intended for use with the Chrome Driver.
*
* The input string needs to be a comma delimited list for multiple options.
* For example, to set a proxy pac url and activate the disable extensions option, the "ADDITIONAL OPTIONS" parameter
* for the SeleniumAbstractJavaSamplerClient based test script can be entered as :
*
--proxy-pac-url=http://myawesomecompany.corp/proxy.pac,--disable-extensions
*
* (note that a proxy override can be set using the "PROXY" parameter, just shown here as an example)
*
*
Another example: to run Chrome in incognito mode and have DevTools open with the browser, you can set the "ADDITIONAL OPTIONS"
* parameter as :
*
--incognito,--auto-open-devtools-for-tabs
*
* At the time of writing the best sources for the list of available options are:
*
* -
* https://peter.sh/experiments/chromium-command-line-switches
* -
* https://chromium.googlesource.com/chromium/src/+/master/chrome/common/chrome_switches.cc
*
*
* @see org.openqa.selenium.chrome.ChromeOptions#addArguments(java.util.List)
* @see SeleniumAbstractJavaSamplerClient
*
* @param arguments options
* @return this
*/
DriverFunctionsSeleniumBuilder setAdditionalOptions(java.util.List arguments);
/**
*
* Only implemented for Firefox. Primary purpose is to redirect gekodriver's copious error logging off the console..
* From a selenium script, the only implemented JMeter parameter is 'WRITE_FFOX_BROWSER_LOGFILE'. Values are:
*
* - false : suppresses Firefox error logging (the default)
* - true : depending on log setting, logs may to written to the
* 'screenshot' log directory (for example as set via property mark59.screenshot.directory in the mark59.properties file).
*
* @param isWriteBrowserLogFile see above
* @return this
*/
DriverFunctionsSeleniumBuilder setWriteBrowserLogfile(boolean isWriteBrowserLogFile);
/**
* Sets the path to an alternate version of the target browser, such as a Chromium browser or a development
* version of Chrome.
*
* For example, if you have downloaded Chromium directly onto your C: drive on a Win machine, you would set
* the "OVERRIDE_PROPERTY_MARK59_BROWSER_EXECUTABLE" as :
*
C:/Chromium/Application/chrome.exe
*
* This over-rides the mark59 property mark59.browser.executable (if set).
*
If neither the "OVERRIDE_PROPERTY_MARK59_BROWSER_EXECUTABLE" JMeter parameter or
* mark59.browser.executable property are
* set, the default installation of the expected browser is assumed.
*
* @param browserExecutablePath executable path to the browser executable to be used (java.nio.file.Path)
* @return this
*/
DriverFunctionsSeleniumBuilder setAlternateBrowser(Path browserExecutablePath);
/**
* Sets whether or not the Selenium WebDriver will have performance logging turned on.
*
*
By default, WebDriver performance logging is turned off.
*
* @param isVerbose indicates if more detailed Webdriver performance logs are
* required, such as requests sent and received.
* @return this
*/
DriverFunctionsSeleniumBuildersetVerbosePerformanceLoggingLogging(boolean isVerbose);
/**
* Creates a Selenium web driver, returning it in a 'wrapper'.
* @param arguments an key value that my be need in the final creation of the selenium driver
* @return a class which extends com.mark59.core.DriverWrapper (eg a Selenium driver wrapper)
*
* @see com.mark59.core.interfaces.DriverFunctions
*/
DriverFunctionsSelenium build(Map arguments);
}