public class Browser
extends java.lang.Object
Examples:
browser.click("Save");
clicks on a link or button labeled Save
browser.type("Username", "Jack");
enter the text Jack in the input field labeled Username
browser.select("language", "english");
selects the options english in the dropdown/list labeled language
HtmlElement firstTitle = browser.query(headline()).findFirst();
finds the first title element on the current page and saves themHtmlElements imagesLeftOfTitle = browser.query(image(), leftOf(title)).find();
finds all image elements left of the previously found titleElements can be searched by queries to get their values and text, and to interact with them. Search queries are case-sensitive.
Use click(String)
to search for elements with the specified name or label and click the best match.
Use type(String, String)
to search for input elements (usually <input>
or <textarea>
, but also
rich text editors used by many CMS, forums or blog applications) with the specified name or label, get the best match
and enter the given text.
Use choose(String, String)
to search for <select>
elements (usually a dropdown selection or a box with a list
of options) with the specified name or label, get the best match and select the given option from the list.
Use query(Predicate...)
to create a Query
instance and to search for HtmlElements
. Predicates can be arbitrarily combined.
The call of Query.find()
or Query.findFirst()
will return the result(s).
Found elements can be further interacted with, see HtmlElement
.
Query
,
HtmlElement
,
HtmlElements
Constructor and Description |
---|
Browser()
Starts new browser session.
|
Browser(java.lang.String url)
Starts new browser session.
|
Browser(java.lang.String url,
BrowserConfig config)
Starts new browser session with specified
BrowserConfig . |
Modifier and Type | Method and Description |
---|---|
HtmlElement |
checkToggle(java.lang.String checkable)
Searches for checkbox input field and toggles it.
|
HtmlElement |
choose(java.lang.String choosable,
java.lang.String option)
Searches for dropdown/list input field and selects the specified option.
|
HtmlElement |
chooseDate(java.lang.String datepicker,
org.joda.time.DateTime dateTime)
Searches for calendar/date picker input fields and selects the specified date.
|
HtmlElement |
click(java.lang.String clickable)
Searches for a clickable element with specified query string and clicks it.
|
void |
close()
Closes all browser windows and stops all browser interactions.
|
Browser |
css(java.lang.String styleDefinitions,
java.lang.Boolean flatImageFolder,
java.lang.Object... args)
Reads CSS from a string and injects it into the current web page.
|
Browser |
cssFromFile(java.lang.String stylesheetFile,
java.lang.Boolean flatImageFolder,
java.lang.Object... args)
Reads CSS from a file and injects it into the current web page.
|
Debug |
debug()
Debugging methods to highlight elements or pause the execution.
|
HtmlElement |
drag(java.lang.String elementToDrag,
java.lang.String elemenToDropOn)
Searches for a element with specified query string and drags it with the mouse to another element.
|
Frame |
frame()
Allows to focus page frames and iframes.
|
java.lang.String |
getCurrentUrl()
Gets URL of current page
|
java.lang.String |
getPageSource()
Gets HTML source code of current page
|
java.lang.String |
getScreenshotAsBase64() |
java.lang.String |
getScreenshotAsBase64(boolean withDataPrefix) |
java.awt.image.BufferedImage |
getScreenshotAsBufferedImage() |
byte[] |
getScreenshotAsByteArray() |
java.io.File |
getScreenshotAsFile() |
org.openqa.selenium.remote.RemoteWebDriver |
getWebDriver()
Gets underlying Selenium WebDriver instance.
|
History |
history()
Allows to interact with the browser history.
|
HtmlElement |
hover(java.lang.String clickable)
Searches for a element with specified query string and hovers it with the mouse.
|
JavaScriptResult |
javaScript(java.lang.String script,
java.lang.Object... args)
Loads JavaScript and evaluates it synchronously.
|
JavaScriptResult |
javaScriptAsync(java.lang.String script,
java.lang.Object... args)
Loads JavaScript and evaluates it asynchronously.
|
JavaScriptResult |
javaScriptFromFile(java.lang.String scriptFilename,
java.lang.Object... args)
Reads JavaScript from a file and evaluates it synchronously.
|
JavaScriptResult |
javaScriptFromFileAsync(java.lang.String scriptFilename,
java.lang.Object... args)
Reads JavaScript from a file and evaluates it asynchronously.
|
org.slf4j.Logger |
log()
Gets logger instance.
|
void |
openUrl(java.lang.String url)
Opens page with specified URL.
|
Query |
query(Predicate... predicates) |
HtmlElement |
submit(java.lang.String submittable)
Submits the form, which contains the given form element.
|
HtmlElement |
type(java.lang.String typable,
java.lang.String text)
Searches for element with specified query string and enters the text.
|
HtmlElement |
unchoose(java.lang.String choosable,
java.lang.String option)
Searches for dropdown/list input field and deselects the specified option.
|
WaitFor |
waitFor()
Allows to wait for the browser to finish specified tasks.
|
Window |
window()
Allows to interact with browser windows.
|
public Browser()
The default browser configuration is the use of Firefox 4 and can be overwritten by creating a default.properties file.
TODO explanation properties. For further customization see also Browser(String, BrowserConfig)
.
Each browser instance needs to be closed at the end of the program by calling the close()
method.
Use openUrl(String)
to open another URL in the browser.
close()
,
openUrl(String)
public Browser(java.lang.String url)
The default browser configuration is the use of Firefox 4 and can be overwritten by creating a default.properties file.
TODO explanation properties. For further customization see also Browser(String, BrowserConfig)
.
Each browser instance needs to be closed at the end of the program by calling the close()
method.
Use openUrl(String)
to open another URL in the browser.
url
- The URL to open, set to null to prevent loading a pageclose()
,
openUrl(String)
public Browser(java.lang.String url, BrowserConfig config)
BrowserConfig
. Opens the browser, loads the given URL and waits until it is ready.
Each browser instance needs to be closed at the end of the program by calling the close()
method.
Use openUrl(String)
to open another URL in the browser.
url
- The URL to open, set to null to prevent loading a pageconfig
- BrowserConfig instanceclose()
,
openUrl(String)
public void openUrl(java.lang.String url)
If there is more than one window open, the URL will be opened in current focused browser window.
url
- the URL to open, null
does not open a web pagepublic void close()
public History history()
public Window window()
public Frame frame()
public WaitFor waitFor()
public Debug debug()
public JavaScriptResult javaScript(java.lang.String script, java.lang.Object... args)
If needed, the jQuery library is automatically loaded.
Examples:
browser.javaScript("alert('info message');"); JavaScriptResult result = browser.javaScript("return jQuery('#content').html();");
script
- The script to runpublic JavaScriptResult javaScriptFromFile(java.lang.String scriptFilename, java.lang.Object... args)
The files need to be placed in the src/main/resources/js directory.
If needed, the jQuery library is automatically loaded.
scriptFilename
- The script to load (without the file extension .js)public JavaScriptResult javaScriptAsync(java.lang.String script, java.lang.Object... args)
If needed, the jQuery library is automatically loaded.
Examples:
browser.javaScriptAsync("alert('info message');"); JavaScriptResult result = browser.javaScriptAsync("return jQuery('#content').html();");
script
- The script to runpublic JavaScriptResult javaScriptFromFileAsync(java.lang.String scriptFilename, java.lang.Object... args)
The files need to be placed in the src/main/resources/js directory.
If needed, the jQuery library is automatically loaded.
scriptFilename
- The script to load (without the file extension .js)public Browser css(java.lang.String styleDefinitions, java.lang.Boolean flatImageFolder, java.lang.Object... args)
The image files need to be placed in the src/main/resources/images directory.
styleDefinitions
- the stylesheet definitionsflatImageFolder
- true if all images are in the same folder or false if the images are in the corresponding subfolderspublic Browser cssFromFile(java.lang.String stylesheetFile, java.lang.Boolean flatImageFolder, java.lang.Object... args)
The css files need to be placed in the src/main/resources/css directory.
The image files need to be placed in the src/main/resources/images directory.
stylesheetFile
- the stylesheet to load (without the file extension .css)flatImageFolder
- true if all images are in the same folder or false if the images are in the corresponding subfolderspublic HtmlElement click(java.lang.String clickable)
Example:
browser.click("Save");
clicks on a link or button labeled SaveDescription:
Elements having an attribute value or visible text containing the query string will
be added to the result set. The first result will be used for clicking. If you already have an
HtmlElement
instance use HtmlElement.click()
instead.
Note that if the page reloads after a click, all found HtmlElement
instances may lose their validity.
clickable
- element labelnull
if element could not be foundHtmlElement.click()
public HtmlElement hover(java.lang.String clickable)
Example:
browser.hover("News");
fires the "mouseover" event on the element labeled NewsDescription:
Elements having an attribute value or visible text containing the query string will
be added to the result set. The first result will be used for hovering. If you already have an
HtmlElement
instance use HtmlElement.hover()
instead.
clickable
- element which will be used for hovering with the mousenull
if element could not be foundHtmlElement.hover()
public HtmlElement drag(java.lang.String elementToDrag, java.lang.String elemenToDropOn)
Example:
browser.dragTo("product", "cart");
drags the element labeled Product to the
element labeled CartDescription:
Elements having an attribute value or visible text containing the query string will
be added to the result set. The first result will be used for dragging. If you already have an
HtmlElement
instance use HtmlElement.dragTo(HtmlElement)
instead.
elementToDrag
- source element label; this is going to be draggedelemenToDropOn
- target element label; the source element is dropped herenull
if element could not be foundHtmlElement.dragTo(HtmlElement)
public HtmlElement type(java.lang.String typable, java.lang.String text)
Example:
browser.type("location","New York").submit();
types in the text New York
in the input field named or labeled location and then submits the form which contains that element.Description:
Elements having an attribute value or visible text containing the query string will
be added to the result set. The first result will be used for typing in the text. If you already have an
HtmlElement
instance use HtmlElement.type(String)
instead. Use HtmlElement.submit()
on the returned object to submit the form.
typable
- the label of the input fieldtext
- the text to type inHtmlElement.submit()
the form,
or null
if element could not be foundHtmlElement.type(String)
public HtmlElement choose(java.lang.String choosable, java.lang.String option)
HtmlElement.submit()
on the returned object to submit the form.
Example:
browser.choose("language","english").submit();
selects the english option from the list
select field named or labeled language and then submits the form which contains that element.Description:
TODO Select description
choosable
- dropdown/select elementoption
- the label or value of the option to selectHtmlElement.submit()
the form,
or null
if element could not be foundpublic HtmlElement unchoose(java.lang.String choosable, java.lang.String option)
HtmlElement.submit()
on the returned object to submit the form.
Example:
browser.unchoose("language","english").submit();
deselects the english option from the list
select field named or labeled language and then submits the form which contains that element.Description:
TODO Select description
choosable
- dropdown/select elementoption
- the label or value of the option to deselectHtmlElement.submit()
the form,
or null
if element could not be foundpublic HtmlElement checkToggle(java.lang.String checkable)
HtmlElement.submit()
on the returned object to submit the form.
Example:
browser.checkToggle("newsletter").submit();
toggles the checkbox labeled newsletter.Description:
TODO Select description
checkable
- checkbox elementHtmlElement.submit()
the form,
or null
if element could not be foundpublic HtmlElement chooseDate(java.lang.String datepicker, org.joda.time.DateTime dateTime)
HtmlElement.submit()
on the returned object to submit the form.
Example:
browser.chooseDate("Arrival", new Date()).submit();
selects the specified date in the date picker
named or labeled Arrival and then submits the form which contains that element.Description:
TODO Select description
datepicker
- calendar/date picker elementdateTime
- the date to selectHtmlElement.submit()
the form,
or null
if element could not be foundpublic HtmlElement submit(java.lang.String submittable)
Example:
browser.submit("address");
submits the form which contains the form element labeled address.submittable
- form submit elementnull
if element could not be foundpublic java.io.File getScreenshotAsFile()
public byte[] getScreenshotAsByteArray()
public java.awt.image.BufferedImage getScreenshotAsBufferedImage() throws java.io.IOException
java.io.IOException
public java.lang.String getScreenshotAsBase64()
public java.lang.String getScreenshotAsBase64(boolean withDataPrefix)
public java.lang.String getCurrentUrl()
public java.lang.String getPageSource()
public org.slf4j.Logger log()
public org.openqa.selenium.remote.RemoteWebDriver getWebDriver()
The WebDriver
is internally used to do all interactions with the browser.
In general, it is not necessary to use this manually.