MARIGOLD README

(This document is continually updated, so please check frequently.)

1. What is Marigold?
2. How does Marigold work? Just provide the big-picture with an easy to understand illustration.
3. Okay, I think I understand. But can you please provide entity diagrams for me to check my understanding?
4. Enough of theory. How to use Marigold to test POJOS? Please provide a detailed step-by-step approach.
5. How to use Marigold to test EJBs?
6. How to use Marigold to test web-services?
7. What can Marigold do for me that other unit-test frameworks do not?
8. Where can I make suggestions or ask questions?

1. What is Marigold?

Marigold is an in-container "scenario-based" white-box unit-testing framework for J2EE applications. Marigold is lightweight and easy to configure, and deploy. It is meant for testing server-side J2EE components like EJBs, messaging, web-services or just POJOS running in the web server or application server.

Marigold's edge lies in facilitating "scenario-based" testing by permitting a developer/tester to test ALL scenarios that exist within an application. This is especially helpful in testing applications that contain multiple pathways and consequently a very large number of scenarios. Marigold is a proven framework -- it has been used with success in the real-world and has saved firms hundreds of man-hours.

IMPORTANT:
Marigold documentation will repeatedly refer to 3 terms -- scenario-suite, scenario, and action.
scenario-suite comprises all the scenarios to be tested, i.e., it is a collection of scenarios.
scenario refers to an execution pathway (one of several possible) in the application and comprises a sequence of actions. It can also contain config-params that are shared by all actions in the scenario.
action and its init-params: An action represents a single action that can be performed in an application. One or more actions put together constitute a scenario that can be executed by the application. An action can have 0 or more init-params. An init-param is a key-value pair that is used to input test-data to the action.
config-params: A config-param consists of a key-value pair that will be shared by all the actions in a scenario. It can be compared to an instance variable that is visible to all the instance methods in a class.

2. How does Marigold work? Just provide the big-picture with an easy to understand illustration.

Let us consider an application that has 3 actions -- A, B, and C. Furthermore, let us assume that there are 4 separate and valid execution pathways (i.e., scenarios) in which this application will be used--
1. A, B, C
2. B, A, C
3. C, B, A
4. C, A, B

In response to changing requirements, developers are having to modify the code implementing the actions. It is obviously essential that the 4 aforementioned scenarios be tested after code change. The testing process with Marigold will require us to do the following:
1. We will write a test class corresponding to each action. Let us call these test classes TestA, TestB, and TestC corresponding to actions A, B, and C respectively.
2. We will create a test-config.xml file in which each action is mapped to its corresponding test class. In our example, A gets mapped to TestA, B to TestB, C to TestC.
3. We will next create a scenario-suite.xml file. This xml file gets configured with all the scenarios we intend testing along with the test data for each action. In our example -- scenario1 (consisting of the action sequence A, B, C), scenario2 (consisting of the action sequence B, A, C), scenario3 (consisting of the action sequence C, B, A), and scenario4 (consisting of the action sequence C, A, B) are included along with the test data to be used in testing actions A, B, and C.
4. You will finally execute Marigold’s test servlet in order to execute all the 4 configured scenarios.
5. The test results get displayed in the browser.

3. Okay, I think I understand. But can you please provide entity diagrams for me to check my understanding?

Sure. Here goes.

4. Enough of theory. How to use Marigold to test POJOS? Please provide a detailed step-by-step approach. (Note: This section is sine qua non and must be followed. Also review the code in the example included separately as part of the download)

1. Download and extract marigold.jar
Download the framework. Extract the .zip or .tar.gz file to anywhere on your local drive
Copy the marigold.jar from the extracted folder to your application classpath and to WEB-INF/lib

2 . Write a test class for each action that you want to test
This test class will extend marigold.test.framework.valueObjects.Test.
The marigold.test.framework.valueObjects.Test class has the following methods that you will need to override:

setup()
a. access the input parameters that will be configured in the scenario-suite.xml file
b. setup other data that will be needed to test the action
c. validate the input parameters to ensure that you have the input data to run the test.
If required data is not available, throw a TestException(validationErrorMessage) that will be displayed on the test results page (after the test is run) in the browser.

execute()
d. invoke the class that performs the action in your application

verify()
e. verify the result of that action and return TestConstants.SUCCESS or TestConstants.FAILED
as a response that will be displayed on the test results page (after the test is run) in the browser.

cleanUp()
f. perform cleanUp() operations.

(SAMPLE test file illustrating 2 a-f)

3. Create and configure the test-config.xml file
You can store the test-config.xml file anywhere on your machine/server.

The test-config.xml will hold all configuration information needed by the framework including:

a. One <action-mappings> element (required)
The <action-mappings> element consists of 1 or more <action> elements.
Each <action> element maps the action being tested to the Test class name (already created in step 2).

b. One <env-params> element (optional)
For details about environmental parameters, refer to "Advanced" section.

Map the action to its corresponding test class in the test-config.xml file.

example:

<test-config>
<action-mappings>
<action name="Action1" class="examples.marigold.adder.tests.TestAction1"/>
<action name="Action2" class="examples.marigold.adder.tests.TestAction2"/>
</action-mappings>
<test-config>

4. Create and configure the scenario-suite.xml file
You can store the scenario-suite.xml file anywhere on your machine/server. The scenario-suite.xml file contains information about all the scenarios in the application being tested.

example:

<scenario-suite>

<scenario name="">
<config-parm name="" value=""/>
<config-parm name="" value=""/>
<config-parm name="" value=""/>

<action name="">
<init-param name="" value=""/>
<init-param name="" value=""/>
</action>

<action name="">
<init-param name="" value=""/>
<init-param name="" value=""/>
</action>

<action name="">
<init-param name="" value=""/>
<init-param name="" value=""/>
</action>

</scenario>

</scenario-suite>

5. Configure the TestServlet in your application's web.xml file
You will also supply the location of the test-suite.xml and test-config.xml files as shown below.

example:

<servlet>
<servlet-name>TestServlet</servlet-name>
<servlet-class>marigold.test.framework.TestControllerServlet</servlet-class>
<load-on-startup>1</load-on-startup>
<init-param>
<param-name>test-config</param-name>
<param-value>C:/test-config.xml</param-value>
</init-param>
<init-param>
<param-name>scenario-suite</param-name>
<param-value>C:/scenario-suite.xml</param-value>
</init-param>
</servlet>

<servlet-mapping>
<servlet-name>TestServlet</servlet-name>
<url-pattern>/TestServlet</url-pattern>
</servlet-mapping>

6. Execute the Marigold scenario-suite.
Build and deploy your web application. Invoke the servlet with http://host:port/ContextName/TestServlet

Included as part of the download is an example web-application that illustrates all these steps.

5. How to use Marigold to test EJBs?

Follow the same steps outlined in the previous section to test POJO's (NOTE: You must be familiar with the steps described earlier to test POJOS in order to use Marigold to test EJBs).

In addition, you will need to do the following:

1. Configure JNDI_FACTORY and URL in your test-config.xml

Example:

<env-params>
<param name="JNDI_FACTORY" value="weblogic.jndi.WLInitialContextFactory"/>
<param name="URL" value="t3://localhost:7001"/>
</env-params>

Substitute the name of the JNDI_FACTORY class and url as applicable to your container and application.

2. You will access JNDI_FACTORY and URL in your TestXXX class's setup()method as follows:

Example:
jndiFactory=(String)envParams.get("JNDI_FACTORY");
url=(String)envParams.get("URL");

3. Obtain the initial context and invoke your EJBs' methods

Your TestXXX class extends Marigold's Test class. The Test superclass has a static method which will
return an InitialContext object given the jndiFactory and url. Its method signature is as follows:

public static InitialContext getInitialContext(String jndiFactory,String url) throws NamingException

You can use the above method as shown in the following example to invoke your EJBs' method.

E xample:

try
{
InitialContext ctx=Test.getInitialContext(jndiFactory,url);
Object obj=ctx.lookup("ejb/AdderBean");
AdderHome home=(AdderHome) javax.rmi.PortableRemoteObject.narrow(obj,AdderHome.class);
Adder adder=home.create();
result=adder.add(2,3);
}
catch(Exception e)
{....}

6. How to use Marigold to test web-services?

Follow the same steps outlined earlier to test POJOs (NOTE: You must be familiar with the steps described earlier to test POJOS in order to use Marigold to test web-services).

In addition, you will need to do the following:

In test-config.xml, configure serviceFactory and messageFactory class names.

Example:

For Weblogic, the serviceFactory and messageFactory values are as shown below:
<env-params>
<param name="serviceFactory" value="weblogic.webservice.core.rpc.ServiceFactoryImpl"/>
<param name="messageFactory" value="weblogic.webservice.core.soap.MessageFactoryImpl"/>
</env-params>

Please refer to the appropriate test class provided in the download. It is located at ${marigold_installation}/src/examples/marigold/webService/test/TestAdderWS.java

7. What can Marigold do for me that other unit-test frameworks do not?

1. Marigold separates test data from the test code. Hence, tests can be run without having to go through repeated build/deploy cycles.

2. Marigold is a scenario-based testing framework that can be used to test all execution pathways in an application in a single pass. Other frameworks test actions in isolation and do not permit testing scenarios.

3. Marigold gives you the power to test your application from any tier -- persistence, business, web services etc. Most other frameworks force you to test from the web-tier and this is not helpful when the application is invoked by non-servlet based technologies.

4. Marigold is not tied to any specific framework or methodology.

8. Where can I make suggestions or ask questions?

The message forums at http://sourceforge.net/forum/?group_id=137140 are a good place to post either suggestions or questions. To get a response from the development team, don't hesitate to email the project admin (iyer_preeti at users. sourceforge. net)