# Framework Structure

This repository publishes a reusable BDD UI step library to npm. Consumer applications should not import framework code directly. They install the npm package, point Cucumber at the compiled support and step files, provide environment configuration, and write feature files using the shared step vocabulary.

## Top-level folders

```text
src/
  steps/      Reusable Cucumber step definitions.
  support/    Cucumber runtime setup such as World, hooks, config loading, and reporting glue.
  runtime/    Internal Playwright helpers used by steps and support files.
templates/    Starter files consumers can copy into their own test project.
examples/     A minimal consumer project proving the published package shape.
docs/         Framework developer and consumer documentation.
dist/         Compiled package output generated by npm run build.
```

## Where to add reusable steps

Add reusable, product-neutral Gherkin steps under `src/steps/`.

Use one file per step category:

```text
src/steps/navigation.steps.ts    URL and page navigation.
src/steps/interaction.steps.ts   Clicks, checks, selects, and user actions.
src/steps/form.steps.ts          Form input and credential-backed field entry.
src/steps/assertion.steps.ts     UI and URL assertions.
src/steps/wait.steps.ts          Explicit waits.
```

Every new step file must be imported by `src/steps/index.ts`. Cucumber loads `dist/steps/index.js`, and that file registers all reusable steps globally.

## Step design rules

Reusable steps must be generic and application-neutral. Prefer steps such as:

```gherkin
When I click the "Save" button
When I fill "Username" with credential "standardUser.username"
Then I should see text "Dashboard"
```

Avoid product-specific steps such as:

```gherkin
When I approve the trade ticket
Then the portfolio valuation should be recalculated
```

Those belong in the consuming application, not in this shared package.

## Where runtime setup lives

Use `src/support/` for Cucumber lifecycle code:

```text
world.ts    Custom Cucumber World with config, browser, context, and page.
hooks.ts    Before, AfterStep, and After hooks for browser startup, failing-step evidence, traces, and cleanup.
config.ts   Config loader for bdd-ui.config.json and BDD_UI_* environment variables.
allure.ts   Reporting helper functions.
index.ts    Imports support files so Cucumber can load one support entrypoint.
```

Use `src/runtime/` for internal helper logic that supports reusable steps:

```text
browser.ts       Browser launch logic.
credentials.ts   Credential lookup from config.
locator.ts       Shared locator conventions.
screenshots.ts   Screenshot helpers.
trace.ts         Trace file helpers.
```

Framework developers can use runtime helpers inside this package, but consumer apps should not need to import them.

## Consumer contract

A consuming app should only need these files:

```text
resources/features/**/*.feature
resources/4-config/bdd-ui.config.json
cucumber.js
```

For a brand-new consumer project, the framework can scaffold the starter layout with:

```bash
npx bdd-ui-init-resources
```

Add `--include-samples` if you want a sample `login.feature` and a sample input JSON file to be created alongside the
base structure.

The recommended consumer resource layout is:

```text
resources/
  features/
    login.feature
    extract-visible-grid.feature
    qte-acceptance-criteria.feature
  5-input/
    qte-acceptance-criteria/
      qte-ac-core-valid.json
    qte-global-field-synchronization/
      qte-global-sync.json
  3-expected/
    extract-visible-grid/
      qte-grid-list.json
    qte-acceptance-criteria/
      qte-created.json
  2-actual/
    extract-visible-grid/
      qte-grid-list.json
```

Keep `resources/features` flat, and keep the files inside each feature-name folder flat as well. In other words:
- feature files go directly under `resources/features`
- input files go directly under `resources/5-input/<feature-name>`
- expected artifacts go directly under `resources/3-expected/<feature-name>`
- actual artifacts go directly under `resources/2-actual/<feature-name>`

The consumer's `cucumber.js` should load:

```js
require: [
  './node_modules/@genesislcap/bdd-ui-automation/dist/support/index.js',
  './node_modules/@genesislcap/bdd-ui-automation/dist/steps/index.js'
]
```

The consumer's `resources/4-config/bdd-ui.config.json` owns environment-specific settings such as base URL,
browser, timeouts, credentials, and numbered resource roots (`1-payload`, `2-actual`, `3-expected`, `4-config`,
`5-input`, and `features`).

The planned backend response-comparison design also relies on that consumer contract:
- capture steps are defined in feature files under `resources/features`
- expected response JSON lives under `resources/3-expected/<feature-name>`
- captured actual response JSON is written under `resources/2-actual/<feature-name>`
- the comparator runtime is expected to be bundled inside the published npm package rather than resolved from Gradle
  or a local Maven cache at execution time

That design keeps consumer setup simple: install the npm package, provide Java on the execution machine, and let the
framework invoke the bundled comparator with the same API-style options (`parent object`, `primary key`, `ignore`,
`specific fields`, `fail on extra`) exposed through reusable Gherkin steps.
