bluprint

Simple and tiny Behavior driven development framework for testing Java code.

The story behind the code

After years of using JBehave writing story files and step classes to execute them on large scale projects, I struggled to maintain all of the stories and associated steps. I sometimes even spent more time fixing and factorizing steps instead of building value features into my apps. Don't get me wrong, I really enjoyed the JBehave framework.

But last year I mainly worked on Javascript projects with Jasmine, Karma and Mocha and I really enjoyed writing tests in the "describe, it" way. I also found it more productive to have both the textual description and the executing code in the same place.

I tried to reproduce this way of writing test in Java when I worked on Java applications. Then Bluprint was born.

Bluprint is built with 3 primary goals :

• Improve Test readability
• Simplicity of use
• Keep the library as small as possible and rely only on JUnit for the core library

How to use it

Installation

With Gradle (Recommended)

Add jcenter to your gradle build file. Then add bluprint as a dependency.

repositories {
    jcenter()
}

dependencies {
    testCompile group: 'io.bluprint', name: 'bluprint', version: '1.0'
}

With Maven

Add the bluprint dependency inside your pom.xml

<dependency>
   <groupId>io.bluprint</groupId>
   <artifactId>bluprint</artifactId>
   <version>1.0</version>
   <type>jar</type>
</dependency>

Manual download

Download the bluprint jar and add it to your project classpath. Also add JUnit 4+.

Simple test case

1. Create a test class and extend the Bluprint class

2. create a method and annotate it with @Scenario

3. Add given, then, when steps

   Here's the final test case

   public class DemoTestCase extends Bluprint {
   
   	@Scenario("Test Addition")
   	@Id("123")
   	@PrimaryActor("user of the demo api")
   	@Goal("Perform an addition")
   	public void simpleTest() {
   		given("A = 5");
   		int a = 5;
   
   		given("B = 5");
   		int b = 5;
   
   		when("A + B");
   
   		int c = a + b;
   
   		then("it should return 10", () -> {
   			Assert.assertEquals(10, c);
   		});
   	}
   }

4. Run as a standard JUnit test. Here's the standard output :

   Scenario : Test Addition
   id : 123
   Description:
   	As a user of the demo api
   	I want to Perform an addition
   
   Execution:
   	 Given A = 5
   	 And B = 5
   	 > When A + B
   	 => Then it should return 10
   Success!
   

Asynchronous tests

Asynchronous operations and assertions are supported by when and then steps.

Implementation is inspired from Javascript BDD frameworks such as Mocha and uses Java 8 functional Interface.

1. write the steps as usual
2. add async to the lambda parameter
3. call async.done() when the asynchronous task has finished

By adding the async parameter, Bluprint will know that it has to wait for completion (async.done()) before executing next step.

   when("async action", (async) -> {

      // Perforn async stuffs

      // Tells Bluprint that async stuffs are completed and continue to next step
      async.done();

   });

Here's a sample

public class AsynchronousTestDemo extends Bluprint{

   @Scenario("Asynchronous scenario")
	public void asyncScenario() {

		given("an asynchronous task");

		long startDate = System.currentTimeMillis();
		AsyncTaskDemo asyncTaskDemo = new AsyncTaskDemo();

		// Waits for async.done() to be invoked before continuing
		when("started for 3 seconds", (async) -> {

			// Running Asynchronous Task
			asyncTaskDemo.start(3, new CallBack() {

				@Override
				public void taskComplete(final String data) {

					then("it should receive data inside the callback",
								() -> {
									Assert.assertNotNull(data);
								});

					// Mark the async task as complete
					async.done();
				}
			});

		});

		then("its execution time should be 3s +/- 200ms", () -> {
			long deltaT = System.currentTimeMillis() - startDate;
			Assert.assertEquals(3000, deltaT, 200);
		});

	}

}

License

Bluprint is released under the Apache License Version 2.0.