net.joala.condition.Condition Maven / Gradle / Ivy

Go to download
/*
 * Copyright 2012 CoreMedia AG
 *
 * This file is part of Joala.
 *
 * Joala is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * Joala is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Joala.  If not, see .
 */

package net.joala.condition;

import net.joala.condition.timing.WaitTimeoutException;
import net.joala.expression.Expression;
import net.joala.expression.ExpressionEvaluationException;
import org.hamcrest.Matcher;

import javax.annotation.Nonnegative;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;

/**
 * A test condition to wait for using a given timeout. If the condition does not become true within
 * time exceptions will be thrown.
 *
 * @param  the type of the value which will be verified
 * @since 2/24/12
 */
public interface Condition {
  /**
   * Conditions need to implement this method to return the value
   * which will be checked.
   *
   * @return the value
   * @throws ExpressionEvaluationException when the actual value cannot be evaluated. Consider calling any of the
   *                                       {@code await} or {@code assume} methods to wait for the value to
   *                                       become available.
   * @see Expression#get()
   */
  @Nullable
  T get();

  /**
   * 
   * Retrieve the result of the condition as soon as it is evaluated without any exception.
   * 
   *
   * @return the retrieved value
   * @throws WaitTimeoutException if a value could not be retrieved in time
   */
  @Nullable
  T await();

  /**
   * 
   * Wait for the condition value until it fulfills the given matcher and return it.
   * 
   *
   * @param matcher matcher to use
   * @return the value which fulfills the given matcher
   * @throws WaitTimeoutException if a value could not be retrieved in time
   */
  @Nullable
  T await(@Nonnull Matcher matcher);

  /**
   * 
   * Assumes that the condition evaluates to the expected value within a given time.
   * 
   *
   * @param expected expected value
   */
  void assumeEquals(@Nullable T expected);

  /**
   * Uses {@link Matcher} to assume that a condition is met in time.
   *
   * @param matcher the matcher to use
   */
  void assumeThat(@Nonnull Matcher matcher);

  /**
   * 
   * Assert that the condition evaluates to the expected value within a given time.
   * 
   *
   * @param expected expected value
   */
  void assertEquals(@Nullable T expected);

  /**
   * Uses {@link Matcher} to assert that a condition is met in time.
   *
   * @param matcher the matcher to use
   */
  void assertThat(@Nonnull Matcher matcher);

  /**
   * 
   * Wait until the condition evaluates to the expected value within a given time.
   * 
   *
   * @param expected expected value
   */
  void waitUntilEquals(@Nullable T expected);

  /**
   * Uses {@link Matcher} to wait until a condition is met in time.
   *
   * @param matcher the matcher to use
   */
  void waitUntil(@Nonnull Matcher matcher);

  /**
   * Sets a factor to speed up or slow down tests. If < 1.0 the tests will speed up at least
   * for failures while a number > 1.0 increases the time to wait for the condition by
   * the given factor.
   *
   * @param factor factor by which to increase the timeout for this condition
   * @return a self-reference.
   */
  @Nonnull
  Condition withTimeoutFactor(@Nonnegative double factor);

  /**
   * The message to print on failure.
   *
   * @param message message with debugging hints; {@code null} to remove the message
   * @return self-reference
   */
  @Nonnull
  Condition withMessage(@Nullable String message);
}