ADR-009-d — BDD + E2E Testing (Gherkin + Playwright)

ADR-009-d — BDD + E2E Testing (Gherkin + Playwright)

Status

Draft

Context

No end-to-end tests exist. No user flow is validated through the full stack (browser → Angular → Django → PostgreSQL). BDD scenarios will serve as both acceptance specification and executable tests.

Decision

BDD scenarios and E2E tests are unified into a single framework using playwright-bdd — a binding that connects Gherkin .feature files to Playwright step definitions.

Architecture.

e2e/
├── playwright.config.ts
├── features/                        ← Gherkin .feature files (the spec)
│   ├── auth/
│   │   ├── login.feature
│   │   └── logout.feature
│   ├── roster/
│   │   ├── employee-list.feature
│   │   └── employee-detail.feature
│   ├── org-chart/
│   │   ├── tree-navigation.feature
│   │   └── assign-worker.feature
│   ├── structure/
│   │   └── create-unit.feature
│   └── coverage/
│       └── dashboard.feature
├── steps/                           ← TypeScript step definitions
│   ├── auth.steps.ts
│   ├── roster.steps.ts
│   ├── org-chart.steps.ts
│   └── common.steps.ts
├── fixtures/
│   └── auth.fixture.ts             ← Reusable login state
└── support/
    └── world.ts                     ← Shared context

Principles.

• Feature files are the spec. Written in Spanish (UI language), readable by non-developers. They describe what the user does, not how the DOM is structured.
• Step definitions are TypeScript. They use Playwright’s API to interact with the browser. Named in English per [[adr-001-b-language-conventions|ADR-001-b]].
• One feature per user flow. Each .feature maps to a complete operational workflow, not a single page.
• playwright-bdd binds them. Gherkin scenarios execute as Playwright tests. No separate runner needed.

Example.

e2e/features/org-chart/assign-worker.feature

Funcionalidad: Asignar empleado a puesto vacante

  Escenario: Admin asigna empleado activo a puesto sin asignación
    Dado que estoy autenticado como admin
    Y existe un puesto vacante en "Unidad Guardia"
    Y existe un empleado activo "García, María"
    Cuando navego al organigrama y selecciono "Unidad Guardia"
    Y hago click en "Asignar" en el puesto vacante
    Y selecciono "García, María"
    Entonces el puesto muestra "García, María" como asignada
    Y la cobertura de la unidad aumenta

Scope. Deferred until core modules (org-chart, roster, assignments) are feature-complete. Initial implementation will target 5-8 critical flows:

1. Login → Dashboard visible
2. Roster: search → detail view
3. Org-chart: navigate tree → view unit positions
4. Assign employee to vacant position
5. Structure: create unit + create position

Accessibility. An axe-scan.feature will run @axe-core/playwright against the 5 main pages after each E2E suite run, per [[adr-013-accessibility|ADR-013]].

Consequences

• (+) BDD scenarios serve as both specification and executable tests — single source of truth for acceptance criteria.
• (+) Feature files in Spanish match the UI language, making them readable by clinical stakeholders.
• (+) Playwright provides reliable cross-browser testing with auto-waiting and trace capture.
• (+) playwright-bdd avoids maintaining two separate frameworks.
• (-) Gherkin step definitions add an abstraction layer over Playwright’s already expressive API.
• (-) Feature files can become brittle if UI copy changes frequently.
• (-) Deferred implementation means no E2E safety net until core modules stabilize.