info.novatec.testit.webtester.browser.BrowserFactory Maven / Gradle / Ivy

package info.novatec.testit.webtester.browser;

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.remote.DesiredCapabilities;

import info.novatec.testit.webtester.browser.proxy.ProxyConfiguration;


/**
 * Implementations of this interface are used to initialize {@link WebDriver web
 * driver} instances and package them as {@link Browser browsers}.
 * 
 * The most important method of a browser factory is {@link #createBrowser()}.
 * It is used by all kinds of reflection based operations to initialize a
 * browser using all the defaults of the actual factory implementation.
 * For more flexibility the {@link #createBrowser(DesiredCapabilities)} method
 * can be used to create instances based on your desired capabilities while still setting
 * some common properties with a default implementation.
 * 

 * The difference between a browser factory and a {@link BrowserBuilder browser
 * builder} is in how they are used. Factories are used to initialize a
 * {@link WebDriver web driver} with a specific implementation and certain
 * capabilities and then packaging that driver as a browser using a builder.
 * Builders are used to wrap any web driver in a browser instance and set
 * certain service implementations needed for the browser abstraction to
 * function. In short:
 * 

 * Browser factory configures web driver and uses browser builder to
 * initialize browser
 * Browser builder configures browser (if needed with sensible default
 * services)
 * 
 * 
 * Here are some examples of how to initialize a browser using a browser
 * factory:
 * 

 * new BrowserFactoryImpl().createBrowser(); 

 * create web driver and browser with implemented defaults
 * 
 * new BrowserFactoryImpl().withProxyConfiguration(configuration).createBrowser();
 * 

 * create web driver and browser with specific {@link ProxyConfiguration proxy
 * configuration}
 * new BrowserFactoryImpl().createBrowser(webDriver); 

 * create browser using the given web driver instance
 * 
 *
 * @see #withProxyConfiguration(ProxyConfiguration)
 * @see WebDriver
 * @see Browser
 * @see BrowserBuilder
 * @since 2.0
 */
public interface BrowserFactory {

    /**
     * Creates a {@link Browser browser} using the {@link BrowserFactory
     * factory's} defaults.
     *
     * @return the created browser
     * @since 2.0
     */
    Browser createBrowser();

    /**
     * Creates a {@link Browser browser} with the given
     * {@link DesiredCapabilities desired capabilities} and the
     * {@link BrowserFactory factory's} defaults. As the name suggests these
     * capabilities might not actually be available in which case the
     * unavailable ones will be ignored.
     *
     * @param capabilities the desired capabilities.
     * @return the created browser
     * @since 2.0
     */
    Browser createBrowser(DesiredCapabilities capabilities);

    /**
     * Defines a {@link ProxyConfiguration proxy configuration} to use when
     * creating a {@link Browser browser} with this {@link BrowserFactory
     * factory}.
     * 
     * This method only takes effect if it is used before any of the
     * createBrowser(...) methods is called.
     *
     * @param configuration the proxy configuration
     * @return the same factory instance for fluent API
     * @since 2.0
     */
    BrowserFactory withProxyConfiguration(ProxyConfiguration configuration);

}