com.github.markusbernhardt.seleniumlibrary.SeleniumLibrary Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of robotframework-seleniumlibrary Show documentation

Java port of the Python based SeleniumLibrary for Robot Framework

There is a newer version: 4.0.0-alpha-2.0

Show newest version

package com.github.markusbernhardt.seleniumlibrary;

import java.io.File;
import java.util.ResourceBundle;

import javax.script.ScriptEngine;
import javax.script.ScriptEngineManager;
import javax.script.ScriptException;

import org.robotframework.javalib.annotation.Autowired;
import org.robotframework.javalib.library.AnnotationLibrary;

import com.github.markusbernhardt.seleniumlibrary.keywords.BrowserManagement;
import com.github.markusbernhardt.seleniumlibrary.keywords.Cookie;
import com.github.markusbernhardt.seleniumlibrary.keywords.Element;
import com.github.markusbernhardt.seleniumlibrary.keywords.FormElement;
import com.github.markusbernhardt.seleniumlibrary.keywords.JavaScript;
import com.github.markusbernhardt.seleniumlibrary.keywords.Logging;
import com.github.markusbernhardt.seleniumlibrary.keywords.RunOnFailure;
import com.github.markusbernhardt.seleniumlibrary.keywords.Screenshot;
import com.github.markusbernhardt.seleniumlibrary.keywords.SelectElement;
import com.github.markusbernhardt.seleniumlibrary.keywords.TableElement;
import com.github.markusbernhardt.seleniumlibrary.keywords.Waiting;
import com.github.markusbernhardt.seleniumlibrary.utils.Javadoc2Libdoc;

/**
 * SeleniumLibrary is a web testing library for the Robot Framework and was
 * originally written in Python. This is the Java port of the Selenium 2
 * (WebDriver) Python library for Robot Framework. It uses the Selenium 2
 * (WebDriver) libraries internally to control a web browser. See WebDriver for more
 * information on Selenium 2 and WebDriver. It runs tests in a real browser
 * instance and should work with most modern browsers and can be used with the
 * Jython interpreter or any other Java application.

 * 

 * Before running tests

 * Prior to running test cases using SeleniumLibrary, the library must be
 * imported into your Robot Framework test suite (see importing section), and
 * the `Open Browser` keyword must be used to open a browser to the desired
 * location.

 * 

 * Locating elements

 * All keywords in SeleniumLibrary that need to find an element on the page
 * take an locator argument.

 * 

 * Key attributes

 * By default, when a locator value is provided, it is matched against the key
 * attributes of the particular element type. The attributes id and
 * name are key attributes to all elements.

 * 

 * List of key attributes:
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * Element Type Key Attributes
A @id,@name,@href,text
IMG @id,@name,@src,@alt
INPUT @id,@name,@value,@src
BUTTON @id,@name,@value,text
* @id,@name
 * 

 * Example:
 * 
 * 
 * 
 * 
 * 
 * Click Element my_element
 * 

 * Locator strategies

 * It is also possible to specify the approach SeleniumLibrary should take to
 * find an element by specifying a locator strategy with a locator prefix.

 * 

 * Supported strategies are:
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * Strategy Example Description
identifier Click Element | identifier=my_element Matches by @id or @name attribute
id Click Element | id=my_element Matches by @id attribute
name Click Element | name=my_element Matches by @name attribute
xpath Click Element | xpath=//div[@id='my_element'] Matches by arbitrary XPath expression
dom Click Element | dom=document.images[56] Matches by arbitrary DOM expression
link Click Element | link=My Link Matches by the link text
css Click Element | css=div.my_class Matches by CSS selector
jquery Click Element | jquery=div.my_class Matches by jQuery/sizzle selector
sizzle Click Element | sizzle=div.my_class Matches by jQuery/sizzle selector
tag Click Element | tag=div Matches by HTML tag name
 * 

 * Locating tables

 * Table related keywords, such as `Table Should Contain`, work differently. By
 * default, when a table locator value is provided, it will search for a table
 * with the specified id attribute.

 * 

 * Example:

 * 
 * 
 * 
 * 
 * 
 * 
 * Table Should Contain my_table text
 * 

 * More complex table locator strategies:
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * Strategy Example Description
xpath Table Should Contain | xpath=//table/[@name="my_table"] | text Matches by arbitrary XPath expression
css Table Should Contain | css=table.my_class | text Matches by CSS selector
 * 

 * Custom location strategies

 * It is also possible to register custom location strategies. See `Add Location
 * Strategy` for details about custom location strategies.

 * 

 * Example:
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * Add Location Strategy custom return window.document.getElementById(arguments[0]);
Input Text custom=firstName Max
 * 

 * Timeouts

 * There are several Wait ... keywords that take timeout as an argument.
 * All of these timeout arguments are optional. The timeout used by all of them
 * can be set globally using the `Set Selenium Timeout keyword`.

 * 

 * All timeouts can be given as numbers considered seconds (e.g. 0.5 or 42) or
 * in Robot Framework's time syntax (e.g. '1.5 seconds' or '1 min 30 s'). See Time Format for details about the time syntax.

 * 

 * Log Level

 * There are several keywords that take timeout as an argument. All of
 * these timeout arguments are optional. The default is usually INFO.

 * 

 * List of log levels:
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * Log Level Description
DEBUG 
INFO 
HTML Same as INFO, but message is in HTML format
TRACE 
WARN 
 */
public class SeleniumLibrary extends AnnotationLibrary {

	/**
	 * The list of keyword patterns for the AnnotationLibrary
	 */
	public static final String KEYWORD_PATTERN = "com/github/markusbernhardt/seleniumlibrary/keywords/**/*.class";

	/**
	 * The javadoc to libdoc converter
	 */
	public static final Javadoc2Libdoc JAVADOC_2_LIBDOC = new Javadoc2Libdoc(SeleniumLibrary.class);

	/**
	 * The library documentation is written in HTML
	 */
	public static final String ROBOT_LIBRARY_DOC_FORMAT = "HTML";

	/**
	 * The scope of this library is global.
	 */
	public static final String ROBOT_LIBRARY_SCOPE = "GLOBAL";

	/**
	 * The actual version of this library. Loaded from maven project.
	 */
	public static final String ROBOT_LIBRARY_VERSION = loadRobotLibraryVersion();

	private static String loadRobotLibraryVersion() {
		try {
			return ResourceBundle.getBundle(SeleniumLibrary.class.getCanonicalName().replace(".", File.separator))
					.getString("version");
		} catch (RuntimeException e) {
			return "unknown";
		}
	}

	public SeleniumLibrary() {
		this("5.0");
	}

	public SeleniumLibrary(String timeout) {
		this(timeout, "0.0");
	}

	public SeleniumLibrary(String timeout, String implicitWait) {
		this(timeout, implicitWait, "Capture Page Screenshot");
	}

	/**
	 * SeleniumLibrary can be imported with optional arguments.

	 * 

	 * timeout is the default timeout used to wait for all waiting
	 * actions. It can be changed later with `Set Selenium Timeout`.

	 * 

	 * implicitWait is the implicit timeout that Selenium waits, when
	 * looking for elements. It can be changed later with `Set Selenium Implicit
	 * Wait`. See WebDriver: Advanced Usage of the SeleniumHQ documentation for
	 * details about WebDriver's implicit wait functionality.

	 * 

	 * runOnFailure specifies the name of a keyword (from any available
	 * libraries) to execute when a SeleniumLibrary keyword fails. By default
	 * `Capture Page Screenshot` will be used to take a screenshot of the
	 * current page. Using the value \"Nothing\" will disable this feature
	 * altogether. See `Register Keyword To Run On Failure` keyword for details
	 * about this functionality.

	 * 

	 * Examples:
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * Library SeleniumLibrary 
Library SeleniumLibrary 15 # Sets timeout to 15 seconds
Library SeleniumLibrary 0 5 # Sets timeout to 0 seconds and implicitWait to 5 seconds
Library SeleniumLibrary 0 5 Log Source # Sets timeout to 0 seconds, implicitWait to 5 seconds and runs `Log
	 * Source` on failure
Library SeleniumLibrary 0 5 Nothing # Sets timeout to 0 seconds, implicitWait to 5 seconds and does
	 * nothing on failure
	 * 
	 * @param timeout
	 *            Default=5.0. Optional custom timeout.
	 * @param implicitWait
	 *            Default=0.0. Optional custom implicit wait time.
	 * @param keywordToRunOnFailure
	 *            Default=Capture Page Screenshot. Optional custom keyword to
	 *            run on failure.
	 */
	public SeleniumLibrary(String timeout, String implicitWait, String keywordToRunOnFailure) {
		super();
		addKeywordPattern(KEYWORD_PATTERN);
		createKeywordFactory(); // => init annotations
		browserManagement.setSeleniumTimeout(timeout);
		browserManagement.setSeleniumImplicitWait(implicitWait);
		runOnFailure.registerKeywordToRunOnFailure(keywordToRunOnFailure);
	}

	// ##############################
	// Autowired References
	// ##############################

	/**
	 * Instantiated BrowserManagement keyword bean
	 */
	@Autowired
	protected BrowserManagement browserManagement;

	/**
	 * Instantiated Cookie keyword bean
	 */
	@Autowired
	protected Cookie cookie;

	/**
	 * Instantiated Element keyword bean
	 */
	@Autowired
	protected Element element;

	/**
	 * Instantiated FormElement keyword bean
	 */
	@Autowired
	protected FormElement formElement;

	/**
	 * Instantiated JavaScript keyword bean
	 */
	@Autowired
	protected JavaScript javaScript;

	/**
	 * Instantiated Logging keyword bean
	 */
	@Autowired
	protected Logging logging;

	/**
	 * Instantiated RunOnFailure keyword bean
	 */
	@Autowired
	protected RunOnFailure runOnFailure;

	/**
	 * Instantiated Screenshot keyword bean
	 */
	@Autowired
	protected Screenshot screenshot;

	/**
	 * Instantiated SelectElement keyword bean
	 */
	@Autowired
	protected SelectElement selectElement;

	/**
	 * Instantiated TableElement keyword bean
	 */
	@Autowired
	protected TableElement tableElement;

	/**
	 * Instantiated Waiting keyword bean
	 */
	@Autowired
	protected Waiting waiting;

	// ##############################
	// Getter / Setter
	// ##############################

	public BrowserManagement getBrowserManagement() {
		return browserManagement;
	}

	public Cookie getCookie() {
		return cookie;
	}

	public Element getElement() {
		return element;
	}

	public FormElement getFormElement() {
		return formElement;
	}

	public JavaScript getJavaScript() {
		return javaScript;
	}

	public Logging getLogging() {
		return logging;
	}

	public RunOnFailure getRunOnFailure() {
		return runOnFailure;
	}

	public Screenshot getScreenshot() {
		return screenshot;
	}

	public SelectElement getSelectElement() {
		return selectElement;
	}

	public TableElement getTableElement() {
		return tableElement;
	}

	public Waiting getWaiting() {
		return waiting;
	}

	// ##############################
	// Public Methods
	// ##############################

	@Override
	public Object runKeyword(String keywordName, Object[] args) {
		return super.runKeyword(keywordName, toStrings(args));
	}

	@Override
	public String getKeywordDocumentation(String keywordName) {
		String keywordDocumentation = JAVADOC_2_LIBDOC.getKeywordDocumentation(keywordName);
		if (keywordDocumentation == null) {
			try {
				return super.getKeywordDocumentation(keywordName);
			} catch (NullPointerException e) {
				return "";
			}
		}
		return keywordDocumentation;
	}

	/**
	 * Returns the currently active SeleniumLibrary instance.
	 * 
	 * @return the library instance
	 * @throws ScriptException - if error occurs in script
	 */
	public static SeleniumLibrary getLibraryInstance() throws ScriptException {
		ScriptEngine engine = new ScriptEngineManager().getEngineByName("python");
		engine.put("library", "SeleniumLibrary");
		engine.eval("from robot.libraries.BuiltIn import BuiltIn");
		engine.eval("instance = BuiltIn().get_library_instance(library)");
		return (SeleniumLibrary) engine.get("instance");
	}

	// ##############################
	// Internal Methods
	// ##############################

	/**
	 * Convert all arguments in the object array to string
	 * 
	 * @param args
	 *            array with object to convert to the return string
	 * @return the return string
	 */
	protected Object[] toStrings(Object[] args) {
		Object[] newArgs = new Object[args.length];
		for (int i = 0; i < newArgs.length; i++) {
			if (args[i] == null || args[i].getClass().isArray()) {
				newArgs[i] = args[i];
			} else {
				newArgs[i] = args[i].toString();
			}
		}
		return newArgs;
	}
}

Element Type	Key Attributes
A	@id,@name,@href,text
IMG	@id,@name,@src,@alt
INPUT	@id,@name,@value,@src
BUTTON	@id,@name,@value,text
*	@id,@name

Strategy	Example	Description
identifier	Click Element \| identifier=my_element	Matches by @id or @name attribute
id	Click Element \| id=my_element	Matches by @id attribute
name	Click Element \| name=my_element	Matches by @name attribute
xpath	Click Element \| xpath=//div[@id='my_element']	Matches by arbitrary XPath expression
dom	Click Element \| dom=document.images[56]	Matches by arbitrary DOM expression
link	Click Element \| link=My Link	Matches by the link text
css	Click Element \| css=div.my_class	Matches by CSS selector
jquery	Click Element \| jquery=div.my_class	Matches by jQuery/sizzle selector
sizzle	Click Element \| sizzle=div.my_class	Matches by jQuery/sizzle selector
tag	Click Element \| tag=div	Matches by HTML tag name

Add Location Strategy	custom	return window.document.getElementById(arguments[0]);
Input Text	custom=firstName	Max

Log Level	Description
DEBUG
INFO
HTML	Same as INFO, but message is in HTML format
TRACE
WARN

Library	SeleniumLibrary
Library	SeleniumLibrary	15			# Sets timeout to 15 seconds
Library	SeleniumLibrary	0	5		# Sets timeout to 0 seconds and implicitWait to 5 seconds
Library	SeleniumLibrary	0	5	Log Source	# Sets timeout to 0 seconds, implicitWait to 5 seconds and runs `Log * Source` on failure
Library	SeleniumLibrary	0	5	Nothing	# Sets timeout to 0 seconds, implicitWait to 5 seconds and does * nothing on failure