festipod/.project/knowledge/bdd-testing.md

BDD Testing

Cucumber/Gherkin BDD specs in French with multi-layer step definitions.

Overview

• 26 feature files (US-1 to US-26), all in French
• Categories: EVENT, WORKSHOP, USER, MEETING, NOTIF
• Priorities: 0 (Impossible), 1 (Haute), 2 (Moyenne), 3 (Basse)
• Current results: 51 passed, 7 failed, 75 skipped (133 scenarios total)

Multi-Layer BDD

Each module has step directories for three test layers:

src/modules/event/steps/
  ui/           # UI/screen assertions (source analysis)
  data/         # Data layer assertions (Playwright + broker)
  e2e/          # E2E assertions (Playwright + broker + real app UI)

Shared steps (cross-domain) live in src/shared/steps/ui/.

Feature Files

Collocated with their module:

src/modules/event/features/us-13-creer-evenement.feature
src/modules/user/features/us-23-connexion-utilisateurs.feature
src/modules/workshop/features/us-1-visualiser-atelier-termine.feature
...

Tagged with @CATEGORY @priority-N for filtering.

Step Definitions

Shared Steps (src/shared/steps/ui/)

File	Purpose
navigation.steps.ts	Screen navigation, authentication, click/select actions, section/button/field assertions
form.steps.ts	Form field validation, required fields, import/duplicate detection
screen.steps.ts	Screen content assertions (participants, events, profiles, QR codes)

How UI Steps Work

@ui steps render the screen with LocalDataProvider (seed data) and RouterProvider via happy-dom, then assert on the rendered DOM. The render helper lives in src/shared/test-harness/renderHelper.tsx and is invoked from world.ts:renderCurrentScreen() on every navigateTo(...).

See test-layer-contracts for what @ui is allowed to test and the patterns to follow (and avoid).

Legacy: screenFileMap, screenFieldDetectors, screenExpectedContent, screenRequiredFields in world.ts are vestiges of an earlier source-code-grep approach. hasText/hasField/hasElement now prefer the rendered DOM and fall back to source so unmigrated steps keep working during the transition.

Screen Name Resolution

French names in .feature files map to screen IDs via screenNameMap:

• "accueil" → home
• "détail événement" → event-detail
• "mon profil" → profile
• "relayer un événement" → create-event

Cucumber Configuration

cucumber.json:

{
  "default": {
    "import": [
      "src/shared/support/**/*.ts",
      "src/shared/steps/**/*.ts",
      "src/modules/*/steps/**/*.ts"
    ],
    "paths": ["src/modules/*/features/**/*.feature"],
    "language": "fr"
  }
}

Requires tsx loader: node --import tsx/esm node_modules/.bin/cucumber-js

Auto-Generated Files

Scripts in scripts/ parse features and steps into TypeScript data files consumed by the prototyping tool:

Script	Input	Output
parse-features.ts	src/modules/*/features/*.feature	src/shared/data/features.ts
parse-test-results.ts	reports/cucumber-report.json	src/shared/data/testResults.ts
extract-step-definitions.ts	src/shared/steps/ui/*.ts	src/shared/data/stepDefinitions.ts

Run all: bun run test:cucumber

Data-Layer Testing

@data scenarios test through the real NextGraph broker. See data-layer-testing for full architecture.

E2E Testing

@e2e scenarios test the real app running in the broker iframe. See data-layer-testing for architecture. Key differences from @data:

• Uses the real app (not a test harness) served on a local HTTP port
• Interacts via Playwright locators and evaluate() on the app iframe
• Tests actual UI behavior: navigation, redirects, button clicks, screen content
• Requires real broker mode (fails with Error if broker unavailable)

Adding New Steps

1. Module-specific: Create in src/modules/{module}/steps/ui/
2. Cross-domain: Add to src/shared/steps/ui/
3. Import FestipodWorld type from ../../support/world (shared) or adjust relative path
4. Run bun run steps:extract to regenerate tooltip data