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    }