Add docs for testing support

- Adding some docs for testing framework which has been
  in place for some time now.
- Fixes #49

build.gradle

@@ -246,6 +246,7 @@ configure(rootProject) {
 
 	task copyDocsSamples(type: Copy) {
 		from 'spring-statemachine-core/src/test/java/org/springframework/statemachine/docs'
+		from 'spring-statemachine-test/src/test/java/org/springframework/statemachine/test/docs'
 		from 'spring-statemachine-recipes/src/test/java/org/springframework/statemachine/recipes/docs'
 		from 'spring-statemachine-samples/src/main/java/'
 		from 'spring-statemachine-samples/washer/src/main/java/'

docs/src/reference/asciidoc/sm.adoc

@@ -730,3 +730,36 @@ only one implementation currently exists based on `Zookeeper`.
 Current technical documentation of a `Zookeeker` based distributed
 state machine can be found from an appendice <<appendices-zookeeper>>.
 
+[[sm-test]]
+== Testing Support
+We have also added a set of utility classes to easy testing of a state
+machine instances. These are used in a framework itself but are also
+very useful for end users.
+
+`StateMachineTestPlanBuilder` is used to build a `StateMachineTestPlan`
+which then have one method `test()` which runs a plan.
+`StateMachineTestPlanBuilder` contains a fluent builder api to add
+steps into a plan and during these steps you can send events and check
+various conditions like state changes, transitions and extended state
+variables.
+
+Lets take a simple `StateMachine` build using below example:
+
+[source,java,indent=0]
+----
+include::samples/DocsTestSampleTests.java[tags=snippetB]
+----
+
+In below test plan we have two steps, first we check that initial
+state `S1` is indeed set, secondly we send an event `E1` and expect
+one state change to happen and machine to end up into a state `S1`.
+
+[source,java,indent=0]
+----
+include::samples/DocsTestSampleTests.java[tags=snippetA]
+----
+
+These utilities are also used within a framework to test distributed
+state machine features and multiple machines can be added to a plan.
+If multiple machines are added then it is also possible to choose if
+event is sent to particular, random or all machines.

spring-statemachine-test/src/test/java/org/springframework/statemachine/test/docs/DocsTestSampleTests.java

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2015 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.statemachine.test.docs;
+
+import org.junit.Test;
+import org.springframework.core.task.SyncTaskExecutor;
+import org.springframework.statemachine.StateMachine;
+import org.springframework.statemachine.config.StateMachineBuilder;
+import org.springframework.statemachine.test.StateMachineTestPlan;
+import org.springframework.statemachine.test.StateMachineTestPlanBuilder;
+
+public class DocsTestSampleTests {
+
+	@Test
+	public void sample1() throws Exception {
+// tag::snippetA[]
+		StateMachine<String, String> machine = buildMachine();
+		StateMachineTestPlan<String, String> plan =
+				StateMachineTestPlanBuilder.<String, String>builder()
+					.defaultAwaitTime(2)
+					.stateMachine(machine)
+					.step()
+						.expectStates("SI")
+						.and()
+					.step()
+						.sendEvent("E1")
+						.expectStateChanged(1)
+						.expectStates("S1")
+						.and()
+					.build();
+		plan.test();
+// end::snippetA[]
+	}
+
+// tag::snippetB[]
+	private StateMachine<String, String> buildMachine() throws Exception {
+		StateMachineBuilder.Builder<String, String> builder = StateMachineBuilder.builder();
+
+		builder.configureConfiguration()
+			.withConfiguration()
+				.taskExecutor(new SyncTaskExecutor())
+				.autoStartup(true);
+
+		builder.configureStates()
+				.withStates()
+					.initial("SI")
+					.state("S1");
+
+		builder.configureTransitions()
+				.withExternal()
+					.source("SI").target("S1")
+					.event("E1");
+
+		return builder.build();
+	}
+// end::snippetB[]
+
+}