FlowDefinition definition = ...
    FlowExecutionFactory factory = ...
    FlowExecution execution = factory.createFlowExecution(definition);
 	  	 	

Once created, a new flow execution is initially inactive, waiting to be started. Once started a flow execution becomes active by entering its startState. From there it continues executing until it enters a state where user input is required to continue or it terminates.

    MutableAttributeMap input = ...
    ExternalContext context = ...
    ViewSelection startingView = execution.start(input, context);
 	  	 	

When a flow execution reaches a state where input is required to continue it is said to have paused, where it waits in that state for the input to be provided. After pausing the ViewSelection returned is typically used to issue a response to the user that provides a vehicle for collecting the required input.

User input is provided by signaling an event that resumes the flow execution by communicating what user action was taken. Attributes of the signal event request form the basis for user input. The flow execution resumes by consuming the event.

Once a flow execution has resumed it continues executing until it again enters a state where more input is needed or it terminates. Once a flow execution has terminated it becomes inactive and cannot be resumed.

    ExternalContext context = ...
    ViewSelection nextView = execution.signalEvent("submit", context);
    if (execution.isActive()) {
        // still active but paused
    } else {
        // has ended
    }
 	  	 	

As outlined, a flow execution can go through a number of phases throughout its lifecycle; for example, created, active, paused, ended.

Spring Web Flow gives you the ability to observe the lifecycle of an executing flow by implementing a FlowExecutionListener.

The different phases of a flow execution are shown graphically below:

Flow execution lifecycle

The Spring Web Flow flow execution implementation is org.springframework.webflow.engine.impl.FlowExecutionImpl, typically created by a FlowExecutionImplFactory (a FlowExecutionFactory implementation). The configurable properties of this flow execution implementation are summarized below:

The configurable constructs related to flow execution are shown graphically below:

Flow execution

    FlowExecutionFactory factory = new FlowExecutionImplFactory();
    factory.setExecutionListeners(...);
    factory.setExecutionAttributes(...);
    FlowExecution execution = factory.createFlowExecution(definition);
 	  	 	

To help illustrate testing a flow execution, first consider the following flow definition to search a phonebook for contacts:

Phonebook Search Flow - State Diagram

The corresponding XML-based flow definition implementation:

    <?xml version="1.0" encoding="UTF-8"?>
    <flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd">
                             
        <start-state idref="enterCriteria"/>
    
        <view-state id="enterCriteria" view="searchCriteria">
            <render-actions>
                <action bean="formAction" method="setupForm"/>
            </render-actions>
            <transition on="search" to="displayResults">
                <action bean="formAction" method="bindAndValidate"/>
            </transition>
        </view-state>
    
        <view-state id="displayResults" view="searchResults">
            <render-actions>
                <bean-action bean="phonebook" method="search">
                    <method-arguments>
                        <argument expression="flowScope.searchCriteria"/>
                    </method-arguments>
                    <method-result name="results"/>
               </bean-action>
            </render-actions>
            <transition on="newSearch" to="enterCriteria"/>
            <transition on="select" to="browseDetails"/>
        </view-state>
	    
        <subflow-state id="browseDetails" flow="detail-flow">
            <attribute-mapper>
                <input-mapper>
                    <mapping source="requestParameters.id" target="id" from="string" to="long"/>
                </input-mapper>
            </attribute-mapper>
            <transition on="finish" to="displayResults"/>
        </subflow-state>
    
    </flow>   		 	
   		 	

Above you see a flow with three (3) states that execute these behaviors, respectively:

From this behavior narrative the following assertable test scenarios can be extracted:

To assist with writing these assertions Spring Web Flow ships with JUnit-based flow execution test support within the org.springframwork.webflow.test package. These base test classes are indicated below:

The completed test for this example extending AbstractXmlFlowExecutionTests is shown below:

    public class SearchFlowExecutionTests extends AbstractXmlFlowExecutionTests {

        public void testStartFlow() {
            ApplicationView view = applicationView(startFlow());
            assertCurrentStateEquals("enterCriteria");
            assertViewNameEquals("searchCriteria", view);
            assertModelAttributeNotNull("searchCriteria", view);
        }
        
        public void testCriteriaSubmitSuccess() {
            startFlow();
            MockParameterMap parameters = new MockParameterMap();
            parameters.put("firstName", "Keith");
            parameters.put("lastName", "Donald");
            ApplicationView view = applicationView(signalEvent("search", parameters));
            assertCurrentStateEquals("displayResults");
            assertViewNameEquals("searchResults", view);
            assertModelAttributeCollectionSize(1, "results", view);
        }
        
        public void testCriteriaSubmitError() {
            startFlow();
            signalEvent("search");
            assertCurrentStateEquals("enterCriteria");
        }
        
        public void testNewSearch() {
            testCriteriaSubmitSuccess();
            ApplicationView view = applicationView(signalEvent("newSearch"));
            assertCurrentStateEquals("enterCriteria");
            assertViewNameEquals("searchCriteria", view);
        }
        
        public void testSelectValidResult() {
            testCriteriaSubmitSuccess();
            MockParameterMap parameters = new MockParameterMap();
            parameters.put("id", "1");
            ApplicationView view = applicationView(signalEvent("select", parameters));
            assertCurrentStateEquals("displayResults");
            assertViewNameEquals("searchResults", view);
            assertModelAttributeCollectionSize(1, "results", view);
        }

        @Override
        protected FlowDefinitionResource getFlowDefinitionResource() {
            return createFlowDefinitionResource("src/main/webapp/WEB-INF/flows/search-flow.xml");
        }
        
        @Override
        protected void registerMockServices(MockFlowServiceLocator serviceRegistry) {
            Flow mockDetailFlow = new Flow("detail-flow");
            mockDetailFlow.setInputMapper(new AttributeMapper() {
                public void map(Object source, Object target, Map context) {
                    assertEquals("id of value 1 not provided as input by calling search flow", new Long(1), ((AttributeMap)source).get("id"));
                }
            });
            // test responding to finish result
            new EndState(mockDetailFlow, "finish");
            
            serviceRegistry.registerSubflow(mockDetailFlow);
            serviceRegistry.registerBean("phonebook", new ArrayListPhoneBook());
        }
    }
        

With a well-written flow execution test passing that covers the controller behavior scenarios possible for your flow you have concrete evidence the flow will execute as expected when deployed in a container.

Go for Green

The previous example shows how to test a flow execution in relative isolation with a mock service layer and mock subflows. Flow execution testing against a real service-layer and real subflows is also supported.

The next example shows how the createFlowServiceLocator method can be overridden to create the service-layer using a Spring application context:

    public class SearchFlowExecutionTests extends AbstractXmlFlowExecutionTests {

        ...
        
        @Override
        protected FlowDefinitionResource getFlowDefinitionResource() {
            return createFlowDefinitionResource("src/main/webapp/WEB-INF/flows/search-flow.xml");
        }
        
        @Override
        protected FlowServiceLocator createFlowServiceLocator() {
        
            // create a context to host our middle tier services
            ApplicationContext context =
                new ClassPathXmlApplicationContext(new String[] {
                   "classpath:service-layer-config.xml",
                   "classpath:data-access-layer-config.xml"
                });
            
            // create a registry for our flow definitions being tested
            FlowDefinitionRegistry registry = new FlowDefinitionRegistryImpl();
            
            // initialize the service locator
            DefaultFlowServiceLocator locator = new DefaultFlowServiceLocator(registry, context);
            
            // perform subflow definition registration with the help of a registrar
            XmlFlowRegistrar registrar = new XmlFlowRegistrar(locator);
            registrar.addResource(createFlowDefinitionResource("/WEB-INF/flows/search-flow.xml"));
            registrar.addResource(createFlowDefinitionResource("/WEB-INF/flows/detail-flow.xml"));
            registrar.registerFlowDefinitions(registry);
            
            return locator;
        }
    }