Write a text scenario

Create a scenario using the words Given, When, Then and And.

Given I am not logged in
When I log in as Liz with a password JBehaver
Then I should see a message, "Welcome, Liz!"

Save the scenario in file. The file should have a meaningful name, but use lowercase letters and underscores, eg: user_logs_in_successfully

Create matching Java Scenario class

Create a Java class, that matches the text scenario name. It should have the same name as your scenario, but use CamelCase, e.g. UserLogsInSuccessfully.java.

This class should extend Scenario and be in the same package.

public class UserLogsInSuccessfully extends Scenario {
  public UserLogsInSuccessfully() {
        super(new LoginSteps());
    }
}

where LoginSteps extends Steps

public class LoginSteps extends Steps {
}

Try running your scenario

The Scenario class is a JUnit test. You can right-click and run it in most new IDEs, or use a build script that runs JUnit tests. You can also run scenarios as Ant tasks or Maven goals. Learn more about running scenarios

You will notice an output of the kind:

Given I am not logged in (PENDING)
When I log in as Liz with a password JBehaver (PENDING)
Then I should see a message, "Welcome, Liz!" (PENDING)

What’s happening is that JBehave cannot find matching methods in the Steps class corresponding the to steps in the text scenario.

NOTE: from JUnit’s perspective the behaviour has been successfully run (you’ll see it marked as green). This silent pending error strategy is meant to allow textual scenarios to be written before any Java matching them is written – but to avoid breaking the build. One can configure different ways of handling scenarios misbehaving, e.g. it is possible to define a pending error strategy that throws an exception, and thus breaking the build.

Define the steps for your scenario

In the LoginSteps, write a method for each step, then annotate that method using @Given, @When or @Then JBehave annotations, depending on whether the step sets up a context (Given), performs some events that you’re interested in (When) or describes the desired outcome (Then).

The value of the annotations should match the steps you described in your scenario. You can capture arguments to pass through to your steps using a prefix, ”$”, before the argument.

package my.domain.app;
 
// Ensure extends JUnit's Assert
// It works just like JUnit with Hamcrest's matchers
// or you can create your own
 
import static org.jbehave.Ensure.ensureThat;
 
import org.jbehave.scenario.steps.Steps;
import org.jbehave.scenario.annotations.Given;
import org.jbehave.scenario.annotations.When;
import org.jbehave.scenario.annotations.Then;
 
public class LoginSteps extends Steps {
 
    // Some code to set up our browser and pages
    // ...
 
    @Given("I am not logged in")
    public void logOut() {
        currentPage.click("logout");
    }
 
    @When("I log in as $username with a password $password")
    public void logIn(String username, String password) {
        currentPage.click("login");
    }
 
    @Then("I should see a message, \"$message\"")
    public void checkMessage(String message) {
        ensureThat(currentPage, containsMessage(message));
    }
}

Run your successful scenario!

If you now re-run your scenario as a JUnit test, you’ll find that the PENDING messages are gone and your scenario has run successfully.

Configure scenarios

While sensible and most useful default values are provided, JBehave 2 has been designed to be highly configurable to suit all the developers’ requirements. Learn more about configuring scenarios.