Feature Files Location in Cucumber JVM

The feature files location is the directory where all Gherkin `.feature` files are stored in a Cucumber JVM project. These files contain business-readable requirements, scenarios, examples, and acceptance criteria. They are the starting point for Cucumber execution because Cucumber must first find feature files before it can parse Gherkin, match steps with Java step definitions, execute automation code, and generate reports.

In a clean Cucumber JVM framework, feature files are treated as test resources, not Java source code. They should be easy for testers, developers, business analysts, and product owners to locate and review. A good feature file location also helps build tools and CI/CD pipelines run scenarios consistently across local machines, IDEs, Jenkins, GitHub Actions, and other execution environments.

The recommended location for feature files in a Maven-based Java project is `src/test/resources/features`. This convention keeps Gherkin files separate from Java implementation code while still making them available on the test classpath. When the structure is followed properly, Cucumber can locate feature files through direct paths or classpath-based configuration, and the framework remains portable across operating systems and build environments.

1. What Is the Feature Files Location?

The feature files location is the folder path where Cucumber looks for `.feature` files. A feature file is a text file written in Gherkin syntax. It may contain a Feature title, description, scenarios, scenario outlines, backgrounds, tags, examples tables, and steps written with Given, When, Then, And, or But. During execution, Cucumber reads the configured location, discovers feature files, parses them, and prepares scenarios for execution.

In Cucumber JVM, this location is commonly configured through the runner class using the `features` option in `@CucumberOptions`. The runner tells Cucumber where to search. If the location is correct, scenarios are discovered and executed. If the location is wrong, Cucumber may run zero scenarios or report that it cannot find the feature files. This is why feature file location is a small configuration detail with a large impact on execution.

The feature files location is not just a technical setting. It also affects collaboration. Feature files are supposed to be readable specifications. If they are hidden inside Java packages, mixed with screenshots, or scattered across random folders, the team loses clarity. A predictable location makes feature files easier to review, refactor, and maintain.

Feature Files as Business Specifications

Feature files should be treated as business specifications, not automation scripts. Their location should reflect that role. They belong in resources because they are input files for test execution, similar to test data, configuration, or templates. Java classes implement execution, while feature files describe expected behavior.

2. Why Feature File Location Is Important

The feature file location is important because Cucumber cannot execute scenarios it cannot find. When the runner starts, it scans the configured feature path. If the path is incorrect, no scenarios are discovered. This can lead to confusing results, especially in CI/CD pipelines where a build may appear to run but execute nothing meaningful. Correct location is the first requirement for reliable execution.

A good location also organizes business requirements. Feature files are not random test scripts; they represent product behavior. Keeping them in a consistent folder helps teams navigate the product by capability, module, or domain. For example, authentication scenarios can live under `features/authentication`, payment scenarios under `features/payments`, and order scenarios under `features/orders`. This makes the suite understandable as it grows.

Feature file location also keeps test resources separate from Java code. Java classes belong under `src/test/java`. Feature files belong under `src/test/resources`. This separation follows Maven conventions and helps IDEs, build tools, and CI systems treat files correctly. It also prevents feature files from being confused with source packages.

Finally, a standard location simplifies CI/CD execution. Jenkins, GitHub Actions, Azure DevOps, GitLab CI, and similar tools can run Maven or Gradle commands without custom path assumptions. When the project follows conventions, the pipeline is easier to configure and easier to troubleshoot.

  • Helps Cucumber discover feature files correctly.
  • Organizes business requirements in a predictable place.
  • Keeps test resources separate from Java code.
  • Supports maintainable project structures.
  • Simplifies Maven, Gradle, IDE, and CI/CD execution.

3. Standard Location in a Maven Project

According to the Maven standard directory layout, test resources should be stored under `src/test/resources`. For Cucumber JVM projects, the most common and recommended folder for feature files is `src/test/resources/features`. This location is used widely because it aligns with Maven conventions and keeps Gherkin files available during test execution.

src
|-- test
|   |-- resources
|       |-- features

The complete path is:

src/test/resources/features

This path is simple, predictable, and portable. It works well with IDEs such as IntelliJ IDEA and Eclipse. It works with Maven Surefire and Failsafe plugins. It also works in CI/CD environments where the project is checked out and built from a clean workspace. Because this structure is standard, new team members can understand it quickly.

Some teams place feature files in a custom folder at the project root, such as `features`. That can work if configured properly, but it is less aligned with Maven conventions. For most Java automation frameworks, `src/test/resources/features` is the better default.

Why Maven Convention Helps

Maven automatically understands `src/test/resources` as the location for test resources. Files placed there are copied to the test classpath during the build. This means feature files can be referenced by classpath in a portable way. The team does not need absolute paths or machine-specific configuration.

4. Why Use src/test/resources?

The `src/test/resources` folder exists specifically for files needed during test execution but not compiled as Java source code. Feature files fit this purpose perfectly. They are test resources that guide execution. They should be packaged or made available to the test runtime, but they should not be compiled like Java classes.

Using `src/test/resources` provides several benefits. First, it includes feature files in the test classpath automatically. Second, it makes the project portable across environments. Third, it separates behavior documentation from Java code. Fourth, it works naturally with Maven, Gradle, Jenkins, and CI/CD tools. Fifth, it helps the team maintain a predictable project structure.

This structure also supports other resource files. Test data files, configuration files, logging configuration, JSON schemas, and templates can live under resources in their own folders. The `features` folder should contain feature files, while test data and configuration should live in separate folders under resources.

  • Included in the test classpath.
  • Easy for Cucumber to locate.
  • Portable across IDEs and operating systems.
  • Compatible with Maven, Gradle, Jenkins, and CI/CD tools.
  • Keeps behavior files separate from Java implementation code.

5. Example Project Structure

A simple Cucumber JVM project may have runners, hooks, pages, and step definitions under `src/test/java`, while feature files live under `src/test/resources/features`. This organization separates executable Java automation code from readable Gherkin resources.

Project
|
|-- src
|   |-- test
|       |-- java
|       |   |-- runners
|       |   |-- hooks
|       |   |-- pages
|       |   |-- stepdefinitions
|       |
|       |-- resources
|           |-- features
|               |-- login.feature
|               |-- registration.feature
|               |-- payment.feature
|               |-- profile.feature
|
|-- pom.xml

In this structure, the runner package starts execution, the hooks package manages setup and teardown, the pages package contains Page Object classes, and the stepdefinitions package maps Gherkin steps to Java methods. The features folder contains only `.feature` files. This makes the project easy to navigate.

Even in a small project, it is worth following this structure from the beginning. Moving feature files later can require runner updates, CI updates, documentation changes, and team retraining. Starting with the standard location prevents that rework.

6. Organizing Feature Files by Business Module

When a project has only a few feature files, placing all of them directly under `features` may be acceptable. As the project grows, this becomes harder to manage. A large enterprise framework may contain dozens or hundreds of feature files. In that situation, organizing feature files by business module or product capability becomes important.

features
|
|-- authentication
|   |-- login.feature
|   |-- logout.feature
|   |-- forgot-password.feature
|
|-- orders
|   |-- create-order.feature
|   |-- cancel-order.feature
|
|-- payments
|   |-- payment.feature
|   |-- refund.feature
|
|-- users
|   |-- registration.feature
|   |-- profile.feature

This structure makes navigation easier. If someone is working on payment behavior, they know where to find payment scenarios. It improves scalability because new modules can be added cleanly. It also supports ownership because teams or squads can own feature folders related to their domain.

Organizing by business module is usually better than organizing by test type. For example, folders such as `positive`, `negative`, `smoke`, and `regression` may sound useful, but they do not represent product capabilities. Tags are better for test type classification. Folder structure should reflect business domain. Tags can handle execution grouping.

Business Structure vs Execution Structure

A common mistake is organizing folders based on how tests are executed rather than what behavior they describe. Execution categories change often. Business capabilities are more stable. Use folders for business organization and tags for execution selection.

For example, a scenario may be part of smoke testing today and regression testing tomorrow. If the file is stored under a smoke folder, the structure becomes misleading when the execution strategy changes. A payment refund scenario should live under a payments or refunds folder because that is its business identity. Whether it runs in smoke, regression, sprint validation, or nightly execution should be controlled by tags, runner options, or CI configuration.

This separation makes large suites easier to maintain. Business folders help people find scenarios. Tags help pipelines select scenarios. Mixing the two responsibilities usually creates confusion over time.

7. Naming Conventions for Feature Files

Feature file names should be meaningful, consistent, and easy to read. A good name describes the business functionality covered by the file. It should be lowercase, use hyphens or underscores, avoid spaces, and end with `.feature`. Hyphenated names are common because they are readable in file systems and URLs.

Good examples include:

login.feature
order-history.feature
payment-processing.feature
forgot-password.feature
profile-management.feature

Poor examples include:

LoginTest.feature
Feature1.feature
TC001.feature
new_login_final.feature

Poor names make feature files harder to understand. `TC001.feature` tells the reader nothing about behavior. `Feature1.feature` suggests the file was created without a domain purpose. `LoginTest.feature` mixes test-case style naming with BDD. A better name describes the capability, such as `login.feature` or `authentication.feature`.

Naming for Long-Term Maintenance

Feature file names appear in reports, IDE navigation, pull requests, and CI logs. Meaningful names help failures make sense. If a report shows failure in `payment-processing.feature`, the team immediately understands the affected area. If it shows failure in `TC_017.feature`, the team must look it up.

8. Configuring Feature File Location

Cucumber locates feature files through runner configuration. In JUnit 4 style Cucumber JVM projects, this is commonly done with the `features` option inside `@CucumberOptions`. The value can point to a folder or a specific feature file.

@CucumberOptions(
    features = "src/test/resources/features"
)

This tells Cucumber to search for `.feature` files under `src/test/resources/features`. If the folder contains subfolders, Cucumber can discover feature files inside them as well. This allows teams to organize files by module while still using one root feature path.

Runner configuration should match the actual folder structure. If the path says `src/test/resources/feature` but the folder is named `features`, Cucumber will not find the files. Small spelling differences are enough to break execution. This is why feature path configuration should be checked carefully during setup.

Direct Path vs Classpath

A direct path such as `src/test/resources/features` is common and easy to understand. A classpath path such as `classpath:features` is more portable in many enterprise setups. Both can work, but the team should use one style consistently.

Consistency is important because mixed path styles make troubleshooting harder. If one runner uses a direct path, another uses classpath, and a third points to a specific module folder, team members must understand three different execution models. A framework is easier to maintain when runner configuration follows one standard unless there is a clear reason to deviate.

When a new runner is added, review the feature path carefully. The runner should point to the correct root folder or module folder, and the glue path should point to the correct step definitions and hooks. Feature path and glue path are different settings, but beginners often confuse them. Feature path finds Gherkin files. Glue path finds Java step definitions and hooks.

9. Multiple Feature Locations

Cucumber can search multiple directories when the runner provides more than one feature path. This is useful when teams want a module-specific runner, when a suite should include selected domains, or when feature files are split across several resource folders for a valid reason.

@CucumberOptions(
    features = {
        "src/test/resources/features/authentication",
        "src/test/resources/features/orders"
    }
)

Multiple locations should be used carefully. They can make execution more flexible, but they can also make runner configuration harder to understand. If the suite should normally run all feature files, pointing to the root `features` folder is simpler. Use multiple paths when there is a clear module-specific execution need.

In larger projects, tags are often a better way to control execution than creating many feature paths. For example, scenarios can be tagged `@smoke`, `@regression`, `@api`, `@ui`, or `@payments`. The runner can point to the root features folder and filter by tags.

10. Running a Single Feature

During development or debugging, it is often useful to run only one feature file. Cucumber supports this by configuring the runner to point directly to one `.feature` file.

@CucumberOptions(
    features = "src/test/resources/features/login.feature"
)

Only scenarios inside `login.feature` will run. This is helpful when a developer or tester is working on one capability and does not want to execute the full suite. It also helps isolate failures. If the full regression suite fails, running one feature can confirm whether the issue is local to that behavior or caused by broader setup.

However, teams should avoid permanently creating a runner for every feature file. Too many runners create maintenance overhead. For routine development, IDE run configurations, Maven parameters, or temporary runner changes may be enough.

11. Running a Specific Scenario

Cucumber can execute a specific scenario by referencing the feature file path and the line number where the scenario starts. This is useful for debugging a failing scenario, validating a fix quickly, or working on a single scenario during development.

@CucumberOptions(
    features = "src/test/resources/features/login.feature:12"
)

This configuration runs the scenario that starts at line 12. The line number can be copied from the IDE or from a failure report. Running by line number is efficient because it avoids executing unrelated scenarios.

Line-number execution is best used temporarily. If feature files are edited and line numbers change, the runner may point to the wrong scenario or stop working as expected. For stable suite selection, tags are usually better.

  • Useful for debugging a failing scenario.
  • Useful for quick validation after a fix.
  • Useful during scenario development.
  • Less suitable for long-term suite configuration.

In daily development, running a scenario by line number is useful when reproducing a failure from a report. Many Cucumber reports include the feature path and scenario line number. A developer can copy that reference and run only the failing scenario locally. After debugging is complete, the permanent runner configuration should return to a folder or tag-based strategy.

12. Feature Files and Classpath

Instead of using a physical file path, Cucumber can use the classpath. When feature files are stored under `src/test/resources/features`, they become available on the test classpath during execution. This allows runner configuration like this:

@CucumberOptions(
    features = "classpath:features"
)

Classpath-based configuration is often preferred in enterprise projects because it is more portable. It does not depend on the current working directory in the same way a relative file path might. It also works well when tests are executed from packaged builds or different environments.

Using `classpath:features` also makes the runner cleaner. The runner says, in effect, "find the features folder on the test classpath." Maven and the IDE handle resource placement. This reduces operating-system path issues and makes execution more consistent.

When Classpath Is Helpful

Classpath configuration is helpful when tests are run from CI, from different IDEs, from Maven commands, or from packaged test artifacts. It is also useful when the team wants to avoid hardcoding `src/test/resources` in runner classes.

Classpath paths are also helpful when teams work across Windows, macOS, and Linux. File path behavior can differ across operating systems, especially around separators and case sensitivity. Classpath-based lookup reduces these differences because the resources are resolved through the Java runtime and build configuration rather than through a local file-system assumption.

13. Feature Files in CI/CD

In CI/CD environments such as Jenkins, GitHub Actions, GitLab CI, Azure DevOps, or Bamboo, the project is checked out into a workspace, dependencies are downloaded, and Maven or Gradle runs the tests. If feature files are stored under the standard resources location, they are available automatically during test execution.

A typical CI flow looks like this. The repository is cloned. Maven builds the project. Test resources are added to the classpath. Cucumber discovers feature files based on runner configuration. Scenarios execute. Reports are generated under `target` or another configured report folder. The CI tool archives or displays those reports.

No special configuration is usually required when the standard structure is followed. Problems appear when feature files are placed in nonstandard folders and the pipeline working directory differs from local execution. This is another reason to prefer `src/test/resources/features` and classpath-based configuration when possible.

CI Troubleshooting Tip

If scenarios run locally but not in CI, check the feature path, runner configuration, working directory, resource copying, and case sensitivity. Some operating systems are case-sensitive, so `Features` and `features` may behave differently.

Another CI issue is accidental exclusion of resource files. If a build configuration, ignore rule, or packaging step excludes `.feature` files, Cucumber will not find them even though the local project looks correct. Check the generated test classes or build output when troubleshooting discovery problems. The feature files should be present in the expected test resource output.

CI logs should also show which runner or Maven profile is being used. Sometimes the feature location is correct, but the pipeline runs a different runner than the one used locally. Clear runner names and documented commands help prevent this mismatch.

14. Common Mistakes

One common mistake is placing feature files inside `src/test/java`. This treats behavior files as if they were source code. It breaks the separation between Java implementation and test resources. It can also confuse build tools and team members.

src/test/java/features

Another mistake is using incorrect paths in runner configuration. For example:

features = "feature"

when the real location is:

features = "src/test/resources/features"

A third mistake is storing unrelated files in the features folder. Excel files, JSON files, screenshots, configuration files, and generated reports should not be mixed with `.feature` files. The features folder should be reserved for Gherkin specifications. Test data should go under `testdata`, config under `config`, and generated files under `target` or reports folders.

Poor organization is another common issue. A folder with files such as `login.feature`, `login2.feature`, `login_new.feature`, and `login_final.feature` suggests unclear ownership and weak naming. Feature files should be named by business behavior or module, not by temporary development history.

  • Placing feature files inside `src/test/java`.
  • Using incorrect or misspelled runner paths.
  • Storing Excel, JSON, screenshots, or config files in the features folder.
  • Using vague names such as Feature1.feature or TC001.feature.
  • Creating duplicate feature files instead of refactoring existing ones.

15. Best Practices

The best practice is to store feature files in `src/test/resources/features`. This location follows Maven conventions, keeps Gherkin separate from Java code, and supports portable execution. Organize feature files by business domain or module as the suite grows. Use meaningful, business-oriented file names. Keep only `.feature` files in the features directory.

Use `classpath:features` when possible for better portability. Keep feature files independent of UI and implementation details. Review and refactor feature organization as the project grows. Remove duplicate files, rename unclear files, and split or merge feature files based on business capability rather than test execution convenience.

Feature file organization should be reviewed during framework maintenance. When new product modules are added, create clear folders. When old functionality is removed, delete obsolete feature files. When a file becomes too large, split it by business capability. When multiple files overlap, consolidate them.

Feature files should also be reviewed for ownership. If several teams edit the same large feature file, merge conflicts become common and the file may lose focus. Splitting by business capability can reduce conflicts and make reviews cleaner. Each file should have a clear reason to exist and a clear relationship to the product area it describes.

Do not treat the feature folder as a dumping ground. New scenarios should be placed intentionally. If a scenario does not clearly belong to an existing folder, that may reveal a missing business module or a scenario that is not framed clearly enough.

  • Store feature files in `src/test/resources/features`.
  • Organize them by business domain or module.
  • Use meaningful, lowercase, business-oriented file names.
  • Keep only `.feature` files in the features directory.
  • Use `classpath:features` where possible for portability.
  • Keep feature files independent of UI or implementation details.
  • Refactor feature organization as the project grows.

16. Feature File Location and Team Collaboration

Feature file location affects collaboration because feature files are shared artifacts. Product owners may review scenarios for business correctness. Business analysts may refine examples. Testers may add edge cases. Developers may connect scenarios to implementation. Automation engineers may map steps to Java code. A predictable feature folder makes this collaboration easier.

When feature files are organized by business module, ownership becomes clearer. The payments team can review payment features. The authentication team can review login and password features. The order team can review order creation, cancellation, and history scenarios. This reduces confusion and helps teams keep scenarios aligned with product behavior.

Good organization also improves pull request reviews. Reviewers can quickly see which business area is affected. A change under `features/payments` signals payment behavior. A change under `features/authentication` signals login or access behavior. This is more useful than having all feature files in one crowded directory.

17. Feature File Location and Reporting

Reports often display feature file names and paths. Clear file locations make reports easier to interpret. If a scenario fails under `features/orders/create-order.feature`, the team can quickly identify the affected module. If files are named vaguely or stored randomly, report interpretation takes longer.

Well-organized feature paths also help with filtering and trend analysis. Teams can see which modules fail most often, which areas have the most scenarios, and which business capabilities need more maintenance. The folder structure becomes part of the quality information produced by the automation suite.

18. Interview-Ready Summary

In interviews, a strong answer should explain that feature files contain business-readable Gherkin scenarios and that the recommended Maven location is `src/test/resources/features`. Cucumber locates feature files using the `features` option in `@CucumberOptions`, or through classpath configuration such as `classpath:features`.

You should also explain that feature files should be organized by business functionality, not by test case IDs or temporary execution needs. Using the standard location improves portability, maintainability, IDE support, Maven compatibility, and CI/CD execution. Feature files are specifications and resources, not Java source code.

  • Feature files contain business-readable Gherkin scenarios.
  • The recommended Maven location is `src/test/resources/features`.
  • Cucumber locates them using the `features` option in runner configuration.
  • Feature files should be organized by business functionality.
  • Standard location improves portability, maintainability, and CI/CD compatibility.

19. Golden Rule

The golden rule is simple: feature files are business specifications, not Java source code. Store them as test resources under `src/test/resources`, usually inside a `features` folder, and organize them by business capability. This keeps the project clean, portable, and understandable.

When feature files are stored in the right place, Cucumber can discover them reliably, build tools can process them correctly, CI/CD pipelines can run them consistently, and teams can review them easily. A clean feature file location is one of the simplest ways to make a Cucumber JVM framework more professional and maintainable.