001: /******************************************************************************
002: * jWebUnit project (http://jwebunit.sourceforge.net) *
003: * Distributed open-source, see full license under LICENCE.txt *
004: ******************************************************************************/package net.sourceforge.jwebunit.api;
005:
006: import java.io.InputStream;
007: import java.net.URL;
008: import java.util.List;
009:
010: import net.sourceforge.jwebunit.exception.ExpectedJavascriptAlertException;
011: import net.sourceforge.jwebunit.exception.ExpectedJavascriptConfirmException;
012: import net.sourceforge.jwebunit.exception.ExpectedJavascriptPromptException;
013: import net.sourceforge.jwebunit.exception.TestingEngineResponseException;
014: import net.sourceforge.jwebunit.html.Table;
015: import net.sourceforge.jwebunit.javascript.JavascriptAlert;
016: import net.sourceforge.jwebunit.javascript.JavascriptConfirm;
017: import net.sourceforge.jwebunit.javascript.JavascriptPrompt;
018: import net.sourceforge.jwebunit.util.TestContext;
019:
020: /**
021: * This is the interface for all communications between jWebUnit and the specific running test engine or dialog.
022: *
023: * @author Julien Henry
024: * @author Nick Neuberger
025: */
026: public interface IJWebUnitDialog {
027:
028: /**
029: * Open the browser at an initial URL.
030: *
031: * @param aInitialURL Initial URL
032: * @param aTestContext Test context
033: * @throws TestingEngineResponseException If something bad happend (404)
034: */
035: void beginAt(URL aInitialURL, TestContext aTestContext)
036: throws TestingEngineResponseException;
037:
038: /**
039: * Close the browser and check if there is no pending Javascript alert, confirm or prompt.
040: *
041: * @throws ExpectedJavascriptAlertException If there is pending Javascript alert
042: * {@link IJWebUnitDialog#setExpectedJavaScriptAlert(JavascriptAlert[])}
043: * @throws ExpectedJavascriptConfirmException If there is pending Javascript confirm
044: * {@link IJWebUnitDialog#setExpectedJavaScriptConfirm(JavascriptConfirm[])}
045: * @throws ExpectedJavascriptPromptException If there is pending Javascript prompt
046: * {@link IJWebUnitDialog#setExpectedJavaScriptPrompt(JavascriptPrompt[])}
047: */
048: void closeBrowser() throws ExpectedJavascriptAlertException,
049: ExpectedJavascriptConfirmException,
050: ExpectedJavascriptPromptException;
051:
052: /**
053: * Simulate user typing a new URL in the browser.
054: *
055: * @param url Full URL of the page.
056: * @throws TestingEngineResponseException If something bad happend (404)
057: */
058: void gotoPage(URL url) throws TestingEngineResponseException;
059:
060: /**
061: * Enable or disable Javascript support.
062: *
063: * @param value true to enable Javascript.
064: */
065: void setScriptingEnabled(boolean value);
066:
067: /**
068: * Get all cookies.
069: *
070: * @return List of javax.servlet.http.Cookie.
071: */
072: List getCookies();
073:
074: /**
075: * Test if the window with the given name is present.
076: *
077: * @param windowName Name of the window.
078: * @return true if the Window exists.
079: */
080: boolean hasWindow(String windowName);
081:
082: /**
083: * Test if window with the given title is present.
084: *
085: * @param windowTitle Title of the window.
086: * @return true if the Window exists.
087: */
088: boolean hasWindowByTitle(String windowTitle);
089:
090: /**
091: * Make the window with the given name active.
092: *
093: * @param windowName Name of the window
094: */
095: void gotoWindow(String windowName);
096:
097: /**
098: * Goto first window with the given title.
099: *
100: * @param title Title of the window
101: */
102: void gotoWindowByTitle(String title);
103:
104: /**
105: * Goto window with the given Javascript ID.
106: *
107: * @param windowID Javascript ID of the window
108: */
109: void gotoWindow(int windowID);
110:
111: /**
112: * Make the root window active.
113: */
114: void gotoRootWindow();
115:
116: /**
117: * Get the number of openend Windows.
118: *
119: * @return Number of openend Windows.
120: */
121: int getWindowCount();
122:
123: /**
124: * Close the current window.
125: *
126: */
127: void closeWindow();
128:
129: /**
130: * Test if the given frame is present.
131: *
132: * @param frameNameOrId Name or ID of the frame. ID is checked first.
133: * @return true if the frame exists.
134: */
135: boolean hasFrame(String frameNameOrId);
136:
137: /**
138: * Make the frame with the given name or ID active in the current conversation.
139: *
140: * @param frameNameOrId Name or ID of the frame. ID is checked first.
141: */
142: void gotoFrame(String frameNameOrId);
143:
144: /**
145: * Set the form on the current page that the client wishes to work with explicitly by index in the page.
146: *
147: * @param index The 0-based index, when more than one form with the same name is expected.
148: */
149: void setWorkingForm(int index);
150:
151: /**
152: * Set the form on the current page that the client wishes to work with explicitly by either the form name or id
153: * (match by id is attempted first).
154: *
155: * @param nameOrId name or id of the form to be worked with.
156: * @param index The 0-based index, when more than one form with the same name is expected.
157: */
158: void setWorkingForm(String nameOrId, int index);
159:
160: /**
161: * Check whether the current page contains a form.
162: *
163: * @return true if there is at least a form.
164: */
165: boolean hasForm();
166:
167: /**
168: * Return true if the current page contains a specific form.
169: *
170: * @param nameOrID name of id of the form to check for.
171: * @return true if there is at least a form.
172: */
173: boolean hasForm(String nameOrID);
174:
175: /**
176: * Return true if a form input element is present on the current form.
177: *
178: * @param paramName name of the input element to check for
179: * @return true if there is at least a form parameter.
180: */
181: boolean hasFormParameterNamed(String paramName);
182:
183: /**
184: * Return the current value of a text field with name <code>paramName</code>. Text fields are input text, input
185: * password and textarea
186: *
187: * @param paramName name of the text field element.
188: * @return Text content of the text field.
189: */
190: String getTextFieldValue(String paramName);
191:
192: /**
193: * Return the current value of a hidden input element with name <code>paramName</code>.
194: *
195: * @param paramName name of the hidden input element.
196: * @return Value of the hidden input.
197: */
198: String getHiddenFieldValue(String paramName);
199:
200: /**
201: * Fill a text, password or textarea field with the provided text.
202: *
203: * @param inputName name of the text, password or textarea element
204: * @param text value to type in the field.
205: */
206: void setTextField(String inputName, String text);
207:
208: /**
209: * Return a string array of select box option values.
210: *
211: * Exemple: <br/>
212: *
213: * <code>
214: * <FORM action="http://my_host/doit" method="post">
215: * <P>
216: * <SELECT multiple size="4" name="component-select">
217: * <OPTION selected value="Component_1_a">Component_1</OPTION>
218: * <OPTION selected value="Component_1_b">Component_2</OPTION>
219: * <OPTION>Component_3</OPTION>
220: * <OPTION>Component_4</OPTION>
221: * <OPTION>Component_5</OPTION>
222: * </SELECT><BR/>
223: * <INPUT type="submit" value="Send">
224: * <INPUT type="reset">
225: * </P>
226: * </FORM>
227: * </code>
228: *
229: * Should return [Component_1_a, Component_1_b, Component_3, Component_4, Component_5]
230: *
231: * @param selectName name of the select box.
232: * @return Array of select options values.
233: */
234: String[] getSelectOptionValues(String selectName);
235:
236: /**
237: * Return the values of the currently selected items in a select box.
238: *
239: * @param selectName name of the select box.
240: */
241: String[] getSelectedOptions(String selectName);
242:
243: /**
244: * Get the label for a given option of a select box.
245: *
246: * @param selectName name of the select box.
247: * @param optionValue label of the option.
248: */
249: String getSelectOptionLabelForValue(String selectName,
250: String optionValue);
251:
252: /**
253: * Get the value for a given option of a select box.
254: *
255: * @param selectName name of the select box.
256: * @param optionLabel label of the option.
257: */
258: String getSelectOptionValueForLabel(String selectName,
259: String optionLabel);
260:
261: /**
262: * Select option(s) of a select box by value.
263: *
264: * @param selectName name of the select box.
265: * @param optionsValue values of the options to select.
266: */
267: void selectOptions(String selectName, String[] optionsValue);
268:
269: /**
270: * Unselect option(s) of a select box by display label.
271: *
272: * @param selectName name of the select box.
273: * @param optionsValue vaules of the options to unselect.
274: */
275: void unselectOptions(String selectName, String[] options);
276:
277: /**
278: * Test if a select box has the given option (by label).
279: *
280: * @param selectName name of the select box.
281: * @param optionLabel label of the option.
282: * @return true if a select box has the given option (by label).
283: */
284: boolean hasSelectOption(String selectName, String optionLabel);
285:
286: /**
287: * Test if a select box has the given option (by value).
288: *
289: * @param selectName name of the select box.
290: * @param optionValue value of the option.
291: * @return true if a select box has the given option (by value).
292: */
293: boolean hasSelectOptionValue(String selectName, String optionValue);
294:
295: /**
296: * Determines if the checkbox is selected.
297: *
298: * @param checkBoxName name of the checkbox.
299: * @return true if the first checkbox with given name is selected.
300: */
301: boolean isCheckboxSelected(String checkBoxName);
302:
303: /**
304: * Determines if the checkbox is selected.
305: *
306: * @param checkBoxName name attribut of the checkbox.
307: * @param checkBoxValue value attribut of the checkbox.
308: * @return true if the first checkbox with given name and value is selected.
309: */
310: boolean isCheckboxSelected(String checkBoxName, String checkBoxValue);
311:
312: /**
313: * Select a specified checkbox. If the checkbox is already checked then the checkbox will stay checked.
314: *
315: * @param checkBoxName name of checkbox to be selected.
316: */
317: void checkCheckbox(String checkBoxName);
318:
319: /**
320: * Select a specified checkbox. If the checkbox is already checked then the checkbox will stay checked.
321: *
322: * @param checkBoxName name of checkbox to be selected.
323: * @param checkBoxValue value of the checkbox (to differenciate checkboxes with the same name).
324: */
325: void checkCheckbox(String checkBoxName, String checkBoxValue);
326:
327: /**
328: * Deselect a specified checkbox. If the checkbox is already unchecked then the checkbox will stay unchecked.
329: *
330: * @param checkBoxName name of checkbox to be deselected.
331: */
332: void uncheckCheckbox(String checkBoxName);
333:
334: /**
335: * Deselect a specified checkbox. If the checkbox is already unchecked then the checkbox will stay unchecked.
336: *
337: * @param checkBoxName name of checkbox to be deselected.
338: * @param value value of the checkbox (to differenciate checkboxes with the same name).
339: */
340: void uncheckCheckbox(String checkBoxName, String value);
341:
342: /**
343: * Clicks a radio option. Asserts that the radio option exists first.
344: *
345: * @param radioGroup name of the radio group.
346: * @param radioOptionValue value of the option to check for.
347: */
348: void clickRadioOption(String radioGroup, String radioOptionValue);
349:
350: /**
351: * Checks if a radio group contains the indicated option.
352: *
353: * @param radioGroup name of the radio group.
354: * @param radioOptionValue value of the option to check for.
355: */
356: boolean hasRadioOption(String radioGroup, String radioOptionValue);
357:
358: /**
359: * Return the currently selected radio button.
360: * @param radioGroup name of the radio group.
361: * @return value of the selected radio.
362: */
363: String getSelectedRadio(String radioGroup);
364:
365: /**
366: * Checks if the current form contains a submit button.
367: *
368: */
369: boolean hasSubmitButton();
370:
371: /**
372: * Checks if the current form contains a specific submit button.<br/> A submit button can be the following HTML
373: * elements:
374: * <ul>
375: * <li>input type=submit
376: * <li>input type=image
377: * <li>button type=submit
378: * </ul>
379: *
380: * @param nameOrID name or id of the button to check for.
381: */
382: boolean hasSubmitButton(String nameOrID);
383:
384: /**
385: * Checks if the current form contains a specific submit button.<br/> A submit button can be the following HTML
386: * elements:
387: * <ul>
388: * <li>input type=submit
389: * <li>input type=image
390: * <li>button type=submit
391: * </ul>
392: *
393: * @param nameOrID name of id of the button to check for.
394: * @param value value of the button
395: */
396: boolean hasSubmitButton(String nameOrID, String value);
397:
398: /**
399: * Submit the current form with the default submit button. See {@link #getForm}for an explanation of how the
400: * current form is established.<br/> A submit button can be the following HTML elements:
401: * <ul>
402: * <li>input type=submit
403: * <li>input type=image
404: * <li>button type=submit
405: * </ul>
406: */
407: void submit();
408:
409: /**
410: * Submit the current form with the specifed submit button. See {@link #getForm}for an explanation of how the
411: * current form is established.<br/> A submit button can be the following HTML elements:
412: * <ul>
413: * <li>input type=submit
414: * <li>input type=image
415: * <li>button type=submit
416: * </ul>
417: *
418: * @param buttonName name of the button to use for submission.
419: */
420: void submit(String buttonName);
421:
422: /**
423: * Submit the current form with the specifed submit button (by name and value). See {@link #getForm}for an
424: * explanation of how the current form is established.<br/> A submit button can be the following HTML elements:
425: * <ul>
426: * <li>input type=submit
427: * <li>input type=image
428: * <li>button type=submit
429: * </ul>
430: *
431: * @author Dragos Manolescu
432: * @param buttonName name of the button to use for submission.
433: * @param buttonValue value/label of the button to use for submission
434: */
435: void submit(String buttonName, String buttonValue);
436:
437: /**
438: * Checks if the current form contains a reset button.<br/> A reset button can be the following HTML elements:
439: * <ul>
440: * <li>input type=reset
441: * <li>button type=reset
442: * </ul>
443: *
444: */
445: boolean hasResetButton();
446:
447: /**
448: * Checks if the current form contains a specific reset button.<br/> A reset button can be the following HTML
449: * elements:
450: * <ul>
451: * <li>input type=reset
452: * <li>button type=reset
453: * </ul>
454: *
455: * @param nameOrID name or id of the button to check for.
456: */
457: boolean hasResetButton(String nameOrID);
458:
459: /**
460: * Reset the current form with the default reset button. See {@link #getForm}for an explanation of how the current
461: * form is established.<br/> A reset button can be the following HTML elements:
462: * <ul>
463: * <li>input type=reset
464: * <li>button type=reset
465: * </ul>
466: */
467: void reset();
468:
469: /**
470: * Checks if a button with <code>text</code> is present.<br/> A button can be the following HTML elements:
471: * <ul>
472: * <li>input type=button
473: * <li>button type=button
474: * </ul>
475: *
476: * @param text the text of the button (contents of the value attribute).
477: * @return <code>true</code> when the button with text could be found.
478: */
479: boolean hasButtonWithText(String text);
480:
481: /**
482: * Checks if a button with <code>id</code> is present.<br/> A button can be the following HTML elements:
483: * <ul>
484: * <li>input type=button
485: * <li>button type=button
486: * </ul>
487: *
488: * @param buttonId the ID of the button.
489: * @return <code>true</code> when the button with text could be found.
490: */
491: boolean hasButton(String buttonId);
492:
493: /**
494: * Click the indicated button. <br/> A button can be the following HTML elements:
495: * <ul>
496: * <li>input type=button
497: * <li>button type=button
498: * </ul>
499: *
500: * @param buttonId the ID of the button.
501: */
502: void clickButton(String buttonId);
503:
504: /**
505: * Clicks a button with <code>text</code> of the value attribute. <br/> A button can be the following HTML
506: * elements:
507: * <ul>
508: * <li>input type=button
509: * <li>button type=button
510: * </ul>
511: *
512: * @param buttonValueText the text of the button (contents of the value attribute).
513: */
514: void clickButtonWithText(String buttonValueText);
515:
516: /**
517: * Get the location of the current page.
518: * @return an URL.
519: */
520: URL getPageURL();
521:
522: /**
523: * Return the string representation of the current page, encoded as specified by the current
524: * {@link net.sourceforge.jwebunit.util.TestContext}.
525: *
526: * @return Visible text in the page.
527: */
528: String getPageText();
529:
530: /**
531: * Return the source of the current page (like in a browser).
532: *
533: * @return Source of the page (or HTTP Body as String)
534: */
535: String getPageSource();
536:
537: /**
538: * Return the page title of the current response page, encoded as specified by the current
539: * {@link net.sourceforge.jwebunit.util.TestContext}.
540: *
541: * @return Title of the page.
542: */
543: String getPageTitle();
544:
545: /**
546: * Return the response of the server for the current page.
547: *
548: * @return HTTP header & body
549: */
550: String getServerResponse();
551:
552: /**
553: * Gets the last server response as input stream.
554: *
555: */
556: InputStream getInputStream();
557:
558: /**
559: * Gets the input stream for a given URL - can be used to test images or other resources without changing the current
560: * navigation context.
561: *
562: * @param url the url to the resource
563: */
564: InputStream getInputStream(URL url)
565: throws TestingEngineResponseException;
566:
567: /**
568: * Check if the Table object representing a specified table exists.
569: *
570: * @param tableSummaryNameOrId summary, name or id of the table.
571: * @return true if table exists.
572: */
573: boolean hasTable(String tableSummaryNameOrId);
574:
575: /**
576: * Each framework have it's own way to represent a Table. Dialogs are responsible for converting to the unified
577: * jWebUnit format.
578: *
579: * @param tableSummaryNameOrId summary, name or id of the table to return.
580: * @return unified jWebUnit representation of a table.
581: */
582: Table getTable(String tableSummaryNameOrId);
583:
584: /**
585: * Return true if a link is present in the current response containing the specified text.
586: *
587: * @param linkText text to check for in links on the response.
588: * @param index The 0-based index, when more than one link with the same text is expected.
589: */
590: boolean hasLinkWithText(String linkText, int index);
591:
592: /**
593: * Return true if a link is present in the current page containing the exact specified text. Note. This will call
594: * String.trim() to trim all leading / trailing spaces.
595: *
596: * RFE 996031...
597: *
598: * @param linkText text to check for in links on the response.
599: * @param index The 0-based index, when more than one link with the same text is expected.
600: */
601: boolean hasLinkWithExactText(String linkText, int index);
602:
603: /**
604: * Return true if a link is present with a given image based on filename of image.
605: *
606: * @param imageFileName A suffix of the image's filename; for example, to match
607: * <tt>"images/my_icon.png"<tt>, you could just pass in
608: * <tt>"my_icon.png"<tt>.
609: * @param index
610: * The 0-based index, when more than one link with the same text
611: * is expected.
612: */
613: boolean hasLinkWithImage(String imageFileName, int index);
614:
615: /**
616: * Return true if a link is present in the current response with the specified id.
617: *
618: * @param anId link id to check for.
619: */
620: boolean hasLink(String anId);
621:
622: /**
623: * Navigate by submitting a request based on a link containing the specified text. A RuntimeException is thrown if
624: * no such link can be found.
625: *
626: * @param linkText text which link to be navigated should contain.
627: * @param index The 0-based index, when more than one link with the same text is expected.
628: */
629: void clickLinkWithText(String linkText, int index);
630:
631: /**
632: * Navigate by clicking a link with the exact specified text. A RuntimeException is thrown if no such link can be
633: * found.
634: *
635: * @param linkText exact text which link to be navigated should contain.
636: * @param index The 0-based index, when more than one link with the same text is expected.
637: */
638: void clickLinkWithExactText(String linkText, int index);
639:
640: /**
641: * Navigate by submitting a request based on a link with a given ID. A RuntimeException is thrown if no such link
642: * can be found.
643: *
644: * @param anID id of link to be navigated.
645: */
646: void clickLink(String anID);
647:
648: /**
649: * Navigate by submitting a request based on a link with a given image file name. A RuntimeException is thrown if no
650: * such link can be found.
651: *
652: * @param imageFileName A suffix of the image's filename; for example, to match <tt>"images/my_icon.png"</tt>,
653: * you could just pass in <tt>"my_icon.png"</tt>.
654: * @param index The 0-based index, when more than one link with the same text is expected.
655: */
656: void clickLinkWithImage(String imageFileName, int index);
657:
658: /**
659: * Test if element with given id exists.
660: *
661: * @param anID id of the element.
662: * @return true if element was found.
663: */
664: boolean hasElement(String anID);
665:
666: /**
667: * Test if element with given xpath exists.
668: *
669: * @param xpath xpath of the element.
670: * @return true if element was found.
671: */
672: boolean hasElementByXPath(String xpath);
673:
674: /**
675: * Click element with given xpath.
676: *
677: * @param xpath xpath of the element.
678: */
679: void clickElementByXPath(String xpath);
680:
681: /**
682: * Get attribut value of the given element. For example, if you have img src="bla.gif" alt="toto",
683: * getElementAttributByXPath("//img[@src='bla.gif']", "alt") returns "toto"
684: *
685: * @param xpath xpath of the element.
686: * @param attribut name of the attribut.
687: * @return Attribut value or null if the element is not found.
688: */
689: String getElementAttributByXPath(String xpath, String attribut);
690:
691: /**
692: * Get text of the given element.
693: *
694: * @param xpath xpath of the element.
695: */
696: String getElementTextByXPath(String xpath);
697:
698: /**
699: * Return true if a given string is contained within the specified element.
700: *
701: * @param elementID ID of element to inspect.
702: * @param text text to check for.
703: * @return true if text was found.
704: */
705: boolean isTextInElement(String elementID, String text);
706:
707: /**
708: * Return true if a given regexp is contained within the specified element.
709: *
710: * @param elementID Id of element to inspect.
711: * @param regexp regexp to match.
712: * @return true if a match is found.
713: */
714: boolean isMatchInElement(String elementID, String regexp);
715:
716: /**
717: * Tell the dialog that the given alert boxes are expected in the given order.
718: *
719: * @param alerts Expected alerts.
720: * @throws ExpectedJavascriptAlertException If there are still unconsummed alert since a previous call of this
721: * method.
722: */
723: void setExpectedJavaScriptAlert(JavascriptAlert[] alerts)
724: throws ExpectedJavascriptAlertException;
725:
726: /**
727: * Tell the dialog that the given confirm boxes are expected in the given order.
728: *
729: * @param confirms Expected confirms.
730: * @throws ExpectedJavascriptConfirmException If there are still unconsummed confirm since a previous call of this
731: * method.
732: */
733: void setExpectedJavaScriptConfirm(JavascriptConfirm[] confirms)
734: throws ExpectedJavascriptConfirmException;
735:
736: /**
737: * Tell the dialog that the given prompt boxes are expected in the given order.
738: *
739: * @param prompts Expected prompts.
740: * @throws ExpectedJavascriptPromptException If there are still unconsummed prompt since a previous call of this
741: * method.
742: */
743: void setExpectedJavaScriptPrompt(JavascriptPrompt[] prompts)
744: throws ExpectedJavascriptPromptException;
745:
746: }
|