Browser (Groovy API Documentation for geb-core 0.10.0)

geb.Browser

The browser is the centre of Geb. It encapsulates a WebDriver implementation and references a Page object that provides access to the content.
Browser objects dynamically delegate all method calls and property read/writes that it doesn't implement to the current page instance via propertyMissing() and methodMissing().

Properties Summary

Properties
Type	Name and description
`WebDriver`	`augmentedDriver` If the driver is remote, this object allows access to its capabilities (users of Geb should not access this object, it is used internally).

Constructor Summary

Constructors
Constructor and description
`Browser ()` Create a new browser with a default configuration loader, loading the default configuration file.
`Browser (Configuration config)` Create a new browser backed by the given configuration.
`Browser (Map props, Configuration config)` Creates a new browser instance backed by the given configuration, then applies `props` as property overrides on the browser.

Methods Summary

Methods
Type	Name and description
`T`	`at(Class<T> pageType)` Checks if the browser is at the current page by running the at checker for this page type
`void`	`checkIfAtAnUnexpectedPage(Class<? extends Page>[] expectedPages)` Check if at one of the pages configured to be unexpected.
`void`	`cleanReportGroupDir()` Removes the directory returned by getReportGroupDir() from the filesystem if it exists.
`void`	`clearCookies()` Clears all cookies that the browser currently has.
`void`	`clearCookiesQuietly()` Clears all cookies that the browser currently has, suppressing any webdriver exceptions.
`void`	`close()` Closes the current driver window.
`protected NavigatorFactory`	`createNavigatorFactory()` Called to create the navigator factory, the first time it is requested.
`T`	`createPage(Class<T> pageType)` Creates a new instance of the given page type and initialises it.
`static Browser`	`drive(Closure script)` Creates a new browser object via the default constructor and executes the closure with the browser instance as the closure's delegate.
`static Browser`	`drive(Configuration conf, Closure script)` Creates a new browser with the configuration and executes the closure with the browser instance as the closure's delegate.
`static Browser`	`drive(Map browserProperties, Closure script)` Creates a new browser with the properties and executes the closure with the browser instance as the closure's delegate.
`static Browser`	`drive(Browser browser, Closure script)` Executes the closure with browser as its delegate.
`Set<String>`	`getAvailableWindows()` Retrieves all available windows
`String`	`getBaseUrl()` The url to resolve all relative urls against.
`Configuration`	`getConfig()` Provides access to the configuration object assoicated with this browser.
`String`	`getCurrentUrl()` Retrieves the current url
`String`	`getCurrentWindow()` Retrieves current window
`WebDriver`	`getDriver()` The driver implementation used to automate the actual browser.
`JavascriptInterface`	`getJs()` Returns a newly created javascript interface connected to this browser.
`NavigatorFactory`	`getNavigatorFactory()` Returns the factory that creates navigator instances for this browser.
`Page`	`getPage()` Provides access to the current page object.
`File`	`getReportGroupDir()` The directory that will be used for the method.
`void`	`go()` Sends the browser to the configured base url.
`void`	`go(Map params)` Sends the browser to the configured base url, appending `params` as query parameters.
`void`	`go(String url)` Sends the browser to the given url.
`void`	`go(Map params, String url)` Sends the browser to the given url.
`boolean`	`isAt(Class<? extends Page> pageType, boolean allowAtCheckWaiting = true)` Checks if the browser is at the given page by running the at checker for this page type, suppressing assertion errors.
`def`	`methodMissing(String name, def args)` Delegates the method call directly to the current page object.
`void`	`page(Class<? extends Page> pageClass)` Changes the browser's page to be an instance of the given class.
`void`	`page(Class<? extends Page>[] potentialPageClasses)` Changes the browser's page to be an instance of the first given type whose at checker returns a true value.
`void`	`page(Page page)` Sets this browser's page to be the given page after initializing it.
`def`	`propertyMissing(String name)` Delegates the property access directly to the current page object.
`def`	`propertyMissing(String name, def value)` Delegates the property assignment directly to the current page object.
`void`	`quit()` Quits the driver.
`void`	`registerPageChangeListener(PageChangeListener listener)` Allows new page change listeners to be registered with this browser.
`boolean`	`removePageChangeListener(PageChangeListener listener)` Removes the given page change listener.
`void`	`report(String label)` Writes a snapshot of the browser's state to the current getReportGroupDir() using the config's reporter.
`void`	`reportGroup(String path)` Sets the "group" for all subsequent reports, which is the relative path inside the reports dir that reports will be written to.
`void`	`reportGroup(Class clazz)` Sets the report group to be the full name of the class, replacing "." with "/".
`void`	`setBaseUrl(String baseUrl)` Changes the base url used for resolving relative urls.
`void`	`setDriver(WebDriver driver)` Set (or change) the webdriver underneath this browser.
`T`	`to(Class<T> pageType, Object[] args)` Sends the browser to the given page type's url, sets the page to a new instance of the given type and verifies the at checker of that page.
`T`	`to(Map params, Class<T> pageType)` Sends the browser to the given page type's url, sets the page to a new instance of the given type and verifies the at checker of that page.
`T`	`to(Map params, Class<T> pageType, Object[] args)` Sends the browser to the given page type's url, sets the page to a new instance of the given type and verifies the at checker of that page.
`T`	`via(Class<T> pageType, Object[] args)` Sends the browser to the given page type's url and sets the page to a new instance of the given type.
`T`	`via(Map params, Class<T> pageType)` Sends the browser to the given page type's url and sets the page to a new instance of the given type.
`T`	`via(Map params, Class<T> pageType, Object[] args)` Sends the browser to the given page type's url and sets the page to a new instance of the given type.
`def`	`withNewWindow(Map options, Closure windowOpeningBlock, Closure block)` Expects the first closure argument to open a new window and calls the second closure argument in the context of the newly opened window.
`def`	`withNewWindow(Closure windowOpeningBlock, Closure block)` Expects the first closure argument to open a new window and calls the second closure argument in the context of the newly opened window.
`def`	`withWindow(String window, Closure block)` Executes a closure within the context of a window specified by a name
`def`	`withWindow(Closure specification, Closure block)` Executes a closure within the context of all windows for which the specification closure returns groovy truth.
`def`	`withWindow(Map options, Closure specification, Closure block)` Executes a closure within the context of all windows for which the specification closure returns groovy truth.
`def`	`withWindow(Map options, String window, Closure block)` Executes a closure within the context of a window specified by a name

Inherited Methods Summary

Inherited Methods
Methods inherited from class	Name
`class Object`	`wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`

- Property Detail
  - @Lazy WebDriver augmentedDriver
    
    If the driver is remote, this object allows access to its capabilities (users of Geb should not access this object, it is used internally).
- Constructor Detail
  - Browser()
    
    Create a new browser with a default configuration loader, loading the default configuration file.
    See Also:
    ConfigurationLoader
  - Browser(Configuration config)
    
    Create a new browser backed by the given configuration.
    See Also:
    Configuration
  - Browser(Map props, Configuration config)
    
    Creates a new browser instance backed by the given configuration, then applies props as property overrides on the browser.
    See Also:
    Configuration
- Method Detail
  - T at(Class<T> pageType)
    
    Checks if the browser is at the current page by running the at checker for this page type A new instance of the page is created for the at check. If the at checker is successful, this browser object's page instance is updated to the new instance of the given page type and the new instance is returned. If the given pageType does not define an at checker, UndefinedAtCheckerException is thrown.
    If implicit assertions are enabled (which they are by default). This method will only ever return a page instance or throw an AssertionError
    Returns:
    a page instance of the given page type when the at checker succeeded or null otherwise (never null if implicit assertions are enabled)
  - void checkIfAtAnUnexpectedPage(Class<? extends Page>[] expectedPages)
    
    Check if at one of the pages configured to be unexpected.
    throws:
    UnexpectedPageException when at an unexpected page
    
    Parameters:
    expectedPages - allows to specify which of the unexpected pages to ignore for the check
  - void cleanReportGroupDir()
    
    Removes the directory returned by getReportGroupDir() from the filesystem if it exists.
  - void clearCookies()
    
    Clears all cookies that the browser currently has.
  - void clearCookiesQuietly()
    
    Clears all cookies that the browser currently has, suppressing any webdriver exceptions.
  - void close()
    
    Closes the current driver window.
    See Also:
    WebDriver.close
  - protected NavigatorFactory createNavigatorFactory()
    
    Called to create the navigator factory, the first time it is requested.
    Returns:
    The navigator factory
  - T createPage(Class<T> pageType)
    
    Creates a new instance of the given page type and initialises it.
    Returns:
    The newly created page instance
  - static Browser drive(Closure script)
    
    Creates a new browser object via the default constructor and executes the closure with the browser instance as the closure's delegate.
    Returns:
    the created browser
  - static Browser drive(Configuration conf, Closure script)
    
    Creates a new browser with the configuration and executes the closure with the browser instance as the closure's delegate.
    Returns:
    the created browser
  - static Browser drive(Map browserProperties, Closure script)
    
    Creates a new browser with the properties and executes the closure with the browser instance as the closure's delegate.
    Returns:
    the created browser
  - static Browser drive(Browser browser, Closure script)
    
    Executes the closure with browser as its delegate.
    Returns:
    browser
  - Set<String> getAvailableWindows()
    
    Retrieves all available windows
    See Also:
    WebDriver.getWindowHandles
  - String getBaseUrl()
    
    The url to resolve all relative urls against. Typically the root of the application or system Geb is interacting with.
    The base url is determined by the configuration.
    See Also:
    Configuration.getBaseUrl
  - Configuration getConfig()
    
    Provides access to the configuration object assoicated with this browser.
  - String getCurrentUrl()
    
    Retrieves the current url
    See Also:
    WebDriver.getCurrentUrl
  - String getCurrentWindow()
    
    Retrieves current window
    See Also:
    WebDriver.getWindowHandle
  - WebDriver getDriver()
    
    The driver implementation used to automate the actual browser.
    The driver implementation to use is determined by the configuration.
    See Also:
    Configuration.getDriver
  - JavascriptInterface getJs()
    
    Returns a newly created javascript interface connected to this browser.
  - NavigatorFactory getNavigatorFactory()
    
    Returns the factory that creates navigator instances for this browser.
    Returns:
    The navigator factory
  - Page getPage()
    
    Provides access to the current page object.
    All browser objects are created with a page type of Page initially.
  - File getReportGroupDir()
    
    The directory that will be used for the method.
    Uses the Configuration.getReportsDir for the base location for reports (throwing an exception if this is not set), and appending the current report group. The returned file object is guaranteed to exist on the filesystem.
    If the current report group is null, this method returns the same as config.reportsDir.
    See Also:
    reportGroup(java.lang.String)
    report(java.lang.String)
  - void go()
    
    Sends the browser to the configured base url.
  - void go(Map params)
    
    Sends the browser to the configured base url, appending params as query parameters.
  - void go(String url)
    
    Sends the browser to the given url. If it is relative it is resolved against the base url.
  - void go(Map params, String url)
    
    Sends the browser to the given url. If it is relative it is resolved against the base url.
  - boolean isAt(Class<? extends Page> pageType, boolean allowAtCheckWaiting = true)
    
    Checks if the browser is at the given page by running the at checker for this page type, suppressing assertion errors. If the at checker is successful, this browser object's page instance is updated the one the method is called with. If the given pageType does not define an at checker, UndefinedAtCheckerException is thrown. If the at check throws an AssertionError (as it will when implicit assertions are enabled) this method will suppress the exception and return false.
    Returns:
    true if browser is at the given page otherwise false
  - def methodMissing(String name, def args)
    
    Delegates the method call directly to the current page object.
  - void page(Class<? extends Page> pageClass)
    
    Changes the browser's page to be an instance of the given class.
    This method performs the following:
    - Create a new instance of the given class (which must be Page or a subclass thereof) and connect it to this browser object
    - Inform any registered page change listeners
    - Set the browser's page property to the created instance (if it is not already of this type)
      Note that it does not verify that the page matches the current content by running its at checker
    - void page(Class<? extends Page>[] potentialPageClasses)
      
      Changes the browser's page to be an instance of the first given type whose at checker returns a true value.
      This method performs the following:
      - Check if not at an unexpected page
      - For each given page type:
        
        Create a new instance of the class (which must be Page or a subclass thereof) and connect it to the browser object
        Test if the page represents the new instance by running its at checker
        If the page's at checker is successful:
        
        Inform any registered page change listeners
        Set the browser's page property to the instance (if it is not already of this type)
        Discard the rest of the potentials
        
        If the page's at checker is not successful:
        
        Try the next potential
        
        void page(Page page)
        
        Sets this browser's page to be the given page after initializing it.
        See Also:
        page(Class)
        
        def propertyMissing(String name)
        
        Delegates the property access directly to the current page object.
        
        def propertyMissing(String name, def value)
        
        Delegates the property assignment directly to the current page object.
        
        void quit()
        
        Quits the driver.
        See Also:
        WebDriver.quit
        
        void registerPageChangeListener(PageChangeListener listener)
        
        Allows new page change listeners to be registered with this browser.
        This method will immediately call the PageChangeListener.pageWillChange method on listener with the current page as the newPage argument and null for the oldPage argument.
        throws:
        geb.error.PageChangeListenerAlreadyRegisteredException if the listener is already registered.
        
        See Also:
        PageChangeListener
        
        boolean removePageChangeListener(PageChangeListener listener)
        
        Removes the given page change listener.
        Returns:
        whether or not the listener was actually registered or not.
        
        void report(String label)
        
        Writes a snapshot of the browser's state to the current getReportGroupDir() using the config's reporter.
        Parameters:
        label - The name for the report file (should not include a file extension)
        
        void reportGroup(String path)
        
        Sets the "group" for all subsequent reports, which is the relative path inside the reports dir that reports will be written to.
        Parameters:
        path - a relative path, or null to have reports written to the base reports dir
        
        void reportGroup(Class clazz)
        
        Sets the report group to be the full name of the class, replacing "." with "/".
        See Also:
        reportGroup(String)
        
        void setBaseUrl(String baseUrl)
        
        Changes the base url used for resolving relative urls.
        This method delegates to Configuration.setBaseUrl.
        
        void setDriver(WebDriver driver)
        
        Set (or change) the webdriver underneath this browser.
        This should only be called before making any requests as a means to override the driver instance that would be created from the configuration. Where possible, prefer using the configuration mechanism to specify the driver implementation to use.
        This method delegates to Configuration.setDriver.
        
        T to(Class<T> pageType, Object[] args)
        
        Sends the browser to the given page type's url, sets the page to a new instance of the given type and verifies the at checker of that page.
        Returns:
        a page instance of the passed page type when the at checker succeeded
        See Also:
        page(geb.Page)
        Page.to
        
        T to(Map params, Class<T> pageType)
        
        Sends the browser to the given page type's url, sets the page to a new instance of the given type and verifies the at checker of that page.
        Returns:
        a page instance of the passed page type when the at checker succeeded
        See Also:
        page(geb.Page)
        Page.to
        
        T to(Map params, Class<T> pageType, Object[] args)
        
        Sends the browser to the given page type's url, sets the page to a new instance of the given type and verifies the at checker of that page.
        Returns:
        a page instance of the passed page type when the at checker succeeded
        See Also:
        page(geb.Page)
        Page.to
        
        T via(Class<T> pageType, Object[] args)
        
        Sends the browser to the given page type's url and sets the page to a new instance of the given type.
        Returns:
        a page instance of the passed page type
        See Also:
        page(geb.Page)
        Page.to
        
        T via(Map params, Class<T> pageType)
        
        Sends the browser to the given page type's url and sets the page to a new instance of the given type.
        Returns:
        a page instance of the passed page type
        See Also:
        page(geb.Page)
        Page.to
        
        T via(Map params, Class<T> pageType, Object[] args)
        
        Sends the browser to the given page type's url and sets the page to a new instance of the given type.
        Returns:
        a page instance of the passed page type
        See Also:
        page(geb.Page)
        Page.to
        
        def withNewWindow(Map options, Closure windowOpeningBlock, Closure block)
        
        Expects the first closure argument to open a new window and calls the second closure argument in the context of the newly opened window. A map of options can also be specified that allows to close the new window, switch to a different page for closure executed in the context of the new window and also to wait for the window opening if the window opening is asynchronous.
        throws:
        geb.error.NoNewWindowException if the window opening closure doesn't open one or opens more than one new window
        
        Parameters:
        options - a map that can be used to pass additional options
        windowOpeningBlock - a closure that should open a new window
        block - closure to be executed in the new window context
        Returns:
        The return value of block
        
        def withNewWindow(Closure windowOpeningBlock, Closure block)
        
        Expects the first closure argument to open a new window and calls the second closure argument in the context of the newly opened window.
        throws:
        geb.error.NoNewWindowException if the window opening closure doesn't open one or opens more than one new window
        
        Parameters:
        windowOpeningBlock - a closure that should open a new window
        block - closure to be executed in the new window context
        Returns:
        The return value of block
        
        def withWindow(String window, Closure block)
        
        Executes a closure within the context of a window specified by a name
        Parameters:
        window - name of the window to use as context
        block - closure to be executed in the window context
        Returns:
        The return value of block
        
        def withWindow(Closure specification, Closure block)
        
        Executes a closure within the context of all windows for which the specification closure returns groovy truth.
        Parameters:
        specification - closure executed once in context of each window, if it returns groovy truth for a given window then also the block closure is executed in the context of that window
        block - closure to be executed in the window context
        Returns:
        The return value of block
        
        def withWindow(Map options, Closure specification, Closure block)
        
        Executes a closure within the context of all windows for which the specification closure returns groovy truth.
        Parameters:
        options - a map that can be used to pass additional options
        specification - closure executed once in context of each window, if it returns groovy truth for a given window then also the block closure is executed in the context of that window
        block - closure to be executed in the window context
        Returns:
        The return value of block
        
        def withWindow(Map options, String window, Closure block)
        
        Executes a closure within the context of a window specified by a name
        Parameters:
        options - a map that can be used to pass additional options
        window - name of the window to use as context
        block - closure to be executed in the window context
        Returns:
        The return value of block

Summary:
Property
Constructor
Method

| Detail:
Property
Constructor
Method

Groovy API Documentation for geb-core 0.10.0 - Licensed under the Apache License, Version 2.0 - http://www.gebish.org

[Groovy] Class Browser

Properties Summary

Constructor Summary

Methods Summary

Inherited Methods Summary

Property Detail

@Lazy WebDriver augmentedDriver

Constructor Detail

Browser()

Browser(Configuration config)

Browser(Map props, Configuration config)

Method Detail

T at(Class<T> pageType)

void checkIfAtAnUnexpectedPage(Class<? extends Page>[] expectedPages)

void cleanReportGroupDir()

void clearCookies()

void clearCookiesQuietly()

void close()

protected NavigatorFactory createNavigatorFactory()

T createPage(Class<T> pageType)

static Browser drive(Closure script)

static Browser drive(Configuration conf, Closure script)

static Browser drive(Map browserProperties, Closure script)

static Browser drive(Browser browser, Closure script)

Set<String> getAvailableWindows()

String getBaseUrl()

Configuration getConfig()

String getCurrentUrl()

String getCurrentWindow()

WebDriver getDriver()

JavascriptInterface getJs()

NavigatorFactory getNavigatorFactory()

Page getPage()

File getReportGroupDir()

void go()

void go(Map params)

void go(String url)

void go(Map params, String url)

boolean isAt(Class<? extends Page> pageType, boolean allowAtCheckWaiting = true)

def methodMissing(String name, def args)

void page(Class<? extends Page> pageClass)

void page(Class<? extends Page>[] potentialPageClasses)

void page(Page page)

def propertyMissing(String name)

def propertyMissing(String name, def value)

void quit()

void registerPageChangeListener(PageChangeListener listener)

boolean removePageChangeListener(PageChangeListener listener)

void report(String label)

void reportGroup(String path)

void reportGroup(Class clazz)

void setBaseUrl(String baseUrl)

void setDriver(WebDriver driver)

T to(Class<T> pageType, Object[] args)

T to(Map params, Class<T> pageType)

T to(Map params, Class<T> pageType, Object[] args)

T via(Class<T> pageType, Object[] args)

T via(Map params, Class<T> pageType)

T via(Map params, Class<T> pageType, Object[] args)

def withNewWindow(Map options, Closure windowOpeningBlock, Closure block)

def withNewWindow(Closure windowOpeningBlock, Closure block)

def withWindow(String window, Closure block)

def withWindow(Closure specification, Closure block)

def withWindow(Map options, Closure specification, Closure block)

def withWindow(Map options, String window, Closure block)