org.springframework.webflow.test
Class AbstractFlowExecutionTests

java.lang.Object
  junit.framework.Assert
      junit.framework.TestCase
          org.springframework.test.AbstractSpringContextTests
              org.springframework.test.AbstractDependencyInjectionSpringContextTests
                  org.springframework.test.AbstractTransactionalSpringContextTests
                      org.springframework.webflow.test.AbstractFlowExecutionTests

All Implemented Interfaces:

junit.framework.Test

public abstract class AbstractFlowExecutionTests
extends org.springframework.test.AbstractTransactionalSpringContextTests

Base class for integration tests that verify a flow executes as expected. Flow execution tests captured by subclasses should test that a flow responds to all supported transition criteria correctly, transitioning to the correct states and producing the appropriate results on the occurence of possible "external" (user) events.

More specifically, a typical flow execution test case will test:

• That the flow execution starts as expected given a source event with potential input parameters (see startFlow(Event)).
• That given the set of supported transition criteria for a given state, that the state executes the appropriate transition when an event is signaled (with potential input parameters). A test case should be coded for each logical event that can occur, where an event drives a possible path through the flow. The goal should be to exercise all possible paths of the flow.
• That given a transition that leads to an interactive state type (a view state or an end state), that the view descriptor returned to the client matches what was expected and the current state of the flow matches what is expected.

A flow execution test can effectively automate and validate the orchestration required to drive an end-to-end business process that spans several steps involving the user. Such tests are a good way to test your system top-down starting at the web-tier and pushing through all the way to the DB without having to deploy to a servlet or portlet container. Because these tests are typically end-to-end integration tests that involve a transactional resource such a database, this class subclasses Spring's AbstractTransactionalSpringContextTests to take advantage of its automatic transaction management and rollback capabilites. If you do not need those capabilities, you must call setDependencyCheck(false) in your test's constructor to turn off dependency checking for the transaction manager property.

Author:

Keith Donald

Field Summary

Fields inherited from class org.springframework.test.AbstractTransactionalSpringContextTests

transactionManager, transactionStatus

Fields inherited from class org.springframework.test.AbstractDependencyInjectionSpringContextTests

applicationContext, managedVariableNames

Fields inherited from class org.springframework.test.AbstractSpringContextTests

logger

Constructor Summary

AbstractFlowExecutionTests()

Method Summary

protected void	assertActiveFlowEquals(java.lang.String expectedActiveFlowId) Assert that the active flow session is for the flow with the provided id.
protected void	assertCurrentStateEquals(java.lang.String expectedCurrentStateId) Assert that the current state of the flow execution equals the provided state id.
protected void	assertLastEventEquals(java.lang.String expectedEventId) Assert that the last supported event that occured in the flow execution equals the provided event.
void	assertModelAttributeCollectionSize(int expectedSize, java.lang.String attributeName, ViewDescriptor viewDescriptor) Assert that the view descriptor contains the specified collection model attribute with the provided expected size.
void	assertModelAttributeEquals(java.lang.String expectedValue, java.lang.String attributeName, ViewDescriptor viewDescriptor) Assert that the view descriptor contains the specified model attribute with the provided expected value.
void	assertModelAttributeNotNull(java.lang.String attributeName, ViewDescriptor viewDescriptor) Assert that the view descriptor contains the specified model attribute.
void	assertModelAttributeNull(java.lang.String attributeName, ViewDescriptor viewDescriptor) Assert that the view descriptor does not contain the specified model attribute.
void	assertViewNameEquals(java.lang.String expectedViewName, ViewDescriptor viewDescriptor) Assert that the view name equals the provided value.
protected Event	event(java.lang.String eventId) Convenience factory method that returns an event instance for this test client with the specified id.
protected Event	event(java.lang.String eventId, java.util.Map parameters) Convenience factory method that returns an event instance for this test client with the specified id and parameters
protected abstract java.lang.String	flowId() Subclasses should override to return the flowId whose execution should be tested.
protected Flow	getFlow() Get the singleton flow definition whose execution is being tested.
protected FlowExecutionContext	getFlowContext() Returns the ongoing flow execution for this test.
protected FlowLocator	getFlowLocator() Returns the flow locator used to resolve the Flow to be tested by id.
protected void	onSetupFlowExecution(FlowExecution flowExecution) Hook method where you can do additional setup of a flow execution before it is started, like register an execution listener.
protected void	onSetUpInTransaction()
protected void	onSetUpInTransactionalFlowTest() Hook method subclasses can implement to do additional setup.
protected void	setFlow(Flow flow) Set the flow definition whose execution is being tested.
protected void	setFlowBuilder(FlowBuilder flowBuilder) Set the flow definition to be tested to the Flow built by the specified builder.
protected ViewDescriptor	signalEvent(Event event) Signal an occurence of an event in the current state of the flow execution being tested.
protected ViewDescriptor	startFlow() Start a new flow execution for the flow definition that is being tested.
protected ViewDescriptor	startFlow(Event event) Start a new flow execution for the flow definition that is being tested.

Methods inherited from class org.springframework.test.AbstractTransactionalSpringContextTests

endTransaction, onSetUp, onSetUpBeforeTransaction, onTearDown, onTearDownAfterTransaction, onTearDownInTransaction, setComplete, setDefaultRollback, setTransactionManager

Methods inherited from class org.springframework.test.AbstractDependencyInjectionSpringContextTests

contextKey, getConfigLocations, getLoadCount, initManagedVariableNames, isDependencyCheck, isPopulateProtectedVariables, loadContextLocations, populateProtectedVariables, setDependencyCheck, setDirty, setPopulateProtectedVariables, setUp, tearDown

Methods inherited from class org.springframework.test.AbstractSpringContextTests

contextKeyString, getContext, hasCachedContext, loadContext, setDirty

Methods inherited from class junit.framework.TestCase

countTestCases, createResult, getName, run, run, runBare, runTest, setName, toString

Methods inherited from class junit.framework.Assert

assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertFalse, assertFalse, assertNotNull, assertNotNull, assertNotSame, assertNotSame, assertNull, assertNull, assertSame, assertSame, assertTrue, assertTrue, fail, fail

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractFlowExecutionTests

public AbstractFlowExecutionTests()

Method Detail

getFlowLocator

protected FlowLocator getFlowLocator()

Returns the flow locator used to resolve the Flow to be tested by id.

onSetUpInTransaction

protected final void onSetUpInTransaction()
                                   throws java.lang.Exception

Overrides:

onSetUpInTransaction in class org.springframework.test.AbstractTransactionalSpringContextTests

Throws:

java.lang.Exception

onSetUpInTransactionalFlowTest

protected void onSetUpInTransactionalFlowTest()

Hook method subclasses can implement to do additional setup. Called after the transition has been activated and the flow locator has been set.

getFlow

protected Flow getFlow()
                throws ServiceLookupException

Get the singleton flow definition whose execution is being tested.

Returns:

the singleton flow definition

Throws:

ServiceLookupException - if the flow identified by flowId() could not be resolved (if this.flow was null)

setFlow

protected void setFlow(Flow flow)

Set the flow definition whose execution is being tested.

Parameters:

flow - the singleton flow definition

flowId

protected abstract java.lang.String flowId()

Subclasses should override to return the flowId whose execution should be tested.

Returns:

the flow id, whose execution is to be tested

setFlowBuilder

protected void setFlowBuilder(FlowBuilder flowBuilder)

Set the flow definition to be tested to the Flow built by the specified builder.

Parameters:

flowBuilder - the flow builder

startFlow

protected ViewDescriptor startFlow()

Start a new flow execution for the flow definition that is being tested.

Returns:

the model and view returned as a result of starting the flow (returned when the first view state is entered)

event

protected Event event(java.lang.String eventId)

Convenience factory method that returns an event instance for this test client with the specified id.

Parameters:

eventId - the event id

Returns:

the event

event

protected Event event(java.lang.String eventId,
                      java.util.Map parameters)

Convenience factory method that returns an event instance for this test client with the specified id and parameters

Parameters:

eventId - the event id

parameters - the event parameters

Returns:

the event

startFlow

protected ViewDescriptor startFlow(Event event)

Start a new flow execution for the flow definition that is being tested.

Parameters:

event - the starting event

Returns:

the model and view returned as a result of starting the flow (returned when the first view state is entered)

onSetupFlowExecution

protected void onSetupFlowExecution(FlowExecution flowExecution)

Hook method where you can do additional setup of a flow execution before it is started, like register an execution listener.

Parameters:

flowExecution - the flow execution

signalEvent

protected ViewDescriptor signalEvent(Event event)

Signal an occurence of an event in the current state of the flow execution being tested.

Note: signaling an event will cause state transitions to occur in a chain UNTIL control is returned to the caller. Control will be returned once a view state is entered or an end state is entered and the flow terminates. Action states are executed without returning control, as their result always triggers another state transition, executed internally. Action states can also be executed in a chain like fashion (e.g. action state 1 (result), action state 2 (result), action state 3 (result), view state ).

If you wish to verify expected behavior on each state transition (and not just when the view state triggers return of control back to the client), you have a few options:

First, you can always write a standalone unit test for the Action implementation. There you can verify that the action executes its core logic and responds to any exceptions it must handle. When you do this, you may mock or stub out services the Action implementation needs that are expensive to initialize. You can also verify there that the action puts everything in the flow or request scope it was supposed to (to meet its contract with the view it is prepping for display, if it's a view setup action).

Second, you can attach a FlowExecutionListener to the ongoing flow execution at any time within your test code, which receives callbacks on each state transition (among other points). To add a listener, call getFlowExecution().getListenerList().add(myListener), where myListener is a class that implements the FlowExecutionListener interface. It is recommended you extend FlowExecutionListenerAdapter and only override what you need.

Parameters:

event - the event to signal

Returns:

the model and view, returned once control is returned to the client (occurs when the flow enters a view state, or an end state)

getFlowContext

protected FlowExecutionContext getFlowContext()
                                       throws java.lang.IllegalStateException

Returns the ongoing flow execution for this test.

Returns:

the flow execution

Throws:

java.lang.IllegalStateException - the execution has not been started

assertActiveFlowEquals

protected void assertActiveFlowEquals(java.lang.String expectedActiveFlowId)

Assert that the active flow session is for the flow with the provided id.

Parameters:

expectedActiveFlowId - the flow id that should have a session active in the tested flow execution

assertCurrentStateEquals

protected void assertCurrentStateEquals(java.lang.String expectedCurrentStateId)

Assert that the current state of the flow execution equals the provided state id.

Parameters:

expectedCurrentStateId - the expected current state

assertLastEventEquals

protected void assertLastEventEquals(java.lang.String expectedEventId)

Assert that the last supported event that occured in the flow execution equals the provided event.

Parameters:

expectedEventId - the expected event

assertViewNameEquals

public void assertViewNameEquals(java.lang.String expectedViewName,
                                 ViewDescriptor viewDescriptor)

Assert that the view name equals the provided value.

Parameters:

expectedViewName - the expected name

viewDescriptor - the view descriptor to assert

assertModelAttributeEquals

public void assertModelAttributeEquals(java.lang.String expectedValue,
                                       java.lang.String attributeName,
                                       ViewDescriptor viewDescriptor)

Assert that the view descriptor contains the specified model attribute with the provided expected value.

Parameters:

expectedValue - the expected value

attributeName - the attribute name

viewDescriptor - the view descriptor to assert

assertModelAttributeCollectionSize

public void assertModelAttributeCollectionSize(int expectedSize,
                                               java.lang.String attributeName,
                                               ViewDescriptor viewDescriptor)

Assert that the view descriptor contains the specified collection model attribute with the provided expected size.

Parameters:

expectedSize - the expected size

attributeName - the collection attribute name

viewDescriptor - the view descriptor to assert

assertModelAttributeNotNull

public void assertModelAttributeNotNull(java.lang.String attributeName,
                                        ViewDescriptor viewDescriptor)

Assert that the view descriptor contains the specified model attribute.

Parameters:

attributeName - the attribute name

viewDescriptor - the view descriptor to assert

assertModelAttributeNull

public void assertModelAttributeNull(java.lang.String attributeName,
                                     ViewDescriptor viewDescriptor)

Assert that the view descriptor does not contain the specified model attribute.

Parameters:

attributeName - the attribute name

viewDescriptor - the view descriptor to assert