org.jboss.jsfunit.facade
Class JSFClientSession

java.lang.Object
  org.jboss.jsfunit.facade.JSFClientSession

public class JSFClientSession
extends Object

The JSFClientSession provides a simplified API that wraps HttpUnit. With a single JSFClientSession object, you can simulate an entire user session as you set parameters and submit data using submit() and clickCommandLink() methods.

Author:

Stan Silvert

Constructor Summary

JSFClientSession(String initialPage)
Creates a new client interface for testing the JSF application.

JSFClientSession(WebConversation webConversation, String initialPage)
Creates a new client interface for testing a JSF application using a customized WebConversation.

Method Summary

void	clickCommandLink(String componentID) Finds the named command link and uses the link to submit its form.
void	clickLink(String componentID) Finds the named link and clicks it.
void	doWebRequest(WebRequest request) The method submits the WebRequest to the server using the WebConversation of this JSFClientSession instance.
ClientIDs	getClientIDs() Get the ClientIDs helper class which provides useful information and lookups for the components in the server-side component tree.
WebForm	getForm(String componentID) Package-private method to get the WebForm that contains the given component.
Document	getUpdatedDOM() Get the current state of the DOM including any changes made through the setParameter() method.
WebConversation	getWebConversation() Get the HttpUnit WebConversation used by this instance.
WebResponse	getWebResponse() Get the HttpUnit WebResponse object from the latest request.
void	setCheckbox(String componentID, boolean state) Set a checkbox value on a form.
void	setParameter(String componentID, String value) Set a parameter value on a form.
void	setParameter(String clientID, String inputID, String inputName, String value) Sets a parameter on a rendered input component.
void	submit() Finds the lone form on the page and submits the form.
void	submit(String componentID) Finds the named submit button on a form and submits the form.
void	submitNoButton(String componentID) Submits a form without pressing a button.

Methods inherited from class java.lang.Object

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

Constructor Detail

JSFClientSession

public JSFClientSession(String initialPage)
                 throws MalformedURLException,
                        IOException,
                        SAXException

Creates a new client interface for testing the JSF application. This will also clear the HttpSession. Note that the initialPage param should be something that maps into the FacesServlet. In the case where the FacesServlet is extension mapped in web.xml, this param will be something like "/index.jsf" or "/index.faces". If the FacesServlet is path-mapped then the initialPage param will be something like "/faces/index.jsp".

Parameters:

initialPage - The page used to start a client session with JSF. Example: "/index.jsf"

Throws:

MalformedURLException - If the initialPage cannot be used to create a URL for the JSF app

IOException - If there is an error calling the JSF app

SAXException - If the response from the JSF app cannot be parsed as HTML

JSFClientSession

public JSFClientSession(WebConversation webConversation,
                        String initialPage)
                 throws MalformedURLException,
                        IOException,
                        SAXException

Creates a new client interface for testing a JSF application using a customized WebConversation. To use this constructor, first get a WebConversation from org.jboss.jsfunit.framework.WebConversationFactory.

Example:
WebConversation webConv = WebConversationFactory.makeWebConversation();
webConv.setAuthorization("myuser", "mypassword");
webConv.setHeaderField("Accept-Language", "es-mx,es");
JSFClientSession client = new JSFClientSession(webConv, "/index.jsf");

Note that the initialPage param should be something that maps into the FacesServlet. In the case where the FacesServlet is extension mapped in web.xml, this param will be something like "/index.jsf" or "/index.faces". If the FacesServlet is path-mapped then the initialPage param will be something like "/faces/index.jsp".

Parameters:

webConversation - A WebConversation object with "custom" attributes.

initialPage - The page used to start a client session with JSF. Example: "/index.jsf"

Throws:

IllegalArgumentException - if the WebConversation did not come from the WebConversationFactory.

MalformedURLException - If the initialPage cannot be used to create a URL for the JSF app

IOException - If there is an error calling the JSF app

SAXException - If the response from the JSF app cannot be parsed as HTML

Method Detail

getClientIDs

public ClientIDs getClientIDs()

Get the ClientIDs helper class which provides useful information and lookups for the components in the server-side component tree.

getForm

public WebForm getForm(String componentID)
                throws SAXException

Package-private method to get the WebForm that contains the given component.

Parameters:

componentID - The ID of the component contained by the form, or the ID of the form itself.

Returns:

The WebForm.

Throws:

SAXException - if the current response page can not be parsed

ComponentIDNotFoundException - if the component can not be found

DuplicateClientIDException - if more than one client ID matches the componentID suffix

FormNotFoundException - if no form parameter can be found matching the componentID

doWebRequest

public void doWebRequest(WebRequest request)
                  throws SAXException,
                         IOException

The method submits the WebRequest to the server using the WebConversation of this JSFClientSession instance. At the end of this method, a new view from the server will be loaded so that you can continue to use this JSFClientSession instance to make further requests.

Parameters:

request - The WebRequest

Throws:

IOException - If there is an error calling the JSF app

SAXException - If the response from the JSF app cannot be parsed as HTML

getWebResponse

public WebResponse getWebResponse()

Get the HttpUnit WebResponse object from the latest request.

Returns:

The HttpUnit WebResponse.

getUpdatedDOM

public Document getUpdatedDOM()

Get the current state of the DOM including any changes made through the setParameter() method. WebResponse.getDOM() will only include the state of the DOM after the last request was completed.

getWebConversation

public WebConversation getWebConversation()

Get the HttpUnit WebConversation used by this instance.

Returns:

The WebConversation

setParameter

public void setParameter(String componentID,
                         String value)
                  throws SAXException

Set a parameter value on a form.

Parameters:

componentID - The JSF component ID or a suffix of the client ID.

value - The value to set before the form is submitted.

Throws:

SAXException - if the current response page can not be parsed

ComponentIDNotFoundException - if the component can not be found

DuplicateClientIDException - if more than one client ID matches the componentID suffix

setParameter

public void setParameter(String clientID,
                         String inputID,
                         String inputName,
                         String value)
                  throws SAXException

Sets a parameter on a rendered input component. This method is used for setting values on custom components that render extra HTML input tags.

Parameters:

clientID - The fully-qualified JSF client ID of the component.

inputID - The value of the id attribute of the extra input tag.

inputName - The value of the name attribute of the extra input tag.

value - The value to set before the form is submitted.

Throws:

SAXException - if the current response page can not be parsed

ComponentIDNotFoundException - if the component can not be found

DuplicateClientIDException - if more than one client ID matches the componentID suffix

setCheckbox

public void setCheckbox(String componentID,
                        boolean state)
                 throws SAXException

Set a checkbox value on a form. This method is needed because setParameter can not "uncheck" a checkbox.

Parameters:

componentID - The JSF component ID or a suffix of the client ID.

value - The value to set before the form is submitted.

Throws:

SAXException - if the current response page can not be parsed

ComponentIDNotFoundException - if the component can not be found

DuplicateClientIDException - if more than one client ID matches the componentID suffix

IllegalArgumentException - if the componentID does not resolve to a checkbox control

submit

public void submit()
            throws SAXException,
                   IOException

Finds the lone form on the page and submits the form. At the end of this method call, the new view will be loaded so you can perform tests on the next page.

Throws:

IllegalStateException - if page does not contain exactly one form.

IOException - if there is a problem submitting the form.

SAXException - if the response page can not be parsed

submit

public void submit(String componentID)
            throws SAXException,
                   IOException

Finds the named submit button on a form and submits the form. At the end of this method call, the new view will be loaded so you can perform tests on the next page.

Parameters:

componentID - The JSF component id (or a suffix of the client ID) of the submit button to be "pressed".

Throws:

IOException - if there is a problem submitting the form.

SAXException - if the response page can not be parsed

ComponentIDNotFoundException - if the component can not be found

DuplicateClientIDException - if more than one client ID matches the componentID suffix

ComponentTypeException - if the componentID does reference an HtmlCommandButton JSF component.

submitNoButton

public void submitNoButton(String componentID)
                    throws SAXException,
                           IOException

Submits a form without pressing a button. This is useful for testing forms that are submitted via javascript. At the end of this method call, the new view will be loaded so you can perform tests on the next page.

Parameters:

componentID - The JSF component id (or a suffix of the client ID) of a component on the form to be submitted. This can also be the ID of the form itself.

Throws:

IOException - if there is a problem submitting the form.

SAXException - if the response page can not be parsed

ComponentIDNotFoundException - if the component can not be found

DuplicateClientIDException - if more than one client ID matches the componentID suffix

clickLink

public void clickLink(String componentID)
               throws SAXException,
                      IOException

Finds the named link and clicks it. This method is used to click static links such as those produced by h:outputLink. If you need to submit a form using an h:commandLink, use clickCommandLink() instead. At the end of this method call, a new page will be loaded. So you can use this JSFClientSession instance to do tests on the page. However, static links typically do not call into the JSF servlet. Therefore, you have exited the realm of JSF. In that case you will probably need a new JSFClientSession instance to do more JSF testing.

Parameters:

componentID - The JSF component id (or a suffix of the client ID) of the link to be "clicked".

Throws:

IOException - if there is a problem clicking the link.

SAXException - if the response page can not be parsed.

ComponentIDNotFoundException - if the component can not be found

DuplicateClientIDException - if more than one client ID matches the componentID suffix

ComponentTypeException - if the componentID does reference an HtmlOutputLink JSF component.

clickCommandLink

public void clickCommandLink(String componentID)
                      throws SAXException,
                             IOException

Finds the named command link and uses the link to submit its form. At the end of this method call, the new view will be loaded so you can perform tests on the next page.

Parameters:

componentID - The JSF component id (or a suffix of the client ID) of the link to be "clicked".

Throws:

IOException - if there is a problem clicking the link.

SAXException - if the response page can not be parsed.

ComponentIDNotFoundException - if the component can not be found

DuplicateClientIDException - if more than one client ID matches the componentID suffix

ComponentTypeException - if the componentID does reference an HtmlCommandLink JSF component.