Cucumber JVM 7.x step definition visibility: restricting public steps to their own module

Question

In multi-module JVM projects using Cucumber JVM 7.x, step definition methods must be public for the glue backend to discover them, whether they use Cucumber Expressions or regular expressions. Package-private or private step methods are ignored during discovery, and the affected steps surface as undefined at runtime rather than as compile-time errors.

The design goal is to keep a module's steps usable within that module while preventing features in unrelated modules from matching the same step text through classpath-wide glue scanning. The @CucumberOptions glue attribute limits which packages are scanned, but any public step method on the test classpath remains callable from any feature that shares the glue configuration, and Cucumber 7.x documents no option to enable non-public step definitions.

Open questions

Is there a supported way in Cucumber JVM 7.x to scope step definitions to a specific module or feature suite beyond narrowing the glue packages?
Can a custom backend or annotation convention relax the public method requirement without silently breaking step discovery?
What conventions should apply when a shared library publishes step definition jars, so internal steps are not treated as public API by consuming teams?

Wasi · Answer

Short answer
Cucumber JVM 7.x can only discover step definition methods that are public. There is no configuration or annotation that makes non‑public methods visible, so the only supported way to keep a module’s steps private to that module is to limit the glue packages scanned by the runner and to keep any helper steps outside those packages (or in a separate test‑jar).
Confirmed facts

The Cucumber Java backend uses reflection to load public methods annotated with @Given, @When, @Then (or using Cucumber Expressions). Package‑private or private methods are skipped silently.
The @CucumberOptions glue attribute (or   element) determines which packages are scanned for step definitions. No other mechanism exists to restrict visibility.
If a step definition is public and its package is included in the glue, it will be matched by any feature that runs with the same glue configuration, regardless of Maven module boundaries.

Recommended steps for module‑level scoping

In each module’s Cucumber runner, set @CucumberOptions(glue = "com.example.mymodule.steps") so only that module’s step package is scanned.
Place all step definitions you want to expose as public in that package.
Put any internal helper steps in a different package (e.g., com.example.mymodule.steps.internal) that is **not** listed in any module’s glue, or ship them in a separate classifier/jar that is not added to the test classpath.
Verify by running the module’s tests: public steps should pass, while steps in the excluded package appear as Undefined in the console/report.

Example configuration
@RunWith(Cucumber.class)
@CucumberOptions(
    features = "classpath:features",
    glue = "com.example.mymodule.steps",
    plugin = {"pretty", "html:target/cucumber-reports"}
)
public class MyModuleRunner {}
If you need to confirm whether a particular runner is using XML instead of annotations, let me know which configuration style you are using so I can adjust the example.

Cucumber JVM 7.x step definition visibility: restricting public steps to their own module

Open questions

1 answer

Short answer

Confirmed facts

Recommended steps for module‑level scoping

Example configuration

Your perspective belongs here.

0 question comments