Skip to content
No description or website provided.


Build Status Coverage Status Maven Central

JUnit-BDD provides a simple and fluent API for structuring test code within when and then blocks used in Behavior-driven development.

As of version 2.0, JUnit-BDD depends only on Java 8 SE.

For more information on the subject of Behavior-driven development see the following links: Introducing BDD, GivenWhenThen article by M. Fowler or Wikipedia article.


  1. News
  2. Features
  3. Installation
  4. Contributing
  5. License



New entry point used for static imports is


All core classes have moved to the new com.github.lpandzic.bdd4j package. This is a precondition required for rename of the project.


JUnit dependency has been removed so the following is no longer required nor possible:

 public Bdd bdd = Bdd.initialized();

To migrate to 2.0 all you need to do is remove this Rule definition.

For other changes see the changelog



Following static import is useful for simpler syntax when using JUnit-BDD:

 import static com.github.lpandzic.junit.bdd.Bdd.when;

Note: in the following examples Hamcrest is used for assertions but you are free to use any assertion framework you like.

Return value assertion

For a given class DeathStar that contains method with signature Target fireAt(Target target) throws TargetAlreadyDestroyedException where TargetAlreadyDestroyedException is a checked exception, we can do the following value assertion:

when(deathStar.fireAt(alderaan)).then(target -> {
    assertThat(target.isDestroyed(), is(true));
    assertThat(target, is(alderaan));
    assertThat(target, is(not(coruscant)));

Thrown exception assertion

In order to catch exception for an assertion we pass a lambda to the when block:

when(() -> deathStar.fireAt(alderaan)).then(thrownException -> {
    assertThat(thrownException, is(instanceOf(TargetAlreadyDestroyedException.class)));
    assertThat(thrownException.getMessage(), is(equalTo("Cannot fire at a destroyed " + alderaan)));

Thrown checked exceptions assertion

If we decide to change the fireAt method so that it doesn't throw the TargetAlreadyDestroyedException the test mentioned in previous sub chapter will fail, but it will still compile. Since TargetAlreadyDestroyedException is a checked exception we can use Generics to prevent that test from compiling and reduce the time required to detect the error! To use this feature change then to thenChecked and use isA matcher:

when(() -> deathStar.fireAt(alderaan)).thenChecked(thrownException -> {
    assertThat(thrownException, isA(TargetAlreadyDestroyedException.class));
    assertThat(thrownException.getMessage(), is(equalTo("Cannot fire at a destroyed " + alderaan)));

Now if we decide to change the signature of fireAt not to include TargetAlreadyDestroyedException we get a compilation error.

Assertion framework flexibility

Although Hamcrest was used in previous examples you are free to use any Java assertion framework.

For example, the first two testing examples can be translated to:

  • plain JUnit assertions

    • Return value assertion
    when(deathStar.fireAt(alderaan)).then(target -> {
        assertEquals(target, alderaan);
        assertNotEquals(target, coruscant);
    • Thrown exception assertion
    when(() -> deathStar.fireAt(alderaan)).then(thrownException -> {
        assertEquals(TargetAlreadyDestroyedException.class, thrownException.getClass());
        assertEquals("Cannot fire at a destroyed " + alderaan, thrownException.getMessage());
  • AssertJ

    • Return value assertion
    when(deathStar.fireAt(alderaan)).then(target -> {
    • Thrown exception assertion
    when(() -> deathStar.fireAt(alderaan)).then(thrownException -> {
        assertThat(thrownException.getMessage()).isEqualTo("Cannot fire at a destroyed " + alderaan);





If you have an idea for a new feature or want to report a bug please use the issue tracker.


Licensed under MIT License.

Something went wrong with that request. Please try again.