appium()-The event firing

原文地址：https://github.com/appium/java-client/blob/master/docs/The-event_firing.md

since 4.1.0

The purpose

This feature allows end user to organize the event logging on the client side. Also this feature may be useful in a binding with standard or custom reporting frameworks.//这个功能是用来组织客户端事件日志，便于分析测试细节和撰写测试报告。

The API

The API was designed the way which allows end user to select events (searching, navigation, exception throwing etc.) which should be listened to. It contains the following list of interfaces (new items may be added further)://有如下API。

• io.appium.java_client.events.api.Listener is the basic interface
• io.appium.java_client.events.api.general.AlertEventListener is for the listening to alerts
• io.appium.java_client.events.api.general.ElementEventListener is for the listening to actions related to elements
• io.appium.java_client.events.api.general.JavaScriptEventListener is for the listening to java script executing
• io.appium.java_client.events.api.general.ListensToException is for the listening to exceptions which are thrown
• io.appium.java_client.events.api.general.NavigationEventListener is for the listening to events related to navigation
• io.appium.java_client.events.api.general.SearchingEventListener is for the listening to events related to the searching.
• io.appium.java_client.events.api.general.WindowEventListener is for the listening to actions on a window
• io.appium.java_client.events.api.mobile.ContextEventListener is for the listening to the switching to mobile context
• io.appium.java_client.events.api.mobile.RotationEventListener is for the listening to screen rotation
• io.appium.java_client.events.api.general.AppiumWebDriverEventListener was added to provide the compatibility with user's implementation of org.openqa.selenium.support.events.WebDriverEventListener. Also it extends some interfaces above.

Briefly about the engine.

This is pretty similar solution as the org.openqa.selenium.support.events.EventFiringWebDriver of the Selenium project. You can read about this thing there The blog post.//这个功能来源于selenium，但克服了selenium中每次只能监听一个事件的缺点。

Here we were trying to improve existing drawbacks and restrictions using:

• API splitting, see above.

• the binding of some Spring framework engines with AspectJ.

How to use

It is easy.//使用方法：将driver和被监听的事件传入EventFiringWebDriverFactory。

import io.appium.java_client.events.api.general.AlertEventListener;

public class AlertListener implements AlertEventListener {
...
}

...
import io.appium.java_client.events.api.general.ElementEventListener;

public class ElementListener implements ElementEventListener {
...
}

//and so on
...
import io.appium.java_client.events.EventFiringWebDriverFactory;
import io.appium.java_client.events.api.Listener;
...

AndroidDriver driver = new AndroidDriver(parameters);
driver = EventFiringWebDriverFactory.getEventFiringWebDriver(driver, new AlertListener(), 
    new ElementListener());

//or 
AndroidDriver driver2 = new AndroidDriver(parameters); 
List<Listener> listeners = new ArrayList<>();
listeners.add(new AlertListener());
listeners.add(new ElementListener());
driver = EventFiringWebDriverFactory.getEventFiringWebDriver(driver2, listeners);

What if there are listeners which used everywhere by default.

In order to avoid the repeating actions an end user is free to do these things://高级用法：将监听事件作为一种自动启动的服务，不必显式地监听。这种用法来源于java自身的SPI。

• create folders /META-INF/services and put the file io.appium.java_client.events.api.Listener there. Please read aboutSPI.//创建/META-INF/services文件夹，把一个文件放到其中。

• define the list of default listeners at the io.appium.java_client.events.api.Listener//在文件中定义默认的被监听的事件。

And then it is enough//使用监听事件。

//and so on
...
import io.appium.java_client.events.EventFiringWebDriverFactory;
...

AndroidDriver driver = new AndroidDriver(parameters);
driver = EventFiringWebDriverFactory.getEventFiringWebDriver(driver);

If there are listeners defined externally when this collection is merged with default set of listeners.

How to reuse customized WebDriverEventListener

If an end user has their own org.openqa.selenium.support.events.WebDriverEventListener implementation then in order to make it compatible with this engine it is enough to do the following.//高级用法：扩展被监听的事件。

import org.openqa.selenium.support.events.WebDriverEventListener;
import io.appium.java_client.events.api.general.AppiumWebDriverEventListener;

public class UsersWebDriverEventListener implements WebDriverEventListener, AppiumWebDriverEventListener {
...
}

or just

import io.appium.java_client.events.api.general.AppiumWebDriverEventListener;

public class UsersWebDriverEventListener implements AppiumWebDriverEventListener {
...
}