Package com.meterware.httpunit
Class WebClient
- java.lang.Object
-
- com.meterware.httpunit.WebClient
-
- Direct Known Subclasses:
ServletUnitClient
,WebConversation
public abstract class WebClient extends java.lang.Object
The context for a series of web requests. This class manages cookies used to maintain session context, computes relative URLs, and generally emulates the browser behavior needed to build an automated test of a web site.- Author:
- Russell Gold, Jan Ohrstrom, Seth Ladd, Oliver Imbusch
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
WebClient.HeaderDictionary
-
Constructor Summary
Constructors Modifier Constructor Description protected
WebClient()
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
addClientListener(WebClientListener listener)
Adds a listener to watch for requests and responses.void
addCookie(java.lang.String name, java.lang.String value)
Deprecated.as of 1.6, use #putCookie instead.void
addWindowListener(WebWindowListener listener)
Adds a listener to watch for window openings and closings.void
clearContents()
Resets the state of this client, removing all cookies, frames, and per-client headers.void
clearProxyServer()
Clears the proxy server settings.ClientProperties
getClientProperties()
Returns the properties associated with this client.Cookie
getCookieDetails(java.lang.String name)
Returns an object containing the details of the named cookieCookieJar
getCookieJar()
Deprecated.- use with care - was not public in the pastjava.lang.String[]
getCookieNames()
Returns the name of all the active cookies which will be sent to the server.java.lang.String
getCookieValue(java.lang.String name)
Returns the value of the specified cookie.WebResponse
getCurrentPage()
Returns the response representing the current top page in the main window.boolean
getExceptionsThrownOnErrorStatus()
Returns true if an exception will be thrown when an error status (4xx or 5xx) is detected on a response.WebResponse
getFrameContents(FrameSelector targetFrame)
Returns the response associated with the specified frame name in the main window.WebResponse
getFrameContents(java.lang.String frameName)
Returns the response associated with the specified frame name in the main window.java.lang.String[]
getFrameNames()
Returns the name of the currently active frames in the main window.java.lang.String
getHeaderField(java.lang.String fieldName)
Returns the value for the header field with the specified name.protected java.util.Dictionary
getHeaderFields(java.net.URL targetURL)
Returns the value of all current header fields.WebWindow
getMainWindow()
java.lang.String
getNextAlert()
Returns the next javascript alert without removing it from the queue.WebWindow
getOpenWindow(java.lang.String name)
WebWindow[]
getOpenWindows()
java.lang.String
getProxyHost()
Returns the name of the active proxy server.int
getProxyPort()
Returns the number of the active proxy port, or 0 is none is specified.WebResponse
getResource(WebRequest request)
Returns the resource specified by the request.WebResponse
getResponse(WebRequest request)
Submits a web request and returns a response, using all state developed so far as stored in cookies as requested by the server.WebResponse
getResponse(java.lang.String urlString)
Submits a GET method request and returns a response.java.lang.String
getUserAgent()
Deprecated.as of 1.4.6.protected abstract WebResponse
newResponse(WebRequest request, FrameSelector targetFrame)
Creates a web response object which represents the response to the specified web request.java.lang.String
popNextAlert()
Returns the next javascript alert and removes it from the queue.void
putCookie(java.lang.String name, java.lang.String value)
Defines a cookie to be sent to the server on every request.void
removeClientListener(WebClientListener listener)
Removes a listener to watch for requests and responses.void
removeWindowListener(WebWindowListener listener)
Removes a listener to watch for window openings and closings.WebResponse
sendRequest(WebRequest request)
Submits a web request and returns a response.void
setAuthentication(java.lang.String realm, java.lang.String username, java.lang.String password)
Specifies a username and password for on-demand authentication.void
setAuthorization(java.lang.String userName, java.lang.String password)
Deprecated.as of 1.7.void
setDialogResponder(DialogResponder responder)
Specifies the object which will respond to all dialogs.void
setExceptionsThrownOnErrorStatus(boolean throwExceptions)
Specifies whether an exception will be thrown when an error status (4xx or 5xx) is detected on a response.void
setHeaderField(java.lang.String fieldName, java.lang.String fieldValue)
Sets the value for a header field to be sent with all requests.void
setMainWindow(WebWindow mainWindow)
abstract void
setProxyServer(java.lang.String proxyHost, int proxyPort)
Specifies a proxy server to use for requests from this client.void
setProxyServer(java.lang.String proxyHost, int proxyPort, java.lang.String userName, java.lang.String password)
Specifies a proxy server to use, along with a user and password for authentication.void
setUserAgent(java.lang.String userAgent)
Deprecated.as of 1.4.6.protected void
updateMainWindow(FrameSelector frame, WebResponse response)
Updates this web client based on a received response.protected void
writeMessageBody(WebRequest request, java.io.OutputStream stream)
Writes the message body for the request.
-
-
-
Method Detail
-
getMainWindow
public WebWindow getMainWindow()
-
setMainWindow
public void setMainWindow(WebWindow mainWindow)
-
getOpenWindows
public WebWindow[] getOpenWindows()
-
getOpenWindow
public WebWindow getOpenWindow(java.lang.String name)
-
getResponse
public WebResponse getResponse(java.lang.String urlString) throws java.io.IOException, org.xml.sax.SAXException
Submits a GET method request and returns a response.- Throws:
org.xml.sax.SAXException
- thrown if there is an error parsing the retrieved pagejava.io.IOException
-
sendRequest
public WebResponse sendRequest(WebRequest request) throws java.io.IOException, org.xml.sax.SAXException
Submits a web request and returns a response. This is an alternate name for the getResponse method.- Throws:
java.io.IOException
org.xml.sax.SAXException
-
getCurrentPage
public WebResponse getCurrentPage()
Returns the response representing the current top page in the main window.
-
getResponse
public WebResponse getResponse(WebRequest request) throws java.io.IOException, org.xml.sax.SAXException
Submits a web request and returns a response, using all state developed so far as stored in cookies as requested by the server.- Throws:
org.xml.sax.SAXException
- thrown if there is an error parsing the retrieved pagejava.io.IOException
-
getFrameNames
public java.lang.String[] getFrameNames()
Returns the name of the currently active frames in the main window.
-
getFrameContents
public WebResponse getFrameContents(java.lang.String frameName)
Returns the response associated with the specified frame name in the main window. Throws a runtime exception if no matching frame is defined.
-
getFrameContents
public WebResponse getFrameContents(FrameSelector targetFrame)
Returns the response associated with the specified frame name in the main window. Throws a runtime exception if no matching frame is defined.- Since:
- 1.6
-
getResource
public WebResponse getResource(WebRequest request) throws java.io.IOException
Returns the resource specified by the request. Does not update the client or load included framesets or scripts. May return null if the resource is a JavaScript URL which would normally leave the client unchanged.- Throws:
java.io.IOException
-
clearContents
public void clearContents()
Resets the state of this client, removing all cookies, frames, and per-client headers. This does not affect any listeners or preferences which may have been set.
-
addCookie
public void addCookie(java.lang.String name, java.lang.String value)
Deprecated.as of 1.6, use #putCookie instead.Defines a cookie to be sent to the server on every request.
-
putCookie
public void putCookie(java.lang.String name, java.lang.String value)
Defines a cookie to be sent to the server on every request. This overrides any previous setting for this cookie name.
-
getCookieNames
public java.lang.String[] getCookieNames()
Returns the name of all the active cookies which will be sent to the server.
-
getCookieDetails
public Cookie getCookieDetails(java.lang.String name)
Returns an object containing the details of the named cookie- Since:
- [ 1488617 ] alternate patch for cookie bug #1371204
-
getCookieValue
public java.lang.String getCookieValue(java.lang.String name)
Returns the value of the specified cookie.
-
getClientProperties
public ClientProperties getClientProperties()
Returns the properties associated with this client.
-
setUserAgent
public void setUserAgent(java.lang.String userAgent)
Deprecated.as of 1.4.6. Use ClientProperties#setUserAgent instead.Specifies the user agent identification. Used to trigger browser-specific server behavior.
-
getUserAgent
public java.lang.String getUserAgent()
Deprecated.as of 1.4.6. Use ClientProperties#getUserAgent instead.Returns the current user agent setting.
-
setAuthorization
public void setAuthorization(java.lang.String userName, java.lang.String password)
Deprecated.as of 1.7. Use #setAuthentication for more accurate emulation of browser behavior.Sets a username and password for a basic authentication scheme.
-
setAuthentication
public void setAuthentication(java.lang.String realm, java.lang.String username, java.lang.String password)
Specifies a username and password for on-demand authentication. Will only send the authorization header when challenged for the specified realm.- Parameters:
realm
- the realm for which the credentials apply.username
- the user to authenticatepassword
- the credentials for the user
-
setProxyServer
public abstract void setProxyServer(java.lang.String proxyHost, int proxyPort)
Specifies a proxy server to use for requests from this client.
-
setProxyServer
public void setProxyServer(java.lang.String proxyHost, int proxyPort, java.lang.String userName, java.lang.String password)
Specifies a proxy server to use, along with a user and password for authentication.- Since:
- 1.6
-
clearProxyServer
public void clearProxyServer()
Clears the proxy server settings.
-
getProxyHost
public java.lang.String getProxyHost()
Returns the name of the active proxy server.
-
getProxyPort
public int getProxyPort()
Returns the number of the active proxy port, or 0 is none is specified.
-
setHeaderField
public void setHeaderField(java.lang.String fieldName, java.lang.String fieldValue)
Sets the value for a header field to be sent with all requests. If the value set is null, removes the header from those to be sent.
-
getHeaderField
public java.lang.String getHeaderField(java.lang.String fieldName)
Returns the value for the header field with the specified name. This method will ignore the case of the field name.
-
setExceptionsThrownOnErrorStatus
public void setExceptionsThrownOnErrorStatus(boolean throwExceptions)
Specifies whether an exception will be thrown when an error status (4xx or 5xx) is detected on a response. Defaults to the value returned by HttpUnitOptions.getExceptionsThrownOnErrorStatus.
-
getExceptionsThrownOnErrorStatus
public boolean getExceptionsThrownOnErrorStatus()
Returns true if an exception will be thrown when an error status (4xx or 5xx) is detected on a response.
-
addClientListener
public void addClientListener(WebClientListener listener)
Adds a listener to watch for requests and responses.
-
removeClientListener
public void removeClientListener(WebClientListener listener)
Removes a listener to watch for requests and responses.
-
addWindowListener
public void addWindowListener(WebWindowListener listener)
Adds a listener to watch for window openings and closings.
-
removeWindowListener
public void removeWindowListener(WebWindowListener listener)
Removes a listener to watch for window openings and closings.
-
getNextAlert
public java.lang.String getNextAlert()
Returns the next javascript alert without removing it from the queue.
-
popNextAlert
public java.lang.String popNextAlert()
Returns the next javascript alert and removes it from the queue. If the queue is empty, will return an empty string.
-
setDialogResponder
public void setDialogResponder(DialogResponder responder)
Specifies the object which will respond to all dialogs.
-
newResponse
protected abstract WebResponse newResponse(WebRequest request, FrameSelector targetFrame) throws java.io.IOException
Creates a web response object which represents the response to the specified web request.- Parameters:
request
- the request to which the response should be generatedtargetFrame
- the frame in which the response should be stored- Throws:
java.io.IOException
-
writeMessageBody
protected final void writeMessageBody(WebRequest request, java.io.OutputStream stream) throws java.io.IOException
Writes the message body for the request.- Throws:
java.io.IOException
-
getHeaderFields
protected java.util.Dictionary getHeaderFields(java.net.URL targetURL)
Returns the value of all current header fields.
-
updateMainWindow
protected final void updateMainWindow(FrameSelector frame, WebResponse response) throws java.io.IOException, org.xml.sax.SAXException
Updates this web client based on a received response. This includes updating cookies and frames. This method is required by ServletUnit, which cannot call the updateWindow method directly.- Throws:
java.io.IOException
org.xml.sax.SAXException
-
getCookieJar
public CookieJar getCookieJar()
Deprecated.- use with care - was not public in the pastSupport Request [ 1288796 ] getCookieJar() in WebClient- Returns:
- the cookie jar
-
-