Background and Architectural Context

JBehave composes four concerns: story parsing (Gherkin-like but with JBehave’s own grammar), step matching via annotations, execution orchestration through the Embedder or JUnit/Jupiter runners, and reporting via pluggable StoryReporters that produce HTML, TXT, XML, or custom outputs. In enterprise setups, these pieces live across multiple modules: story files in resources, step libraries in a shared test-utilities module, and runners per service. CI/CD commonly launches tests with Maven Surefire/Failsafe or Gradle Test, while cloud browsers and containers add network and filesystem variability. Understanding how story loading, step discovery, and reporting cross module/classloader boundaries is key to diagnosing "works locally, fails in CI".

Runtime Model in Brief

• Stories: plain text files with keywords (Given/When/Then/Examples/Meta) parsed by StoryParser.
• Steps: Java/Kotlin classes with @Given/@When/@Then annotated methods; parameter binding uses regex or named parameters.
• Embedder: orchestrates discovery, filtering (meta, story paths), execution, and reporting.
• Reporters: configurable via StoryReporterBuilder to generate views, cross-references, and failure summaries.

Typical Enterprise Symptoms

• Stories pass locally but are skipped in CI with no obvious reason—often due to meta-filter misconfiguration or story path resolution issues inside containers.
• Parameter conversion crashes for decimals/dates only on certain agents—locale or JDK differences alter parsing behavior.
• Parallel runs become flaky—shared WebDriver instances, static test data, or non-thread-safe step libraries collide.
• HTML reports not generated or missing CSS/JS—view resources not copied in headless environments or custom working directory assumptions.
• JUnit runners find zero stories in monorepos—classloader roots differ for shaded/fat JARs and test resource directories.
• Long stories time out in CI but not locally—distinct CPU shares and default storyTimeoutInSecs not tuned for container throttling.

Root Cause Analysis

Under the hood, most issues reduce to predictable categories: (1) discovery and filtering pitfalls, (2) environment-dependent parsing/conversion, (3) thread-safety and resource lifecycle, (4) reporting I/O and filesystem assumptions, and (5) execution controls/timeouts in distributed CI. Senior teams need to pin down which axis is failing by instrumenting the Embedder and reporters, then standardizing configuration across modules and pipelines.

Discovery & Filtering

Story discovery depends on the StoryLoader and path patterns. When test resources are relocated by the build tool, patterns like **/*.story may not align with the container’s working directory. Meta filters (e.g., +priority High -wip) are applied before execution; incorrect filter strings or missing Meta sections silently exclude stories. This creates the illusion of green builds that actually ran nothing.

Parsing & Conversion

JBehave binds parameters either via regex groups or named parameters. Converters are pluggable; defaults rely on JVM locale for numbers/dates unless you override. Heterogeneous agents (US vs EU locales) and multiple JDK versions lead to "works on my machine" bugs in Examples tables where commas vs periods matter, or ISO-8601 parsing differs.

Thread-safety & Lifecycles

Parallelism is coarse-grained (stories) and fine-grained (scenarios) depending on Embedder controls. Step instances can be reused across threads if configured incorrectly. Shared singletons (e.g., static WebDriver) cause cross-scenario leakage. Flakiness manifests as random element-not-found, non-idempotent API state, or racey data setup.

Reporting & Filesystems

HTML view generation writes to a "view" directory. In ephemeral CI containers, relative paths may point to non-writable locations. If resources (CSS/JS) are not copied because the "viewResources" weren’t on the classpath, the report renders blank. Headless runs often change working directories and break assumptions.

Execution Controls & Timeouts

Defaults for batch, failure strategies, and timeouts are optimized for local dev. In CI, long browser waits or API backoffs can exceed storyTimeoutInSecs. Pending steps behavior (ignore, treat as failures) can hide real coverage gaps if mis-set.

Diagnostics and Observability

Enable deep diagnostics at the orchestration and step levels. Treat your test runner like a production service: structured logs, environment capture, and deterministic seeds.

Embedder with Verbose Reporting

public class RunStoriesIT extends JUnitStories {
  @Override
  public Configuration configuration() {
    return new MostUsefulConfiguration()
      .useStoryLoader(new LoadFromClasspath(this.getClass()))
      .useStoryReporterBuilder(new StoryReporterBuilder()
        .withDefaultFormats()
        .withFormats(Format.CONSOLE, Format.TXT, Format.HTML, Format.XML)
        .withFailureTrace(true)
        .withFailureTraceCompression(true)
        .withCrossReference(new CrossReference()));
  }
  @Override
  public InjectableStepsFactory stepsFactory() {
    return new InstanceStepsFactory(configuration(), new UiSteps(), new ApiSteps());
  }
  @Override
  protected List<String> storyPaths() {
    return new StoryFinder().findPaths(CodeLocations.codeLocationFromClass(this.getClass()),
      Arrays.asList("**/stories/**/*.story"), Arrays.asList(""));
  }
}

CrossReference augments reports with step-to-story mappings. Start here to confirm stories were discovered, filters applied, and reporters wrote to disk.

Log Story Filtering & Meta

Embedder embedder = new Embedder();
embedder.useMetaFilters(Arrays.asList("+priority High", "-wip"));
embedder.useEmbedderControls(new EmbedderControls()
  .doBatch(true).useThreads(4).doIgnoreFailureInStories(false));
System.out.println("Meta filters: " + embedder.metaFilters());

Echo filters to logs. Many "skipped all tests" incidents stem from a single stray space or sign in the filter string.

Trace Parameter Binding

public class ConvertersConfig extends ParameterConverters {
  public ConvertersConfig() {
    super(new ParameterConverters.PlaceholderConverter(), true);
    addConverters(new DateConverter(new SimpleDateFormat("yyyy-MM-dd")),
                  new NumberConverter(NumberFormat.getInstance(Locale.US)));
  }
}

Configuration configuration = new MostUsefulConfiguration()
  .useParameterConverters(new ConvertersConfig())
  .useParameterControls(new ParameterControls().useDelimiterNamedParameters(true));

Explicit converters and named parameters remove locale ambiguity and make logs readable ("{amount}", "{date}"). This is a common fix for inconsistent Examples table parsing.

Enable Step Monitoring

configuration.useStepMonitor(new SilentStepMonitor() {
  @Override public void performed(String step, boolean dryRun) {
    System.out.println("PERFORMED: " + step);
  }
  @Override public void failed(String step, Throwable cause) {
    System.err.println("FAILED: " + step + " \u2192 " + cause.getMessage());
  }
});

Step monitors are invaluable when steps appear to match but bind to the wrong overload due to greedy regex.

Pitfalls and Deep Dives

1) Silent Story Exclusion via Meta Filters

Symptom: CI shows green build but zero stories executed. Root cause: the meta filter string excludes everything. Long-term fix: baseline with a "meta audit" step that prints the meta of all discovered stories before filtering; add a guard that fails fast when zero stories remain after filters.

2) Locale-Specific Parsing Breaks Examples

Symptom: tests pass in US agents but fail in EU agents where decimal commas are default. Fix: explicitly set NumberFormat in converters and log the active locale at test start. Consider a "known-locale" Docker image for test jobs to eliminate drift.

3) Parallel Flakiness from Shared State

Symptom: random failures only under useThreads > 1. Root cause: shared singletons (WebDriver, HTTP clients, in-memory DB). Fix: per-scenario or per-thread resource factories, thread-local storage, and disciplined teardown.

4) Reports Missing in CI Artifacts

Symptom: "view" folder is empty or HTML lacks styling. Root: working directory mismatch; reporters writing outside the archived path; static resources not on classpath. Fix: configure reporter output directory explicitly, assert writability, and copy view resources during build.

5) Story Path Resolution in Shaded JARs

Symptom: JUnitStories finds zero stories once tests run from a fat JAR or a different module. Root: codeLocationFromClass points to the runner module, not where resources ended up. Fix: resolve from the classpath root or use a LoadFromClasspath with explicit base.

6) Pending Step Strategy Masks Gaps

Symptom: new stories "pass" despite unimplemented steps. Root: EmbedderControls.doIgnoreFailureInStories(true) or default pending strategy. Fix: adopt FailingUponPendingStep and enforce in CI.

Step-by-Step Fixes

Stabilize Discovery & Paths

protected List<String> storyPaths() {
  URL searchBase = ClassLoader.getSystemResource("stories");
  return new StoryFinder().findPaths(searchBase,
    Arrays.asList("**/*.story"), Arrays.asList("**/wip/*.story"));
}

Resolve from a known classpath resource directory, not the current working directory. Exclude patterns explicitly.

Declare Runners with Deterministic Filters

@RunWith(AnnotatedEmbedderRunner.class)
@UsingEmbedder(embedder = Embedder.class,
  generateViewAfterStories = true,
  ignoreFailureInStories = false,
  ignoreFailureInView = false,
  threads = 4,
  storyTimeoutInSecs = 1800)
@UsingSteps(instances = { UiSteps.class, ApiSteps.class })
@UsingPaths(searchIn = "classpath:stories", includes = {"**/*.story"}, excludes = {"**/wip/*"})
@UsingMeta(filters = {"+priority High", "-wip"})
public class AllStoriesIT {}

Annotations document execution policy. Standardize these across modules to avoid drift.

Enforce Named Parameters & Strong Converters

public class PriceSteps {
  @When("the price is set to {amount} on {date}")
  public void setPrice(@Named("amount") BigDecimal amount, @Named("date") LocalDate date) {
    // ...
  }
}

Configuration cfg = new MostUsefulConfiguration()
  .useParameterControls(new ParameterControls().useDelimiterNamedParameters(true))
  .useParameterConverters(new ParameterConverters()
    .addConverters(new ParameterConverters.NumberConverter(NumberFormat.getInstance(Locale.US)),
                   new ParameterConverters.DateConverter(new SimpleDateFormat("yyyy-MM-dd"))));

Use named parameters over regex indexing to reduce ambiguity and improve maintainability.

Make Steps "Pure" and Thread-Safe

public class WebSteps {
  private final Supplier<WebDriver> driverFactory;
  public WebSteps(Supplier<WebDriver> driverFactory) { this.driverFactory = driverFactory; }
  @BeforeScenario public void open() { driver().get("about:blank"); }
  @AfterScenario(uponType = Outcome.ANY) public void close() { driver().quit(); }
  private WebDriver driver() { return driverFactory.get(); }
}

Inject a per-scenario driver; never hold a static shared driver. In parallel runs, use a thread-local supplier or a pool keyed by scenario ID.

Control Timeouts & Batching

EmbedderControls controls = new EmbedderControls()
  .doBatch(true)
  .useThreads(Runtime.getRuntime().availableProcessors())
  .useStoryTimeoutInSecs(3600)
  .doIgnoreFailureInStories(false)
  .doIgnoreFailureInView(false);
embedder.useEmbedderControls(controls);

Tune timeouts to CI conditions rather than local developer machines. Prefer (batch) execution with a bounded thread count equal to CPU cores.

Harden Reporting

StoryReporterBuilder builder = new StoryReporterBuilder()
  .withRelativeDirectory("jbehave-view")
  .withDefaultFormats()
  .withFormats(Format.HTML, Format.TXT, Format.XML, Format.CONSOLE)
  .withViewResources(new Properties() {{
    put("decorateNonHtml","true");
    put("reports","html,txt,xml");
  }});
configuration.useStoryReporterBuilder(builder);

Set a relative directory inside the CI workspace and assert writability at start-up. Export that folder as an artifact explicitly.

Lock Build Tooling

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <version>3.2.5</version>
  <configuration>
    <forkCount>1C</forkCount>
    <reuseForks>true</reuseForks>
    <argLine>-Dfile.encoding=UTF-8 -Duser.language=en -Duser.country=US</argLine>
  </configuration>
</plugin>

Force consistent encoding and locale to neutralize parsing differences across agents.

Advanced Diagnostics Patterns

1) Dry-Run Feature to Validate Coverage

configuration.useStepPatternParser(new RegexPrefixCapturingPatternParser());
configuration.useStepMonitor(new PrintStreamStepMonitor());
embedder.useEmbedderControls(new EmbedderControls().doDryRun(true));

Dry runs list unmatched steps without executing side effects. Use as a pre-merge check to block commits that add uncovered steps.

2) Custom Parameter Converters for Domain Objects

public class MoneyConverter implements ParameterConverters.ParameterConverter {
  @Override public boolean accept(Type type) { return type.equals(Money.class); }
  @Override public Object convertValue(String value, Type type) {
    String[] parts = value.split(" ");
    return new Money(new BigDecimal(parts[0]), Currency.getInstance(parts[1]));
  }
}
new ParameterConverters().addConverters(new MoneyConverter());

Instead of sprinkling parsing logic around steps, centralize business parsing with a converter and reuse across suites.

3) Capturing HTTP & Browser Artifacts on Failure

@AfterScenario(uponOutcome = AfterScenario.Outcome.FAILURE)
public void captureArtifacts() {
  takeScreenshot();
  dumpNetworkLogs();
  saveConsoleLogs();
}

Attach artifacts to CI for post-mortem analysis. Combine with reporter hooks to hyperlink artifacts from HTML reports.

4) Composite Steps for Reusability

@Composite(steps = {
  "Given user navigates to \"{url}\"",
  "When user logs in as \"{role}\"",
  "Then dashboard is visible"
})
@Given("a logged-in {role} on {url}")
public void loggedIn(String role, String url) {}

Composite steps reduce duplication while keeping atomic steps testable. Use sparingly to avoid obscuring intent.

5) Scenario-Level Dependency Injection with Spring

@Configuration
public class TestConfig {
  @Bean @Scope("prototype") public WebDriver driver() { return new ChromeDriver(); }
}

public class SpringSteps extends Steps {
  @Autowired private WebDriver driver;
  public SpringSteps() { super(new SpringStepFactory(new MostUsefulConfiguration(), new AnnotationConfigApplicationContext(TestConfig.class))); }
}

Prototype scope ensures a fresh WebDriver per scenario, eliminating cross-scenario contamination in parallel runs.

End-to-End Example

Story File

Meta: @priority High
Narrative:
In order to complete a purchase
As a registered user
I want to add a product to cart and checkout

Scenario: Successful checkout
Given a logged-in user on "https://shop.example"
When the user adds "laptop" to the cart
And the user pays with "1000 USD" on "2025-08-01"
Then the order status is "CONFIRMED"

Examples:
| product | amount   | date       |
| laptop  | 1000 USD | 2025-08-01 |

Steps

public class CheckoutSteps {
  @Given("a logged-in user on \"{url}\"")
  public void login(@Named("url") String url) { /* open and login */ }
  @When("the user adds \"{product}\" to the cart")
  public void add(@Named("product") String product) { /* add to cart */ }
  @When("the user pays with \"{amount}\" on \"{date}\"")
  public void pay(@Named("amount") Money amount, @Named("date") LocalDate date) { /* pay */ }
  @Then("the order status is \"{status}\"")
  public void verify(@Named("status") String status) { /* assert */ }
}

Runner

public class CheckoutStories extends JUnitStories {
  public CheckoutStories() {
    Configuration cfg = new MostUsefulConfiguration()
       .useParameterConverters(new ParameterConverters().addConverters(new MoneyConverter()))
       .useStoryReporterBuilder(new StoryReporterBuilder().withDefaultFormats().withFormats(Format.HTML, Format.CONSOLE));
    useConfiguration(cfg);
    useStepsFactory(new InstanceStepsFactory(cfg, new CheckoutSteps()));
  }
  @Override protected List<String> storyPaths() {
    return new StoryFinder().findPaths(CodeLocations.codeLocationFromClass(getClass()), Arrays.asList("**/checkout.story"), Arrays.asList(""));
  }
}

Performance Optimizations

• Thread model: Prefer story-level parallelism; avoid scenario-level unless steps are hermetic. Size threads to cores.
• I/O shaping: Stub external systems with fast local doubles; use wiremock or in-memory services for determinism.
• Selector stability: For UI steps, adopt resilient locators and explicit waits; flaky selectors dominate runtime variance.
• Data minimization: Keep scenarios short and focused; long end-to-end chains make failures opaque and slow.
• Report size: Compress failure traces and archive only the "view" directory, not raw logs of every dependency.

Best Practices for Sustainable Suites

• Contract-driven steps: Treat steps as a public API; version them and avoid breaking changes across teams.
• Test data strategy: Reset state per scenario; seed using idempotent fixtures; never share mutable IDs across threads.
• Observability: Emit structured JSON logs including story, scenario, step, duration, and outcome; correlate with CI job IDs.
• Static analysis: Lint stories for anti-patterns (too many Ands, ambiguous wording) and detect duplicate step patterns.
• Governance: Enforce pending-step-as-failure and "0 tests executed" guardrails; publish dashboards of flakiness and duration percentiles.
• Version pinning: Lock JBehave, WebDriverManager, and browser versions; document upgrade playbooks with compatibility notes.
• Isolation: Run acceptance tests in dedicated CI stages with resource quotas; flaky neighbors cause spurious timeouts.

Long-Term Architectural Considerations

For organizations with dozens of services, centralize BDD infrastructure. Provide a shared library of stable steps for common concerns (auth, payments, navigation) and generate per-service runners that import the library. Treat story files as product artifacts: code review them, run language checks, and link them to Jira/issue trackers. Consider separating "spec validation" (fast, hermetic) from "UI smoke" (slow, brittle) and gate releases on the former while sampling the latter. If scale or complexity explodes, evaluate headless API-first acceptance tests with UI smoke as a thin layer, keeping JBehave where it delivers the best ROI: articulate, auditable narratives tied to business rules.

Conclusion

JBehave’s power in enterprise contexts stems from its composable architecture and rich extension points—the same traits that can make it tricky at scale. Most production issues are not "framework bugs" but mismatches in discovery rules, locale-sensitive conversion, unsafe parallelism, or brittle reporting paths. Senior teams should standardize Embedder configuration, enforce named parameters and explicit converters, isolate resources per scenario, and treat the test runner as a monitored system. With these controls in place, JBehave suites can remain fast, deterministic, and maintainable across complex pipelines and evolving architectures.

FAQs

1. Why did my build pass with zero JBehave stories executed?

Usually because meta filters or path patterns excluded everything. Log discovered stories before filtering and fail the build if the post-filter count is zero to prevent false greens.

2. How do I stop locale differences from breaking Examples tables?

Provide explicit ParameterConverters for numbers and dates and fix the CI locale via JVM arguments. Prefer named parameters to regex groups to improve clarity and reduce parsing errors.

3. What’s the safest way to run in parallel?

Use story-level parallelism, ensure step classes are stateless, and provision per-scenario resources like WebDriver and test data. Avoid static singletons and shared mutable state.

4. Why are my HTML reports empty in CI but fine locally?

The reporter likely wrote to a non-writable or unarchived directory, or static assets were missing on the classpath. Set an explicit output directory inside the workspace and copy view resources.

5. Should I rely on pending steps to track work-in-progress?

No, treat pending as failures in CI to safeguard coverage and signal incomplete implementations. Use a separate meta tag like @wip to exclude unstable stories intentionally.