Skip to main content

Troubleshooting

Common problems, what causes them, and how to fix them. Each entry starts with what you actually see.

The generated class doesn't exist​

You see: Cannot resolve symbol 'ShoppingCartScenarios', or your hand-written test class can't find the class it extends.

SpecBinder writes that class during compilation, so it only appears once the project has been built with annotation processing switched on.

  1. Build the project. Nothing is generated until compilation runs. In IntelliJ, Build → Build Project; on the command line, mvn test-compile or ./gradlew compileTestJava.

    The SpecBinder IntelliJ plugin can take this step off your hands. Under Settings → Tools → SpecBinder → On feature file save, choose Recompile marker classes and saving a spec file rebuilds its generated tests there and then, so editing a step and re-running is all you do.

  2. Check annotation processing is enabled in your IDE. In IntelliJ: Settings → Build, Execution, Deployment → Compiler → Annotation Processors → Enable annotation processing.

  3. Check the generated sources folder is treated as source. Generated classes land in target/generated-test-sources/test-annotations/ (Maven) or build/generated/sources/annotationProcessor/ (Gradle). Maven and Gradle add these automatically; if your IDE hasn't caught up, re-import the project.

  4. Check the name you're expecting. The class is named after the spec file, not after the class you annotated — Checkout.specb produces CheckoutScenarios. See the naming rules.

The generated class is out of date​

You see: you changed a step's wording, but the generated class still has the old method, or your build still fails on a step you just renamed.

The generated class is rebuilt when the project is compiled. Editing a spec file on its own does not trigger that in every setup — some build tools consider the compile task up to date because no .java file changed.

  • Rebuild rather than relying on an incremental build: mvn clean test-compile, or ./gradlew compileTestJava --rerun-tasks.
  • In IntelliJ, set Settings → Tools → SpecBinder → On feature file save to Recompile marker classes, and saving the spec regenerates its tests immediately — see Auto-recompile on save.

A scenario with no steps fails​

You see: a scenario you have sketched out but not written steps for yet fails when the tests run.

That is the default: emptyScenarioBehavior is FAIL, so an unfinished scenario shows up rather than passing quietly.

If you would rather they were reported as skipped while you work, set the behaviour on the class you annotate:

@Gherkin2JUnit("specs/ShoppingCart.specb")
@Gherkin2JUnitOptions(emptyScenarioBehavior = EMPTY_ELEMENT_BEHAVIOUR.SKIP)
public abstract class ShoppingCartFeature { }

emptyRuleBehavior does the same for a Rule with no scenarios. COMPILATION_ERROR is the third option, if an unfinished scenario should stop the build outright.

A step parameter has the wrong type​

You see: a step method you implemented no longer matches, because a parameter that was an Integer is now a String.

Parameter types are inferred from the values in the spec, and the inference covers every occurrence of that step in the file. If one scenario passes "12" and another passes "twelve", the parameter widens to String everywhere — including in the method you already wrote.

Either keep the values consistent, or accept the wider type and convert inside the step.

My existing step method isn't being picked up​

You see: SpecBinder asks you to implement a step you have already written.

Steps are matched by method name. SpecBinder derives the name from the step's wording, so the method has to match that name exactly, and it has to be visible from the generated class — somewhere in the hierarchy of the class you annotated.

The reliable way to get the name right is to let SpecBinder generate the step first, then move that method to wherever you want it implemented.

If you are coming from Cucumber and expect your @Given/@When annotations to be matched instead, that is off by default — see Migrating from Cucumber.

Still stuck?​

Ask on the Q&A page — questions and answers there are public, so the next person with the same problem finds it too.