001 /*
002 * Created on Jun 12, 2007
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 *
014 * Copyright @2007-2010 the original author or authors.
015 */
016 package org.fest.swing.fixture;
017
018 import java.awt.Component;
019 import java.util.regex.Pattern;
020
021 /**
022 * Understands functional testing of GUI components that contains or display a group of items:
023 * <ul>
024 * <li>user input simulation</li>
025 * <li>state verification</li>
026 * <li>property value query</li>
027 * </ul>
028 * Understands simulation of user events on a <code>{@link Component}</code> that contains or displays a group of items,
029 * and verification of the state of such <code>{@link Component}</code>.
030 *
031 * @author Alex Ruiz
032 * @author Yvonne Wang
033 */
034 public interface ItemGroupFixture {
035
036 /**
037 * Returns the <code>String</code> representation of the elements in this fixture's <code>{@link Component}</code>.
038 * @return the <code>String</code> representation of the elements in this fixture's <code>Component</code>.
039 */
040 String[] contents();
041
042 /**
043 * Clears the selection in this fixture's <code>{@link Component}</code>.
044 * @return this fixture.
045 * @since 1.2
046 */
047 ItemGroupFixture clearSelection();
048
049 /**
050 * Simulates a user selecting an item in this fixture's <code>{@link Component}</code>.
051 * @param index the index of the item to select.
052 * @return this fixture.
053 */
054 ItemGroupFixture selectItem(int index);
055
056 /**
057 * Simulates a user selecting an item in this fixture's <code>{@link Component}</code>.
058 * @param value the value of the item to select. It can be a regular expression.
059 * @return this fixture.
060 */
061 ItemGroupFixture selectItem(String value);
062
063 /**
064 * Simulates a user selecting an item in this fixture's <code>{@link Component}</code>. The text of the item to
065 * select must match the given regular expression pattern.
066 * @param pattern the regular expression pattern to match.
067 * @return this fixture.
068 * @throws NullPointerException if the given regular expression pattern is <code>null</code>.
069 * @since 1.2
070 */
071 ItemGroupFixture selectItem(Pattern pattern);
072
073 /**
074 * Returns the value of an item in the <code>{@link Component}</code> managed by this fixture. If the value is not
075 * meaningful, this method will return <code>null</code>.
076 * @param index the index of the item to return.
077 * @return the value of the item under the given index, or <code>null</code> if nothing meaningful.
078 */
079 Object valueAt(int index);
080
081 /**
082 * Verifies that the value of the selected item in this fixture's <code>{@link Component}</code> matches the given
083 * value.
084 * @param value the value to match. It can be a regular expression.
085 * @return this fixture.
086 * @throws AssertionError if the selected item does not match the given value.
087 */
088 ItemGroupFixture requireSelection(String value);
089
090 /**
091 * Verifies that the value of the selected item in this fixture's <code>{@link Component}</code> matches the given
092 * regular expression pattern.
093 * @param pattern the regular expression pattern to match.
094 * @return this fixture.
095 * @throws NullPointerException if the given regular expression pattern is <code>null</code>.
096 * @throws AssertionError if the selected item does not match the given regular expression pattern.
097 * @since 1.2
098 */
099 ItemGroupFixture requireSelection(Pattern pattern);
100
101 /**
102 * Verifies that the index of the selected item in this fixture's <code>{@link Component}</code> is equal to the given
103 * value.
104 * @param index the expected selection index.
105 * @return this fixture.
106 * @throws AssertionError if the selection index is not equal to the given value.
107 * @since 1.2
108 */
109 ItemGroupFixture requireSelection(int index);
110
111 /**
112 * Verifies that this fixture's <code>{@link Component}</code> does not have a selection.
113 * @return this fixture.
114 * @throws AssertionError if this fixture's <code>Component</code> has a selection.
115 */
116 ItemGroupFixture requireNoSelection();
117
118 /**
119 * Verifies that this fixture's <code>{@link Component}</code> has the expected number of items
120 * @param expected the expected number of items.
121 * @return this fixture.
122 * @throws AssertionError if the number of items in this fixture's <code>Component</code> is not equal to the expected
123 * one.
124 * @since 1.2
125 */
126 ItemGroupFixture requireItemCount(int expected);
127 }