Package org.openqa.selenium.support.events

Class EventFiringDecorator<T extends WebDriver>

java.lang.Object
org.openqa.selenium.support.decorators.WebDriverDecorator<T>
org.openqa.selenium.support.events.EventFiringDecorator<T>
@Beta public class EventFiringDecorator<T extends WebDriver> extends WebDriverDecorator<T>
This decorator creates a wrapper around an arbitrary WebDriver instance that notifies registered listeners about events happening in this WebDriver and derived objects, such as WebElements and Alert.

Listeners should implement WebDriverListener. It supports three types of events:

  • "before"-event: a method is about to be called;
  • "after"-event: a method was called successfully and returned some result;
  • "error"-event: a method was called and thrown an exception.
To use this decorator you have to prepare a listener, create a decorator using this listener, decorate the original WebDriver instance with this decorator and use the new WebDriver instance created by the decorator instead of the original one: 

   WebDriver original = new FirefoxDriver();
   WebDriverListener listener = new MyListener();
   WebDriver decorated = new EventFiringDecorator(listener).decorate(original);
   decorated.get("http://example.com/");
   WebElement header = decorated.findElement(By.tagName("h1"));
   String headerText = header.getText();

The instance of WebDriver created by the decorator implements all the same interfaces as the original driver.

A listener can subscribe to "specific" or "generic" events (or both). A "specific" event correspond to a single specific method, a "generic" event correspond to any method called in a class or in any class.

To subscribe to a "specific" event a listener should implement a method with a name derived from the target method to be watched. The listener methods for "before"-events receive the parameters passed to the decorated method. The listener methods for "after"-events receive the parameters passed to the decorated method as well as the result returned by this method. 


   WebDriverListener listener = new WebDriverListener() {
     @Override
     public void beforeGet(WebDriver driver, String url) {
       logger.log("About to open a page %s", url);
     }
     @Override
     public void afterGetText(WebElement element, String result) {
       logger.log("Element %s has text '%s'", element, result);
     }
   };

To subscribe to a "generic" event a listener should implement a method with a name derived from the class to be watched: 


   WebDriverListener listener = new WebDriverListener() {
     @Override
     public void beforeAnyWebElementCall(WebElement element, Method method, Object[] args) {
       logger.log("About to call a method %s in element %s with parameters %s",
                  method, element, args);
     }
     @Override
     public void afterAnyWebElementCall(WebElement element, Method method, Object[] args, Object result) {
       logger.log("Method %s called in element %s with parameters %s returned %s",
                  method, element, args, result);
     }
   };

There are also listener methods for "super-generic" events: 


   WebDriverListener listener = new WebDriverListener() {
     @Override
     public void beforeAnyCall(Object target, Method method, Object[] args) {
       logger.log("About to call a method %s in %s with parameters %s",
                  method, target, args);
     }
     @Override
     public void afterAnyCall(Object target, Method method, Object[] args, Object result) {
       logger.log("Method %s called in %s with parameters %s returned %s",
                  method, target, args, result);
     }
   };

A listener can subscribe to both "specific" and "generic" events at the same time. In this case "before"-events are fired in order from the most generic to the most specific, and "after"-events are fired in the opposite order, for example: 


   beforeAnyCall
   beforeAnyWebDriverCall
   beforeGet
   // the actual call to the decorated method here
   afterGet
   afterAnyWebDriverCall
   afterAnyCall

One of the most obvious use of this decorator is logging. But it can be used to modify behavior of the original driver to some extent because listener methods are executed in the same thread as the original driver methods.

For example, a listener can be used to slow down execution for demonstration purposes, just make a listener that adds a pause before some operations: 


   WebDriverListener listener = new WebDriverListener() {
     @Override
     public void beforeClick(WebElement element) {
       try {
         Thread.sleep(3000);
       } catch (InterruptedException e) {
         Thread.currentThread().interrupt();
       }
     }
   };

Just be careful to not block the current thread in a listener method!

Listeners can't affect driver behavior too much. They can't throw any exceptions (they can, but the decorator suppresses these exceptions), can't prevent execution of the decorated methods, can't modify parameters and results of the methods.

Decorators that modify the behaviour of the underlying drivers should be implemented by extending WebDriverDecorator, not by creating sophisticated listeners.