001 /*
002 * Created on Oct 20, 2006
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 @2006-2010 the original author or authors.
015 */
016 package org.fest.swing.fixture;
017
018 import static org.fest.assertions.Assertions.assertThat;
019 import static org.fest.swing.driver.ComponentDriver.propertyName;
020 import static org.fest.swing.fixture.ComponentFixtureValidator.notNullRobot;
021 import static org.fest.swing.fixture.ComponentFixtureValidator.notNullTarget;
022 import static org.fest.swing.format.Formatting.format;
023 import static org.fest.swing.query.ComponentBackgroundQuery.backgroundOf;
024 import static org.fest.swing.query.ComponentFontQuery.fontOf;
025 import static org.fest.swing.query.ComponentForegroundQuery.foregroundOf;
026
027 import java.awt.Component;
028
029 import org.fest.swing.core.Robot;
030 import org.fest.swing.core.Settings;
031 import org.fest.swing.driver.ComponentDriver;
032 import org.fest.swing.edt.GuiActionRunner;
033 import org.fest.swing.exception.ComponentLookupException;
034
035 /**
036 * Understands functional testing of <code>{@link Component}</code>s:
037 * <ul>
038 * <li>user input simulation</li>
039 * <li>state verification</li>
040 * <li>property value query</li>
041 * </ul>
042 *
043 * @param <T> the type of <code>Component</code> that this fixture can manage.
044 *
045 * @author Alex Ruiz
046 * @author Yvonne Wang
047 */
048 public abstract class ComponentFixture<T extends Component> {
049
050 /** Name of the property "font". */
051 protected static final String FONT_PROPERTY = "font";
052
053 /** Name of the property "background". */
054 protected static final String BACKGROUND_PROPERTY = "background";
055
056 /** Name of the property "foreground". */
057 protected static final String FOREGROUND_PROPERTY = "foreground";
058
059 /** Performs simulation of user events on <code>{@link #target}</code> */
060 public final Robot robot;
061
062 /**
063 * This fixture's <code>{@link Component}</code>.
064 * <p>
065 * <strong>Note:</strong> Access to this GUI component <em>must</em> be executed in the event dispatch thread. To do
066 * so, please execute a <code>{@link org.fest.swing.edt.GuiQuery GuiQuery}</code> or
067 * <code>{@link org.fest.swing.edt.GuiTask GuiTask}</code> (depending on what you need to do,) inside a
068 * <code>{@link GuiActionRunner}</code>. To learn more about Swing threading, please read the
069 * <a href="http://java.sun.com/javase/6/docs/api/javax/swing/package-summary.html#threading" target="_blank">Swing Threading Policy</a>.
070 * </p>
071 */
072 public final T target;
073
074 /**
075 * Creates a new <code>{@link ComponentFixture}</code>.
076 * @param robot performs simulation of user events on a <code>Component</code>.
077 * @param type the type of the <code>Component</code> to find using the given <code>RobotFixture</code>.
078 * @throws NullPointerException if <code>robot</code> is <code>null</code>.
079 * @throws NullPointerException if <code>type</code> is <code>null</code>.
080 * @throws ComponentLookupException if a matching component could not be found.
081 * @throws ComponentLookupException if more than one matching component is found.
082 */
083 public ComponentFixture(Robot robot, Class<? extends T> type) {
084 this(robot, findTarget(robot, type));
085 }
086
087 private static <C extends Component> C findTarget(Robot robot, Class<? extends C> type) {
088 validate(robot, type);
089 return robot.finder().findByType(type, requireShowing(robot));
090 }
091
092 /**
093 * Validates that the given <code>{@link ComponentDriver}</code> is not <code>null</code>.
094 * @param driver the {@code ComponentDriver} to validate.
095 * @throws NullPointerException if {@code driver} is <code>null</code>.
096 */
097 protected static void validateNotNull(ComponentDriver driver) {
098 if (driver == null) throw new NullPointerException("The driver should not be null");
099 }
100
101 /**
102 * Creates a new <code>{@link ComponentFixture}</code>.
103 * @param robot performs simulation of user events on a <code>Component</code>.
104 * @param name the name of the <code>Component</code> to find using the given <code>RobotFixture</code>.
105 * @param type the type of the <code>Component</code> to find using the given <code>RobotFixture</code>.
106 * @throws NullPointerException if <code>robot</code> is <code>null</code>.
107 * @throws NullPointerException if <code>type</code> is <code>null</code>.
108 * @throws ComponentLookupException if a matching component could not be found.
109 * @throws ComponentLookupException if more than one matching component is found.
110 */
111 public ComponentFixture(Robot robot, String name, Class<? extends T> type) {
112 this(robot, findTarget(robot, name, type));
113 }
114
115 private static <C extends Component> C findTarget(Robot robot, String name, Class<? extends C> type) {
116 validate(robot, type);
117 return robot.finder().findByName(name, type, requireShowing(robot));
118 }
119
120 private static void validate(Robot robot, Class<?> type) {
121 notNullRobot(robot);
122 if (type == null) throw new NullPointerException("The type of component to look for should not be null");
123 }
124
125 /**
126 * Returns whether showing components are the only ones participating in a component lookup. The returned value is
127 * obtained from the <code>{@link Settings#componentLookupScope() component lookup scope}</code> stored in this
128 * fixture's <code>{@link Robot}</code>.
129 * @return <code>true</code> if only showing components can participate in a component lookup, <code>false</code>
130 * otherwise.
131 */
132 protected boolean requireShowing() {
133 return requireShowing(robot);
134 }
135
136 private static boolean requireShowing(Robot robot) {
137 return robot.settings().componentLookupScope().requireShowing();
138 }
139
140 /**
141 * Creates a new <code>{@link ComponentFixture}</code>.
142 * @param robot performs simulation of user events on the given <code>Component</code>.
143 * @param target the <code>Component</code> to be managed by this fixture.
144 * @throws NullPointerException if <code>robot</code> is <code>null</code>.
145 * @throws NullPointerException if <code>target</code> is <code>null</code>.
146 */
147 public ComponentFixture(Robot robot, T target) {
148 this.robot = notNullRobot(robot);
149 this.target = notNullTarget(target);
150 }
151
152 /**
153 * Returns a fixture that verifies the font of this fixture's <code>{@link Component}</code>.
154 * @return a fixture that verifies the font of this fixture's <code>Component</code>.
155 */
156 public final FontFixture font() {
157 return new FontFixture(fontOf(target), propertyName(target, FONT_PROPERTY));
158 }
159
160 /**
161 * Returns a fixture that verifies the background color of this fixture's <code>{@link Component}</code>.
162 * @return a fixture that verifies the background color of this fixture's <code>Component</code>.
163 */
164 public final ColorFixture background() {
165 return new ColorFixture(backgroundOf(target), propertyName(target, BACKGROUND_PROPERTY));
166 }
167
168 /**
169 * Returns a fixture that verifies the foreground color of this fixture's <code>{@link Component}</code>.
170 * @return a fixture that verifies the foreground color of this fixture's <code>Component</code>.
171 */
172 public final ColorFixture foreground() {
173 return new ColorFixture(foregroundOf(target), propertyName(target, FOREGROUND_PROPERTY));
174 }
175
176 /**
177 * Returns this fixture's <code>{@link Component}</code> casted to the given sub-type.
178 * @param <C> enforces that the given type is a sub-type of the managed <code>Component</code>.
179 * @param type the type that the managed <code>Component</code> will be casted to.
180 * @return this fixture's <code>Component</code> casted to the given sub-type.
181 * @throws AssertionError if this fixture's <code>Component</code> is not an instance of the given type.
182 */
183 public final <C extends T> C targetCastedTo(Class<C> type) {
184 assertThat(target).as(format(target)).isInstanceOf(type);
185 return type.cast(target);
186 }
187
188 /**
189 * Returns the GUI component in this fixture (same as <code>{@link #target}</code>.)
190 * <p>
191 * <strong>Note:</strong> Access to the GUI component returned by this method <em>must</em> be executed in the event
192 * dispatch thread. To do so, please execute a <code>{@link org.fest.swing.edt.GuiQuery GuiQuery}</code> or
193 * <code>{@link org.fest.swing.edt.GuiTask GuiTask}</code> (depending on what you need to do,) inside a
194 * <code>{@link GuiActionRunner}</code>. To learn more about Swing threading, please read the
195 * <a href="http://java.sun.com/javase/6/docs/api/javax/swing/package-summary.html#threading" target="_blank">Swing Threading Policy</a>.
196 * </p>
197 * @return the GUI component in this fixture.
198 */
199 public final T component() {
200 return target;
201 }
202 }