From 04f807f1a78f96ab57b4218eb441775c8a443449 Mon Sep 17 00:00:00 2001 From: Janne Valkealahti Date: Sun, 9 Aug 2015 15:41:09 +0100 Subject: [PATCH] Add docs for testing support - Adding some docs for testing framework which has been in place for some time now. - Fixes #49 --- build.gradle | 1 + docs/src/reference/asciidoc/sm.adoc | 33 +++++++++ .../test/docs/DocsTestSampleTests.java | 71 +++++++++++++++++++ 3 files changed, 105 insertions(+) create mode 100644 spring-statemachine-test/src/test/java/org/springframework/statemachine/test/docs/DocsTestSampleTests.java diff --git a/build.gradle b/build.gradle index 811001d1..db484782 100644 --- a/build.gradle +++ b/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/' diff --git a/docs/src/reference/asciidoc/sm.adoc b/docs/src/reference/asciidoc/sm.adoc index 4e43f5de..b62cb85c 100644 --- a/docs/src/reference/asciidoc/sm.adoc +++ b/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 <>. +[[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. diff --git a/spring-statemachine-test/src/test/java/org/springframework/statemachine/test/docs/DocsTestSampleTests.java b/spring-statemachine-test/src/test/java/org/springframework/statemachine/test/docs/DocsTestSampleTests.java new file mode 100644 index 00000000..33945517 --- /dev/null +++ b/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 machine = buildMachine(); + StateMachineTestPlan plan = + StateMachineTestPlanBuilder.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 buildMachine() throws Exception { + StateMachineBuilder.Builder 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[] + +}