expectMsg... methods. Assertions and
+ * bounds concerning timing are available in the form of Within
+ * blocks.
+ * + * + * Beware of two points: + *
+ * + *
Within
+ * blocks); take care not to run tests within a single test class instance in
+ * parallel.dilated method, which uses the
+ * TestKitExtension.Settings.TestTimeFactor settable via akka.conf entry
+ * "akka.test.timefactor".getContext().getWatch(...) ).
+ */
public ActorRef watch(ActorRef ref) {
return p.watch(ref);
}
+ /**
+ * Have the testActor stop watching someone (i.e.
+ * getContext.unwatch(...)).
+ */
public ActorRef unwatch(ActorRef ref) {
return p.unwatch(ref);
}
+ /**
+ * Ignore all messages in the test actor for which the given function returns
+ * true.
+ */
public abstract class IgnoreMsg {
abstract protected boolean ignore(Object msg);
@@ -92,14 +140,63 @@ public class JavaTestKit {
}
}
+ /**
+ * Stop ignoring messages in the test actor.
+ */
public void ignoreNoMsg() {
p.ignoreNoMsg();
}
+ /**
+ * Install an AutoPilot to drive the testActor: the AutoPilot will be run for
+ * each received message and can be used to send or forward messages, etc.
+ * Each invocation must return the AutoPilot for the next round.
+ */
public void setAutoPilot(TestActor.AutoPilot pilot) {
p.setAutoPilot(pilot);
}
+ /**
+ * Obtain time remaining for execution of the innermost enclosing
+ * Within block or missing that it returns the properly dilated
+ * default for this case from settings (key
+ * "akka.test.single-expect-default").
+ */
+ public FiniteDuration remaining() {
+ return p.remaining();
+ }
+
+ /**
+ * Obtain time remaining for execution of the innermost enclosing
+ * Within block or missing that it returns the given duration.
+ */
+ public FiniteDuration remainingOr(FiniteDuration duration) {
+ return p.remainingOr(duration);
+ }
+
+ /**
+ * Execute code block while bounding its execution time between
+ * min and max. Within blocks may be
+ * nested. All methods in this trait which take maximum wait times are
+ * available in a version which implicitly uses the remaining time governed by
+ * the innermost enclosing Within block.
+ *
+ *
+ * Note that the timeout is scaled using dilated, which uses the
+ * configuration entry "akka.test.timefactor", while the min Duration is not.
+ *
+ * + *
+ *
+ * // the run() method needs to finish within 3 seconds
+ * new Within(duration("3 seconds")) {
+ * protected void run() {
+ * // ...
+ * }
+ * }
+ *
+ *
+ */
public abstract class Within {
protected abstract void run();
@@ -122,6 +219,18 @@ public class JavaTestKit {
}
}
+ /**
+ * Await until the given condition evaluates to true or the
+ * timeout expires, whichever comes first.
+ *
+ *
+ * If no timeout is given, take it from the innermost enclosing
+ * Within block.
+ *
+ * + * Note that the timeout is scaled using Duration.dilated, which uses the + * configuration entry "akka.test.timefactor". + */ public abstract class AwaitCond { protected abstract boolean cond(); @@ -150,6 +259,19 @@ public class JavaTestKit { } } + /** + * Await until the given assert does not throw an exception or the timeout + * expires, whichever comes first. If the timeout expires the last exception + * is thrown. + *
+ *
+ * If no timeout is given, take it from the innermost enclosing
+ * Within block.
+ *
+ * + * Note that the timeout is scaled using Duration.dilated, which uses the + * configuration entry "akka.test.timefactor". + */ public abstract class AwaitAssert { protected abstract void check(); @@ -171,6 +293,30 @@ public class JavaTestKit { } } + /** + * Receive one message from the test actor and assert that the given matching + * function accepts it. Wait time is bounded by the given duration, with an + * AssertionFailure being thrown in case of timeout. + *
+ * The received object as transformed by the matching function can be
+ * retrieved with the get method.
+ *
+ * Use this variant to implement more complicated or conditional processing.
+ *
+ * + *
+ *
+ * final String out = new ExpectMsg("match hint") {
+ * protected String match(Object in) {
+ * if (in instanceof Integer)
+ * return "match";
+ * else
+ * throw noMatch();
+ * }
+ * }.get(); // this extracts the received message
+ *
+ *
+ */
public abstract class ExpectMsgexpectMsgEquals(remaining(), obj), but correctly
+ * treating the timeFactor.
+ */
public expectMsgClass(remaining(), clazz), but correctly
+ * treating the timeFactor.
+ */
public expectMsgAnyOf(remaining(), obj...), but correctly
+ * treating the timeFactor.
+ */
public Object expectMsgAnyOf(Object... msgs) {
return p.expectMsgAnyOf(Util.immutableSeq(msgs));
}
+ /**
+ * Receive one message from the test actor and assert that it equals one of
+ * the given objects. Wait time is bounded by the given duration, with an
+ * AssertionFailure being thrown in case of timeout.
+ *
+ * @return the received object
+ */
public Object expectMsgAnyOf(FiniteDuration max, Object... msgs) {
return p.expectMsgAnyOf(max, Util.immutableSeq(msgs));
}
+ /**
+ * Same as expectMsgAllOf(remaining(), obj...), but correctly
+ * treating the timeFactor.
+ */
public Object[] expectMsgAllOf(Object... msgs) {
return (Object[]) p.expectMsgAllOf(Util.immutableSeq(msgs)).toArray(Util.classTag(Object.class));
}
+ /**
+ * Receive a number of messages from the test actor matching the given number
+ * of objects and assert that for each given object one is received which
+ * equals it and vice versa. This construct is useful when the order in which
+ * the objects are received is not fixed. Wait time is bounded by the given
+ * duration, with an AssertionFailure being thrown in case of timeout.
+ */
public Object[] expectMsgAllOf(FiniteDuration max, Object... msgs) {
return (Object[]) p.expectMsgAllOf(max, Util.immutableSeq(msgs)).toArray(Util.classTag(Object.class));
}
+ /**
+ * Same as expectMsgAnyClassOf(remaining(), obj...), but
+ * correctly treating the timeFactor.
+ */
@SuppressWarnings("unchecked")
public expectNoMsg(remaining()), but correctly treating the
+ * timeFactor.
+ */
public void expectNoMsg() {
p.expectNoMsg();
}
+ /**
+ * Assert that no message is received for the specified time.
+ */
public void expectNoMsg(FiniteDuration max) {
p.expectNoMsg(max);
}
+ /**
+ * Same as receiveN(n, remaining()), but correctly treating the
+ * timeFactor.
+ */
public Object[] receiveN(int n) {
return (Object[]) p.receiveN(n).toArray(Util.classTag(Object.class));
}
+ /**
+ * Receive N messages in a row before the given deadline.
+ */
public Object[] receiveN(int n, FiniteDuration max) {
return (Object[]) p.receiveN(n, max).toArray(Util.classTag(Object.class));
}
+ /**
+ * Receive one message from the internal queue of the TestActor. If the given
+ * duration is zero, the queue is polled (non-blocking).
+ *
+ *
+ * This method does NOT automatically scale its Duration parameter!
+ */
+ public Object receiveOne(Duration max) {
+ return p.receiveOne(max);
+ }
+
+ /**
+ * Receive a series of messages until one does not match the given
+ * match function or the idle timeout is met (disabled by
+ * default) or the overall maximum duration is elapsed. Returns the sequence
+ * of messages.
+ *
+ *
+ * Note that it is not an error to hit the max duration in this
+ * case.
+ *
+ *
+ * One possible use of this method is for testing whether messages of certain
+ * characteristics are generated at a certain rate.
+ */
public abstract class ReceiveWhile
+ *
+ * If the occurrences is set to Integer.MAX_VALUE,
+ * no tracking is done.
+ */
public abstract class EventFilter