|
IntroductionForDevelopers
IntroductionThe 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. InstallationThere are two ways you can use Tumbler - either by manually adding it your project's classpath, or by using maven. Manual installationThere'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 installationThis 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! UsageSo, 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 filesTumbler 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 generationGeneration 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 SpringSpring 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. |
The link to the documentation doesn't work. http://tumbler-glass.googlecode.com/svn/trunk/Tumbler/apidocs/tumbler/Tumbler.html
Wow, looks like Spock ported to Java. :-)
Hmmm, looks interesting. Needs a Maven plugin to integrate the story execution and report generation into the build lifecycle, though.
Docs seem to be here: http://tumbler-glass.googlecode.com/svn/trunk/apidocs/index.html
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).
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?
try to add this between </dependencies> and </project>
Thanks Pascal, I've just added this snippet to the wiki page.
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
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
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
This latter category of tests requires some way to produce reports for Business People, so they can
I tried many existing BDD-oriented framework, such as
Great advantage of JUnit-based BDD such as tumbler is that
Other JUnit based frameworks:
What extra killer features could make tumbler rock ?
Thanks a lot!
Does Tumbler supports Groovy?
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
what makes tumbler different compared to jbehave apart from tumbler code converter?
How can I run these Scenarios programmatically, Like we use JUnitCore to run tests programmatically.