My favorites | Sign in
Project Home Downloads Wiki Issues Source
READ-ONLY: This project has been archived. For more information see this post.
Search
for
IntroductionForDevelopers  

Featured
Updated Jan 9, 2012 by lipinski...@gmail.com

Introduction

The whole idea of Tumbler is to help you think about the software you're writing. It has an extremely simple interface, so it won't take you more than 5 seconds to learn it, but it can completely change the way you develop code.

But before I show you how to use it, see how to install it.

Installation

There are two ways you can use Tumbler - either by manually adding it your project's classpath, or by using maven.

Manual installation

There's not much you need to do to start using Tumbler. Just grab a jar file from the Downloads section of the right tab and place it on your project's classpath. That's all, at least for the beginning. You can now import statically tumbler.Tumbler class' methods like this: import static tumbler.Tumbler.*;

Maven installation

This is trivial. Just add to the dependencies section of the pom.xml file for your project:

<dependency>
	<groupId>pl.pragmatists.tumbler</groupId>
	<artifactId>tumbler</artifactId>
	<version>0.4.1</version>
 </dependency>

and you're done. Both new JUnit (4.10) and proper FreeMarker are automatically downloaded, so you don't need to worry about them!

Usage

So, first you don't use word test anymore - now you're writing Stories and their Scenarios. So annotate your Test class with @Story. You'll also need to add @RunWith(TumblerRunner.class) annotation to your class to let JUnit use Tumbler. If you're forced to use JUnit4.4, use @RunWith(JUnit44TumblerRunner.class) instead. Now, each test in your Story must have @Scenario annotation, so that Tumbler knows which methods are scenarios and which are just helpers. Within your scenarios use Given(), When() and Then() methods to specify the scenario - i.e. define what you plan to do there. It's a good idea to first define scenarios, so that you know exactly how you're going to develop your code. If you do that, you'll see that during development you'll be much quicker, since you'll have a good mental model of your application and it will be easier for you to lead your code in the right direction.

Basicaly what you need to do is write your tests in the following manner:

import static tumbler.Tumbler.*;

@RunWith(TumblerRunner.class}
@Story("Story name here")
public class SomeScenarios {

    @Scenario("Scenario name here")
    public void shouldDoSomething() {
        Given("input conditions description");
        Something sth = new Something();
        sth.setSomeField(someValue);

        When("operation description");
        Result result = sth.doSomething();

        Then("expected result description");
        assertThat(result, matchesExpectation);
    }
 
}

That's basically nearly all API. For more usage information and details see documentation

Generating Java classes from scenario files

Tumbler lets you generate java classes (JUnit tests) directly from scenario files. Just run

java -classpath Tumbler.jar tumbler.ScenarioToJavaConverter YOUR_STORY.scenario

This will generate a *Scenarios.java file in the current directory. Just place it in the right package and start working with it!

You can use your mother tongue in the scenario files if you wish. Just add -Dlocale=de if you want German, da for Danish, pl for Polish, etc. If your language is not supported, send me the translation, and I'll add it.

HTML generation

Generation of HTML reports is done using FreeMarker library. In order to be able to use it, place freemarker jar on your classpath and you're done. Now you can pass -DgenerateReport=html and -DoutputFolder=target to the VM while executing tests, and you'll find execution report in the target/Tumbler-reports directory.

You can also generate reports automatically in your maven build with this surefire plugin configuration to your pom.xml:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <useFile>false</useFile>
        <systemProperties>
            <property>
                <name>generateReport</name>
                <value>html</value>
            </property>
        </systemProperties>
        <includes>
            <include>**/*Scenarios.java</include>
        </includes>
    </configuration>
</plugin>

Running Tumbler stories together with Spring

Spring uses its own runner to execute its tests. But it's pretty simple to cheat it. Instead of @RunWith(SpringJUnit4ClassRunner.class) do this in your Tumbler class:

    private TestContextManager testContextManager;

    @Before
    public void init() throws Exception {
        this.testContextManager = new TestContextManager(getClass());
        this.testContextManager.prepareTestInstance(this);
    }

It will start Spring context with every Tumbler scenario run. You can still inherit after Spring-specific Abstract*Test classes and use their specific functionalities.

Comment by thomas.e...@gmail.com, May 17, 2010
Comment by pnied...@gmail.com, May 18, 2010

Wow, looks like Spock ported to Java. :-)

Comment by wakaleo@gmail.com, May 19, 2010

Hmmm, looks interesting. Needs a Maven plugin to integrate the story execution and report generation into the build lifecycle, though.

Comment by project member lipinski...@gmail.com, May 23, 2010

Docs work now. I made some svn layout changes and it influenced the links. Sorry for that. Maven plugin is on the way. For now you may just use 'test' phase and pass it VM arguments (as specified in the documentation).

Comment by thomas.k...@gmail.com, Mar 3, 2011

The creation of a report doesn't seem to work using the pom below and calling it with mvn clean install

<?xml version="1.0" encoding="UTF-8"?>
<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>se.sigma.educational.executable.specs</groupId>
    <artifactId>tumbler</artifactId>
    <version>1.0</version>
    <packaging>jar</packaging>
    <properties>
        <generateReport>html</generateReport>
        <outputFolder>target</outputFolder>
    </properties>
    <dependencies>
        <dependency>
            <groupId>pl.pragmatists.tumbler</groupId>
            <artifactId>tumbler</artifactId>
            <version>0.3.0</version>
        </dependency>
        <dependency>
            <groupId>org.freemarker</groupId>
            <artifactId>freemarker</artifactId>
            <version>2.3.16</version>
        </dependency>
    </dependencies>
</project>

Any suggestions on what to do to fix it?

Removing the property definitions above and calling the build with

mvn clean install -DgenerateReport?=html -DoutputFolder?=target

didn't work either.

Do you have any suggestions on how to fix it?

Comment by pascal.b...@gmail.com, Mar 4, 2011

try to add this between </dependencies> and </project>

<build>

		<plugins>

			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-surefire-plugin</artifactId>
				<configuration>
					<useFile>false</useFile>
					<systemProperties>
						<property>
							<name>generateReport</name>
							<value>html</value>
						</property>
					</systemProperties>
					<includes>
						<include>**/SomeScenarios.java</include>
					</includes>

				</configuration>
			</plugin>
		</plugins>
	</build>
Comment by project member lipinski...@gmail.com, Mar 4, 2011

Thanks Pascal, I've just added this snippet to the wiki page.

Comment by pascal.b...@gmail.com, Mar 7, 2011

Hi Paweł,

I've been using tumbler a alot recently. With its nice JUnit-generated Html reports, Tumbler-glass is really a fantastic tool to break the wall between Business Analyst and Developpers.

Still, in my opinion, one missing feature currently is data injection : TumblerRunner? being an extension of BlockJUnit4ClassRunner, it does not support JUnit data injection features such as @Theory and @Datapoints, or @Parameters annotation.

Do you think such feature could fit into tumbler (or is it irrelevant) ?

Regards, Pascal

Comment by project member lipinski...@gmail.com, Mar 7, 2011

Pascal, Thanks for the feedback. I have a semi-functional :) implementation of what I call "parameterised scenarios", which is basically pretty the same as standard JUnit stuff for this. I never had time to finish it, nor real reason to, because I never had a good use case for it. But once there is somebody who wants it... I'll try to finish it and release soon (maybe still in march).

I would appreciate if you could write a few sentences on what you use Tumbler for, what you like, what not, what it needs more, your experiences - stuff like this. A blog entry would be best (if you have one), but a comment here will also be fine.

Pawel

Comment by pascal.b...@gmail.com, Mar 7, 2011

Well, I'm not much of a blogger I'm afraid...

Why tumbler ?

In many projects, you will find an existing basis of JUnit tests. These tests could be split into

  • genuine unit tests (for developpers only)
  • functional (acceptance) tests, meaningful for both Business People and Developers

This latter category of tests requires some way to produce reports for Business People, so they can

  • read tests outputs without to many efforts adn validate their contents
  • have a framework to come up with new tests in a format that developpers can use

I tried many existing BDD-oriented framework, such as

  • EasyB.
  • Great framework. Great Html Reports. Missing a JUnit-suite like feature when you have many tests Some developers are used to Junit and allergic to groovy
  • Spock
  • Great for data injection Missing html reports

Great advantage of JUnit-based BDD such as tumbler is that

  • you can rewrite some of your exisiting tests and produce clean html reports in a very short period of time
  • it is easy to insert in an automated build tool (maven) and a continous integration server such as hudson

Other JUnit based frameworks:

  • JBehave is complicated to use, whereas your can use tumbler in 5 minutes
  • other (eg: concordion or cukes) requires addition files to your java code, whereas with tumbler you control everything from your java code

What extra killer features could make tumbler rock ?

  • Data injection
Once developers have achieved a walking skeleton, namely a test that works, they show it to Business People. Often Business people come up with new test scenarios: what if we buy instead of selling ? does the test still pass ? what if price is negative ? what if we forget to fill field xyz of form ABC ? ... Often, building new test just consists in adding some flesh to our skeleton: basically, running the very same tests, but with different sets of data. A way to achieve that is to make Tumbler Runner compatible with JUnit 4 @Parameters or, even better, with @Theories.

Of course either said than done...

Comment by project member lipinski...@gmail.com, Mar 9, 2011

Thanks a lot!

Comment by ankitagr...@gmail.com, Jan 3, 2012

Does Tumbler supports Groovy?

Comment by mandarps...@gmail.com, Jan 3, 2012

Hi all,

Can anyone tell me does Tumbler supports groovy? If yes then how we can do that. Please let me know if is there any workaround on it. I will be very much thankful if any one provide me the details on it.

Thanks & Regards Mandar P. Sabnis

Comment by Sidha1...@gmail.com, Jan 11, 2012

what makes tumbler different compared to jbehave apart from tumbler code converter?

Comment by nagarjun...@gmail.com, May 18, 2015

How can I run these Scenarios programmatically, Like we use JUnitCore to run tests programmatically.

Powered by Google Project Hosting