Ginkgo4J

Having been an engineer using Java since pretty much version 1 and having practiced TDD for the best part of 10 years one thing that always bothered me was the lack of structure and context that Java testing frameworks like Junit provided.  On larger code bases, with many developers this problem can become quite accute.  When pair programming and working on existing tests I have sometimes even had to say to my pair

“Give me 10/15 minutes to actually figure out what this test is actually doing”

Because the fact of the matter is that the method name is simply not enough to convey the required given, when, then semantics context that are present in all tests.

I recently made a switch in job roles.  Whilst I stayed with EMC, I left the Documentum division (ECD) with whom I had been for 17 years and moved to a new division called the Cloud Platform Team (CPT) whose remit is to help EMC make a transition to the 3rd platform.  As a result I am now based in the Pivotal office in San Francisco and I pair program and I am now working in Golang.

Golang has a testing framework called Ginkgo that was actually created by one of Pivotal’s VPs Onsi Fakhouri.  It mirrors frameworks from other languages like RSpec in Ruby.  All of these framework provide a very simply DSL that the developer can use in his test to build up a described context with closures.  Having practiced this for the last six months I personally find this way of writing tests very useful.  Perhaps the most useful when I pick up an existing test and try to modify it.

Now, since version 8 Java has included it’s version of closures, called Lambda’s.  Whilst there aren’t quite as flexible as some of their equivalents on other languages.  All variable access must be to ‘finals’ for example.  They are sufficient to build an equivalent  testing DSL.  So that’s what I decided to do with Ginkgo4J, pronounced Ginkgo for Java.

So let’s take a quick look at how it works.

In your Java 8 project, add a new test class called BookTests.java as follows:-

package com.github.paulcwarren.ginkgo4j.examples;

import static com.github.paulcwarren.ginkgo4j.Ginkgo4jDSL.*;
 import org.junit.runner.RunWith;
 import com.github.paulcwarren.ginkgo4j.Ginkgo4jRunner;

@RunWith(Ginkgo4jRunner.class)
 public class BookTests {
{
  Describe("A describe", () -> {
  });
 }
 }

Let’s break this down:-

• The imports Ginkgo4jDSL.* and Ginkgo4jRunner add Ginkgo4J’s DSL and JUnit runner.  The Junit runner allows these style of tests to be run in all IDEs supporting Junit (basically all of them) and also in build tools such as Ant, Maven and Gradle.
• We add a top-level Describe container using Ginkgo4J’s Describe(String title, ExecutableBlock block) method.  The top-level braces {}trick allows us to evaluate the Describe at the top level without having to wrap it.
• The 2nd argument to the Describe () -> {}is a lambda expression defining an anonymous class that implements the ExecutableBlock interface.

The 2nd argument lamdba expression to the Describe will contain our specs.  So let’s add some now to test our Book class.

private Book longBook;
private Book shortBook;
{
 Describe("Book", () -> {
   BeforeEach(() -> {
     longBook = new Book("Les Miserables", "Victor Hugo", 1488);
     shortBook = new Book("Fox In Socks", "Dr. Seuss", 24);
   });

   Context("Categorizing book length", () -> {
     Context("With more than 300 pages", () -> {
       It("should be a novel", () -> {
         assertThat(longBook.categoryByLength(), is("NOVEL"));
       });
     });

     Context("With fewer than 300 pages", () -> {
       It("should be a short story", () -> {
         assertThat(shortBook.categoryByLength(), is("NOVELLA"));
       });
     });
   });
   });
 }

Let’s break this down:

• Ginkgo4J makes extensive use of lambdas to allow you to build descriptive test suites.
• You should make use of Describe and Context containers to expressively organize the behavior of your code.
• You can use BeforeEach to set up state for your specs. You use It to specify a single spec.
• In order to share state between a BeforeEach and an It you must use member variables.
• In this case we use Hamcrest’s assertThat syntax to make expectations on the categoryByLength() method.

Assuming a Book model with this behavior, running this JUnit test in Eclipse (or Intellij) will yield:

Success!

Focussed Specs

It is often convenient, when developing to be able to run a subset of specs. Ginkgo4J allows you to focus individual specs or whole containers of specs programatically by adding an F in front of your Describe, Context, andIt:

 FDescribe("some behavior", () -> { ... })
 FContext("some scenario", () -> { ... })
 FIt("some assertion", () -> { ... })

doing so instructs Ginkgo4J to only run those specs. To run all specs, you’ll need to go back and remove all the Fs.

Parallel Specs

Ginkgo4J has support for running specs in parallel.  It does this by spawning separate threads and dividing the specs evenly among these threads.  Parallelism is on by default and will use 4 threads.  If you wish to modify this you can add the additional annotation to your test class:-

@Ginkgo4jConfiguration(threads=1)

which will instruct Ginkgo4J to run a single thread.

Spring Support

Ginkgo4J also offers native support for Spring.  To test a Spring application context simply replace the @RunWith(Ginkgo4jRunner.class) with @RunWith(Ginkgo4jSpringRunner.class) and initialize you test class’ Spring application context in exactly the same way as if you were using Spring’s SpringJUnit4ClassRunner

@RunWith(Ginkgo4jSpringRunner.class)
@SpringApplicationConfiguration(classes = Ginkgo4jSpringApplication.class)

public class Ginkgo4jSpringApplicationTests {
  @Autowired
  HelloService helloService;
  {
  Describe("Spring intergation", () -> {
    It("should be able to use spring beans", () -> {
      assertThat(helloService, is(not(nullValue())));
    });

    Context("hello service", () -> {
      It("should say hello", () -> {
        assertThat(helloService.sayHello("World"), is("Hello World!"));
      });
    });
   });
   }

   @Test
   public void noop() {
   }
 }

The nooptest class is currently required as Spring’s junit runner asserts on at least one test class existing.

Trying it out for yourself

Please feel free to try it out on your Java projects.  For a maven project add:-

<dependency>     <groupId>com.github.paulcwarren</groupId>     <artifactId>ginkgo4j</artifactId>     <version>1.0.0</version> </dependency>

or for a Gradle project add:-

compile 'com.github.paulcwarren:ginkgo4j:1.0.0'


for others see here.

Advertisement