net.sf.sahi.client
Class Browser

java.lang.Object
  net.sf.sahi.client.BrowserElements
      net.sf.sahi.client.Browser

public class Browser
extends BrowserElements

Browser is the main driver class for Sahi.
It performs various actions on the browser and is also a factory for ElementStubs which are a representation of various elements on the browser DOM.
A Browser instance is associated with a specific session on the Sahi proxy.

Eg.

String sahiBasePath = "D:\\path\\to\\sahi_dir";
Sting userDataDirectory = "D:\\path\\to\\userdata_dir"; // userdata_dir is in sahiBasePath/userdata by default

net.sf.sahi.config.Configuration.initJava(sahiBasePath, userDataDirectory);

Browser browser = new Browser()
String browserPath = "C:\\Program Files\\Internet Explorer\\iexplore.exe";
String browserProcessName = "iexplore.exe";
String browserOption = "-noframemerging -extoff"; // Set to "-noframemerging -extoff" for IE 8, "" for IE 7

browser = new Browser(browserPath, browserProcessName, browserOption);          
browser.open();
browser.navigateTo("http://www.google.com");
browser.textbox("q").setValue("sahi forums");
browser.submit("Google Search").click();
browser.link("Sahi - Web Automation and Test Tool").click();            
browser.link("Login").click();
assertTrue(browser.textbox("req_username").exists());

browser.close();
 
 
 

Constructor Summary

Browser()

Browser(java.lang.String browserName)
Constructs a Browser object and associates it with a session on Sahi Proxy

Browser(java.lang.String browserName, java.lang.String host, int port)

Browser(java.lang.String browserPath, java.lang.String browserProcessName, java.lang.String browserOption)
Constructs a Browser object and associates it with a session on Sahi Proxy

Browser(java.lang.String browserPath, java.lang.String browserProcessName, java.lang.String browserOption, java.lang.String host, int port)
Constructs a Browser object and associates it with a session on Sahi Proxy

Method Summary

void	addURLMock(java.lang.String urlPattern) Force Sahi to return a canned response for specific URL patterns The response is found in sahi/htdocs/spr/simpleMock.htm and can be modified
void	addURLMock(java.lang.String urlPattern, java.lang.String responseClass_method) Force Sahi to return a dynamic response returned by responseClass.methodName
void	check(ElementStub element) Checks the given checkbox or radio only if it is unchecked.
boolean	checked(ElementStub el) Returns true if the element is checked.
void	choose(ElementStub elementStub, java.lang.String[] values, boolean append) Chooses the given options in a multi select box (<select> tag).
void	choose(ElementStub elementStub, java.lang.String value, boolean append) Chooses the given option in a select box (<select> tag).
void	clearLastAlert() Clears the lastAlert message
void	clearLastConfirm() Clears the lastConfirm message
void	clearLastDownloadedFileName() Resets the lastDownloadedFileName to null
void	clearLastPrompt() Clears the lastPrompt message
void	click(ElementStub element) Clicks the given element
void	close() Closes the browser instance.
boolean	containsHTML(ElementStub el, java.lang.String html) Returns true if the element's innerHTML contains the input html
boolean	containsText(ElementStub el, java.lang.String text) Returns true if the element contains the input text
Browser	domain(java.lang.String domainName) Represents a portion of the page which is from a different domain.
void	doubleClick(ElementStub element) Double clicks the given element
void	dragDrop(ElementStub dragElement, ElementStub dropElement) Simulates a drag and drop event
void	execute(java.lang.String step) Executes any javascript on the browser.
void	executeStep(java.lang.String step)
boolean	exists(ElementStub el) Returns true if the element exists on the browser Retries a few times if the return value is false.
boolean	exists(ElementStub el, boolean optimistic) Returns true if the element exists on the browser Retries a few times if optimistic is false.
void	expectConfirm(java.lang.String message, boolean input) Sets the input value of a confirm dialog with given message. This needs to be set before a confirm is expected. Prompts are generated in javascript via window.confirm(message)
void	expectPrompt(java.lang.String message, java.lang.String input) Sets the input value of a prompt dialog with given message. This needs to be set before a prompt is expected. Prompts are generated in javascript via window.prompt(message)
java.lang.String	fetch(ElementStub el) Fetches the string value of an element stub by performing an eval on the browser
java.lang.String	fetch(java.lang.String expression) Fetches the value of any DOM property
void	focus(ElementStub element) Brings focus on the element.
java.lang.String[]	getRecordedSteps() Gets the recorded steps from the last time getRecordedSteps() was called.
java.lang.String	getSelectedText(ElementStub el) Returns the selected text visible in a select box (<select> tag)
java.lang.String	getText(ElementStub el) Returns the inner text of given element from the browser
java.lang.String	getValue(ElementStub el) Returns the value of given form element from the browser
boolean	isChrome() Checks for Google Chrome browser
boolean	isFF() Checks for Firefox browser
boolean	isFirefox() Checks for Firefox browser
boolean	isIE() Checks for Internet Explorer browser
boolean	isOpera() Checks for Opera browser
boolean	isSafari() Checks for Safari browser
boolean	isVisible(ElementStub el) Returns true if the element is visible on the browser
boolean	isVisible(ElementStub el, boolean optimistic) Returns true if the element is visible on the browser Retries a few times if optimistic is false.
void	kill() Kills the browser instance
java.lang.String	lastAlert() Returns the last alert message from browser Alert messages are generated via window.alert(message) in javascript.
java.lang.String	lastConfirm() Returns the last confirm message from browser Confirm messages are generated via window.confirm(message) in javascript.
java.lang.String	lastDownloadedFileName() Sahi automatically downloads files into sahi/userdata/temp/download directory. If a file was downloaded as a result of a click, its fileName will be accessible for assertion
java.lang.String	lastPrompt() Returns the last prompt message from browser Alert messages are generated via window.prompt(message) in javascript.
void	mouseOver(ElementStub link) Simulates a mouse over on the given element
void	navigateTo(java.lang.String url) Navigates to the given URL
void	navigateTo(java.lang.String url, boolean forceReload) Navigates to the given URL
void	open() Opens a browser instance and associates with a session on Sahi proxy.
Browser	popup(java.lang.String popupName) Represents a popup window.
void	removeFocus(ElementStub element) Removes focus from the element.
void	removeURLMock(java.lang.String urlPattern) Removes any mocks associated with given pattern
void	restartPlayback() Re-initializes proxy for playback if proxy is restarted. Should be invoked if proxy is started as a different process and needs a restart.
void	rightClick(ElementStub element) Right clicks the given element
void	rteWrite(ElementStub rte, java.lang.String value) Sets the value in a Rich Text Editor (RTE)
void	saveDownloadedAs(java.lang.String newFilePath) Saves the last downloaded file to required location. Can be used to save file to some location and then verify contents by reading it.
java.lang.String	sessionId()
void	setBrowserJS(java.lang.String browserJS) Allows given javascript to be injected into the browser. Custom functions or stubbed functions can be passed through this The given javascript will be available to every web page in this session Equivalent to adding <browser> blocks in Sahi Script Eg. browser.setBrowserJS("function myFinderFn(i){return document.links[i];}"); // The above code defines a function myFinderFn, which will be available on each page of the application. browser.setBrowserJS("function checkFileFieldIsPopulated(){return true}"); // The above code will redefine checkFileFieldIsPopulated function so that it will always return true
void	setFile(ElementStub textbox, java.lang.String value) Sets the file to be posted to the server via a file input field.
void	setSessionId(java.lang.String sessionId)
void	setSpeed(int interval) Sets the speed of playback. Some applications do not trigger AJAX requests on response to events, but use a small delay before execution. It is useful to tweak this parameter (eg.
void	setValue(ElementStub textbox, java.lang.String value) Sets the value in a form element
void	startRecording() Starts recording.
void	stopRecording() Stops recording.
java.lang.String	style(ElementStub el, java.lang.String attribute) Returns the computed css style
java.lang.String	title()
void	uncheck(ElementStub element) Unchecks the given checkbox only if it is checked.
void	waitFor(BrowserCondition condition, int timeout) Waits till the condition is satisfied or till timeout
void	waitFor(long timeout) Waits till timeout milliseconds

Methods inherited from class net.sf.sahi.client.BrowserElements

accessor, area, blockquote, bold, button, byClassName, byId, bySeleniumLocator, byText, byXPath, cell, checkbox, code, cookie, div, emphasis, file, heading1, heading2, heading3, heading4, heading5, heading6, hidden, iframe, image, imageSubmitButton, italic, label, link, list, listItem, map, option, parentCell, parentNode, parentRow, parentTable, password, position, preformatted, radio, reset, row, rte, select, span, spandiv, strong, submit, table, tableHeader, textarea, textbox, xy

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Browser

public Browser(java.lang.String browserName)

Constructs a Browser object and associates it with a session on Sahi Proxy

Parameters:

browserName - - Name of the browser as it is in browser_types.xml

Browser

public Browser(java.lang.String browserPath,
               java.lang.String browserProcessName,
               java.lang.String browserOption)

Constructs a Browser object and associates it with a session on Sahi Proxy

Parameters:

browserPath - The browser executable path

browserProcessName - The process name to look for to run a kill command

browserOption - Any browser options. Leave blank if not required.

Browser

public Browser(java.lang.String browserPath,
               java.lang.String browserProcessName,
               java.lang.String browserOption,
               java.lang.String host,
               int port)

Constructs a Browser object and associates it with a session on Sahi Proxy

Parameters:

browserPath - The browser executable path

browserProcessName - The process name to look for to run a kill command

browserOption - Any browser options. Leave blank if not required.

Browser

public Browser(java.lang.String browserName,
               java.lang.String host,
               int port)

Browser

public Browser()

Method Detail

restartPlayback

public void restartPlayback()

Re-initializes proxy for playback if proxy is restarted.
Should be invoked if proxy is started as a different process and needs a restart.
For NTLM/Windows authentication, java stores the first supplied valid
credentials. To logout of such a system, the proxy needs to be restarted
and then browser.restartPlayback() needs to be called.

navigateTo

public void navigateTo(java.lang.String url)
                throws ExecutionException

Navigates to the given URL

Parameters:

url -

Throws:

ExecutionException

navigateTo

public void navigateTo(java.lang.String url,
                       boolean forceReload)
                throws ExecutionException

Navigates to the given URL

Parameters:

url -

forceReload - boolean forces reload

Throws:

ExecutionException

execute

public void execute(java.lang.String step)
             throws ExecutionException

Executes any javascript on the browser.

Parameters:

step -

Throws:

ExecutionException

executeStep

public void executeStep(java.lang.String step)
                 throws ExecutionException

Throws:

ExecutionException

open

public void open()

Opens a browser instance and associates with a session on Sahi proxy.

close

public void close()

Closes the browser instance. If called on a popup it works

kill

public void kill()

Kills the browser instance

setValue

public void setValue(ElementStub textbox,
                     java.lang.String value)
              throws ExecutionException

Sets the value in a form element

Parameters:

textbox -

value -

Throws:

ExecutionException

setFile

public void setFile(ElementStub textbox,
                    java.lang.String value)
             throws ExecutionException

Sets the file to be posted to the server via a file input field. This method instructs the proxy to inject the file contents directly in the request. The browser's input field will not be populated, though data will be submitted.

Parameters:

elementStub -

value -

Throws:

ExecutionException

click

public void click(ElementStub element)
           throws ExecutionException

Clicks the given element

Parameters:

element -

Throws:

ExecutionException

doubleClick

public void doubleClick(ElementStub element)
                 throws ExecutionException

Double clicks the given element

Parameters:

element -

Throws:

ExecutionException

rightClick

public void rightClick(ElementStub element)
                throws ExecutionException

Right clicks the given element

Parameters:

element -

Throws:

ExecutionException

check

public void check(ElementStub element)
           throws ExecutionException

Checks the given checkbox or radio only if it is unchecked.

Parameters:

element -

Throws:

ExecutionException

uncheck

public void uncheck(ElementStub element)
             throws ExecutionException

Unchecks the given checkbox only if it is checked.

Parameters:

element -

Throws:

ExecutionException

focus

public void focus(ElementStub element)
           throws ExecutionException

Brings focus on the element.

Parameters:

element -

Throws:

ExecutionException

removeFocus

public void removeFocus(ElementStub element)
                 throws ExecutionException

Removes focus from the element.

Parameters:

element -

Throws:

ExecutionException

mouseOver

public void mouseOver(ElementStub link)
               throws ExecutionException

Simulates a mouse over on the given element

Parameters:

link -

Throws:

ExecutionException

dragDrop

public void dragDrop(ElementStub dragElement,
                     ElementStub dropElement)
              throws ExecutionException

Simulates a drag and drop event

Parameters:

dragElement - Element to drag

dropElement - Element to drop on

Throws:

ExecutionException

fetch

public java.lang.String fetch(java.lang.String expression)
                       throws ExecutionException

Fetches the value of any DOM property

Parameters:

expression -

Returns:

Throws:

ExecutionException

fetch

public java.lang.String fetch(ElementStub el)
                       throws ExecutionException

Fetches the string value of an element stub by performing an eval on the browser

Parameters:

element -

Returns:

Throws:

ExecutionException

getText

public java.lang.String getText(ElementStub el)
                         throws ExecutionException

Returns the inner text of given element from the browser

Parameters:

el -

Returns:

Throws:

ExecutionException

getValue

public java.lang.String getValue(ElementStub el)
                          throws ExecutionException

Returns the value of given form element from the browser

Parameters:

el -

Returns:

Throws:

ExecutionException

exists

public boolean exists(ElementStub el)

Returns true if the element exists on the browser Retries a few times if the return value is false. This can be controlled with script.max_reattempts_on_error in sahi.properties. Use exists(el, true) to return in a single try.

Parameters:

elementStub -

Returns:

exists

public boolean exists(ElementStub el,
                      boolean optimistic)

Returns true if the element exists on the browser
Retries a few times if optimistic is false. Retry count can be controlled with script.max_reattempts_on_error in sahi.properties.
Use exists(el, true) to return in a single try.

Parameters:

elementStub -

optimistic - boolean. If true returns in a single try. If false, retries a few times.

Returns:

isVisible

public boolean isVisible(ElementStub el)
                  throws ExecutionException

Returns true if the element is visible on the browser

Parameters:

elementStub -

Returns:

Throws:

ExecutionException

isVisible

public boolean isVisible(ElementStub el,
                         boolean optimistic)
                  throws ExecutionException

Returns true if the element is visible on the browser
Retries a few times if optimistic is false. Retry count can be controlled with script.max_reattempts_on_error in sahi.properties.
Use exists(el, true) to return in a single try.

Parameters:

elementStub -

optimistic - boolean. If true returns in a single try. If false, retries a few times.

Returns:

Throws:

ExecutionException

getSelectedText

public java.lang.String getSelectedText(ElementStub el)
                                 throws ExecutionException

Returns the selected text visible in a select box (<select> tag)

Parameters:

selectElement -

Returns:

Throws:

ExecutionException

popup

public Browser popup(java.lang.String popupName)

Represents a popup window. The name is either the window name or the title of the window.

Parameters:

popupName -

Returns:

domain

public Browser domain(java.lang.String domainName)

Represents a portion of the page which is from a different domain.

Parameters:

domainName -

Returns:

waitFor

public void waitFor(long timeout)

Waits till timeout milliseconds

Parameters:

timeout - in milliseconds

waitFor

public void waitFor(BrowserCondition condition,
                    int timeout)

Waits till the condition is satisfied or till timeout

Parameters:

condition - BrowserCondition

timeout - in milliseconds

BrowserCondition condition = new BrowserCondition(browser); browser.waitFor(condition, 5000);

The above code will make the browser wait till the textbox's value becomes "populated". If it does not become "populated", the browser will wait for max 5000 ms before moving to the next step

choose

public void choose(ElementStub elementStub,
                   java.lang.String value,
                   boolean append)
            throws ExecutionException

Chooses the given option in a select box (<select> tag).

Parameters:

selectElement -

value -

append: - if true, option is selected without unselecting previous option in multi-select box

Throws:

ExecutionException

choose

public void choose(ElementStub elementStub,
                   java.lang.String[] values,
                   boolean append)
            throws ExecutionException

Chooses the given options in a multi select box (<select> tag).

Parameters:

selectElement -

values -

append: - if true, options are selected without unselecting previous options in multi-select box

Throws:

ExecutionException

startRecording

public void startRecording()

Starts recording. It tells the browser to record events and post the steps which will be available via getRecordedSteps()

stopRecording

public void stopRecording()

Stops recording. Tells the browser to stop monitoring events.

getRecordedSteps

public java.lang.String[] getRecordedSteps()

Gets the recorded steps from the last time getRecordedSteps() was called.

Returns:

String array of recorded steps

lastAlert

public java.lang.String lastAlert()
                           throws ExecutionException

Returns the last alert message from browser
Alert messages are generated via window.alert(message) in javascript.

Returns:

String the last alerted message

Throws:

ExecutionException

lastConfirm

public java.lang.String lastConfirm()
                             throws ExecutionException

Returns the last confirm message from browser
Confirm messages are generated via window.confirm(message) in javascript.

Returns:

String the last confirm message

Throws:

ExecutionException

expectPrompt

public void expectPrompt(java.lang.String message,
                         java.lang.String input)
                  throws ExecutionException

Sets the input value of a prompt dialog with given message.
This needs to be set before a prompt is expected.
Prompts are generated in javascript via window.prompt(message)

Parameters:

message - String visible message prompted by the browser

input - String input to enter in the prompt dialog

Throws:

ExecutionException

expectConfirm

public void expectConfirm(java.lang.String message,
                          boolean input)
                   throws ExecutionException

Sets the input value of a confirm dialog with given message.
This needs to be set before a confirm is expected.
Prompts are generated in javascript via window.confirm(message)

Parameters:

message - String visible message prompted by the browser

input - boolean true to click on 'OK', false to click on 'Cancel'

Throws:

ExecutionException

lastPrompt

public java.lang.String lastPrompt()
                            throws ExecutionException

Returns the last prompt message from browser
Alert messages are generated via window.prompt(message) in javascript. Use expectPrompt to set value to prompt.

Returns:

String the last prompt message

Throws:

ExecutionException

clearLastAlert

public void clearLastAlert()
                    throws ExecutionException

Clears the lastAlert message

Throws:

ExecutionException

clearLastPrompt

public void clearLastPrompt()
                     throws ExecutionException

Clears the lastPrompt message

Throws:

ExecutionException

clearLastConfirm

public void clearLastConfirm()
                      throws ExecutionException

Clears the lastConfirm message

Throws:

ExecutionException

title

public java.lang.String title()
                       throws ExecutionException

Throws:

ExecutionException

checked

public boolean checked(ElementStub el)
                throws ExecutionException

Returns true if the element is checked. Is meaningful only for radio buttons and checkboxes

Parameters:

el -

Returns:

Throws:

ExecutionException

addURLMock

public void addURLMock(java.lang.String urlPattern)

Force Sahi to return a canned response for specific URL patterns The response is found in sahi/htdocs/spr/simpleMock.htm and can be modified

Parameters:

urlPattern - a javascript regular expression as a string

addURLMock

public void addURLMock(java.lang.String urlPattern,
                       java.lang.String responseClass_method)

Force Sahi to return a dynamic response returned by responseClass.methodName

Parameters:

urlPattern - a javascript regular expression as a string

responseClass_method - The class which will respond to matching requests

removeURLMock

public void removeURLMock(java.lang.String urlPattern)

Removes any mocks associated with given pattern

Parameters:

urlPattern -

lastDownloadedFileName

public java.lang.String lastDownloadedFileName()

Sahi automatically downloads files into sahi/userdata/temp/download directory.
If a file was downloaded as a result of a click, its fileName will be accessible for assertion

Returns:

fileName of last downloaded file

clearLastDownloadedFileName

public void clearLastDownloadedFileName()

Resets the lastDownloadedFileName to null

saveDownloadedAs

public void saveDownloadedAs(java.lang.String newFilePath)

Saves the last downloaded file to required location.
Can be used to save file to some location and then verify contents by reading it.

Parameters:

newFilePath -

setSpeed

public void setSpeed(int interval)

Sets the speed of playback.
Some applications do not trigger AJAX requests on response to events, but use a small delay before execution.
It is useful to tweak this parameter (eg. increase to 200 milliseconds) The default is picked from "script.time_between_steps" in userdata.properties (or sahi.properties)

Parameters:

interval - time in milliseconds

containsText

public boolean containsText(ElementStub el,
                            java.lang.String text)

Returns true if the element contains the input text

Parameters:

el -

text -

Returns:

true if the element contains the input text

containsHTML

public boolean containsHTML(ElementStub el,
                            java.lang.String html)

Returns true if the element's innerHTML contains the input html

Parameters:

el -

html -

Returns:

true if the element's innerHTML contains the input html

style

public java.lang.String style(ElementStub el,
                              java.lang.String attribute)

Returns the computed css style

Parameters:

el -

attribute -

Returns:

the computed css style

setSessionId

public void setSessionId(java.lang.String sessionId)

sessionId

public java.lang.String sessionId()

rteWrite

public void rteWrite(ElementStub rte,
                     java.lang.String value)

Sets the value in a Rich Text Editor (RTE)

Parameters:

rte -

value -

Throws:

ExecutionException

setBrowserJS

public void setBrowserJS(java.lang.String browserJS)

Allows given javascript to be injected into the browser.
Custom functions or stubbed functions can be passed through this
The given javascript will be available to every web page in this session
Equivalent to adding <browser> blocks in Sahi Script

Eg.
browser.setBrowserJS("function myFinderFn(i){return document.links[i];}");
// The above code defines a function myFinderFn, which will be available on each page of the application.
browser.setBrowserJS("function checkFileFieldIsPopulated(){return true}");
// The above code will redefine checkFileFieldIsPopulated function so that it will always return true


Parameters:

browserJS -

isChrome

public boolean isChrome()

Checks for Google Chrome browser

Returns:

isFirefox

public boolean isFirefox()

Checks for Firefox browser

Returns:

isFF

public boolean isFF()

Checks for Firefox browser

Returns:

isIE

public boolean isIE()

Checks for Internet Explorer browser

Returns:

isSafari

public boolean isSafari()

Checks for Safari browser

Returns:

isOpera

public boolean isOpera()

Checks for Opera browser

Returns: