Q17 of 17 · Framework design

What does the folder structure of a well-organised BDD (Cucumber) framework look like?

Framework designMidframework-designbddcucumberfolder-structurearchitecture

Short answer

Short answer: Features in a features/ directory mirroring the app's domain, step definitions in a stepdefs/ package grouped by domain (not by feature file), page objects in pages/, shared context/world in support/, and config/reporting in dedicated folders.

Detail

Java — Maven Cucumber project:

src/
  test/
    java/
      com/example/
        stepdefs/
          AuthSteps.java          ← Login, registration, logout
          OrderSteps.java         ← Order creation, cancellation
          CommonSteps.java        ← Navigation, generic assertions
        pages/
          BasePage.java
          LoginPage.java
          OrderPage.java
        context/
          TestContext.java        ← Shared state injected via PicoContainer
        config/
          Configuration.java
        hooks/
          Hooks.java              ← @Before, @After, screenshots
        utils/
          DatabaseHelper.java
          ApiClient.java
    resources/
      features/
        auth/
          login.feature
          registration.feature
        orders/
          checkout.feature
          returns.feature
      config/
        staging.properties
        prod.properties

JavaScript — Cucumber + Playwright:

features/
  auth/
    login.feature
  orders/
    checkout.feature
step_definitions/
  auth.steps.js
  orders.steps.js
  common.steps.js
pages/
  LoginPage.js
  CheckoutPage.js
support/
  world.js           ← Custom World (state per scenario)
  hooks.js           ← Before/After
helpers/
  dbHelper.js
  apiClient.js
config/
  env.js
reports/             ← gitignored, generated by CI
cucumber.config.js

Key decisions:

  • Step defs grouped by domain, not feature file — AuthSteps is reused by login.feature, session-timeout.feature, and password-reset.feature. One file per feature creates duplication.
  • World / TestContext in a dedicated support/ or context/ folder — keeps it discoverable.
  • features/ mirrors the app's domain hierarchy — makes it easy to find tests for a given area.

// WHAT INTERVIEWERS LOOK FOR

Domain-grouped step definitions (not feature-grouped). Features directory mirroring app domain. Separate hooks, utils, and context files.

// Related questions

What is a recommended folder structure for a Playwright or Selenium test framework?

Framework design

How do you share state between step definitions in Cucumber without using static variables?

BDD / Cucumber

What are hooks in Cucumber, what types exist, and what should (and shouldn't) go in them?

BDD / Cucumber