# mnashed13/playwright-testing-framework architecture

> Architecture diagram of the GitHub repository mnashed13/playwright-testing-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mnashed13/playwright-testing-framework
- Repository: https://github.com/mnashed13/playwright-testing-framework

## Overview

#### Purpose and Entry Points
This is a Node.js TypeScript automated-testing framework combining Cucumber BDD scenarios with Playwright. It has separate UI/browser and API test suites. Main execution is through npm scripts in `package.json`, with Cucumber profiles/configuration in `cucumber.cjs` and browser settings in `playwright.config.ts`.

#### UI BDD Test Pipeline
UI scenarios begin as Gherkin features, are bound to Cucumber step definitions, then drive browser interactions through page objects:
- `src/features/login.feature`
- `src/steps/login.steps.ts`
- `src/pages/login.page.ts`

The UI suite is invoked by `npm test`; Cucumber is the scenario orchestrator and Playwright supplies browser automation and assertions.

#### UI Runtime Lifecycle and State Boundary
A custom Cucumber World holds per-scenario Playwright state, while hooks establish and dispose browser/page resources around scenarios. Environment handling is isolated from feature and page code:
- `src/support/world.ts`
- `src/support/hooks.ts`
- `src/support/env.ts`

This separates declarative scenarios and step logic from browser lifecycle, credentials, runtime browser selection, and environment-dependent values.

#### Page-Object Automation Layer
Page objects encapsulate navigation, locators, and UI operations; steps should express business actions rather than selectors. `BasePage` provides shared browser-page behavior, and `LoginPage` specializes login interactions:
- `src/pages/base.page.ts`
- `src/pages/login.page.ts`
- `src/test-data/test-data.ts`

Test data is kept outside scenario and page control flow, reducing direct dependence on credentials or fixed UI inputs.

#### API BDD Test Pipeline
API tests are a parallel Cucumber suite with no browser-page dependency. Features select endpoint behaviors, step definitions issue requests via a shared client, and the API World retains scenario request/response context:
- `api-tests/features/echo-api.feature`
- `api-tests/steps/echo-api.steps.ts`
- `api-tests/support/api-client.ts`

The user endpoint coverage follows the same pattern in `api-tests/features/user-api.feature` and `api-tests/steps/users-api.steps.ts`. API execution is exposed through `npm run test:api`, smoke filtering, and Echo-specific scripts.

#### API Diagnostics and Reporting
The API client boundary centralizes external HTTP communication. Supporting code formats reproducible curl representations and generates test reports:
- `api-tests/support/world.ts`
- `api-tests/support/curl-formatter.ts`
- `api-tests/support/report-generator.ts`

Generated artifacts include Cucumber HTML/JSON under `reports/` and API report generation entry code in `api-tests/generate-report.ts`. Browser-oriented output is published under `playwright-report/`.

#### Build, CI, and Release Boundaries
Source TypeScript is compiled into committed/generated JavaScript under `dist/`, which mirrors the UI suite structure:
- `tsconfig.json`
- `dist/steps/login.steps.js`
- `dist/support/world.js`

CI is represented across GitHub Actions, Buildkite, and Azure pipeline definitions. GitHub Actions runs API tests and semantic-release; release flow treats passing tests and report artifacts as a release gate:
- `.github/workflows/api-tests.yml`
- `.github/workflows/semantic-release.yml`
- `.buildkite/pipeline.yml`

External dependencies/material runtimes are Node.js, Cucumber.js, Playwright, target web applications for UI testing, and target HTTP services for API testing.

Main entry points: [`src/steps/login.steps.ts`](https://github.com/mnashed13/playwright-testing-framework/blob/main/src/steps/login.steps.ts) (Login steps), [`src/pages/login.page.ts`](https://github.com/mnashed13/playwright-testing-framework/blob/main/src/pages/login.page.ts) (LoginPage), [`api-tests/steps/echo-api.steps.ts`](https://github.com/mnashed13/playwright-testing-framework/blob/main/api-tests/steps/echo-api.steps.ts) (API step definitions), [`api-tests/support/api-client.ts`](https://github.com/mnashed13/playwright-testing-framework/blob/main/api-tests/support/api-client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI BDD Suite"]
  node_cucumber_ui{{"Cucumber UI runner<br/>scenario orchestrator<br/>[cucumber.cjs]"}}
  node_ui_features["Login feature<br/>Gherkin feature<br/>[login.feature]"]
  node_ui_steps["Login steps<br/>step definitions<br/>[login.steps.ts]"]
  node_ui_world["UI World<br/>scenario state<br/>[world.ts]"]
  node_ui_hooks["UI hooks<br/>lifecycle hooks<br/>[hooks.ts]"]
  node_env["Environment settings<br/>runtime config<br/>[env.ts]"]
  node_base_page["BasePage<br/>page-object base<br/>[base.page.ts]"]
  node_login_page["LoginPage<br/>page object<br/>[login.page.ts]"]
  node_test_data["Test data<br/>test inputs<br/>[test-data.ts]"]
  node_playwright{{"Playwright<br/>browser automation"}}
  node_target_web(("Target web app<br/>external application"))
end

subgraph group_api["API BDD Suite"]
  node_api_features["API features<br/>Gherkin features<br/>[echo-api.feature]"]
  node_api_steps["API step definitions<br/>[echo-api.steps.ts]"]
  node_api_world["API World<br/>scenario context<br/>[world.ts]"]
  node_api_client{{"API client<br/>HTTP client boundary<br/>[api-client.ts]"}}
  node_target_api(("Target HTTP services<br/>external service"))
  node_curl["curl formatter<br/>diagnostics<br/>[curl-formatter.ts]"]
  node_reports["API report generator<br/>reporting"]
end

subgraph group_platform["Runtime &amp; Delivery"]
  node_npm{{"npm scripts<br/>entry point<br/>[package.json]"}}
  node_typescript_build["TypeScript build<br/>compiler output<br/>[tsconfig.json]"]
  node_dist["Compiled UI suite<br/>generated JavaScript<br/>[login.steps.js]"]
  node_ci{{"CI and release<br/>pipeline<br/>[api-tests.yml]"}}
end

node_npm -->|"npm test"| node_cucumber_ui
node_npm -->|"test:api"| node_api_features
node_cucumber_ui -->|"executes"| node_ui_features
node_ui_features -->|"binds steps"| node_ui_steps
node_ui_steps -->|"uses"| node_login_page
node_ui_steps -->|"reads state"| node_ui_world
node_ui_hooks -->|"initializes"| node_ui_world
node_ui_hooks -->|"manages"| node_playwright
node_env -->|"configures"| node_ui_hooks
node_base_page -->|"shared behavior"| node_login_page
node_login_page -->|"automates through"| node_playwright
node_login_page -->|"interacts with"| node_target_web
node_test_data -->|"supplies inputs"| node_ui_steps
node_api_features -->|"binds steps"| node_api_steps
node_api_steps -->|"stores context"| node_api_world
node_api_steps -->|"issues requests"| node_api_client
node_api_client -->|"HTTP calls"| node_target_api
node_api_client -.->|"diagnostics"| node_curl
node_api_world -->|"report data"| node_reports
node_typescript_build -->|"emits"| node_dist
node_ci -->|"runs test gates"| node_npm
node_ci -->|"publishes artifacts"| node_reports

click node_npm "https://github.com/mnashed13/playwright-testing-framework/blob/main/package.json"
click node_cucumber_ui "https://github.com/mnashed13/playwright-testing-framework/blob/main/cucumber.cjs"
click node_ui_features "https://github.com/mnashed13/playwright-testing-framework/blob/main/src/features/login.feature"
click node_ui_steps "https://github.com/mnashed13/playwright-testing-framework/blob/main/src/steps/login.steps.ts"
click node_ui_world "https://github.com/mnashed13/playwright-testing-framework/blob/main/src/support/world.ts"
click node_ui_hooks "https://github.com/mnashed13/playwright-testing-framework/blob/main/src/support/hooks.ts"
click node_env "https://github.com/mnashed13/playwright-testing-framework/blob/main/src/support/env.ts"
click node_base_page "https://github.com/mnashed13/playwright-testing-framework/blob/main/src/pages/base.page.ts"
click node_login_page "https://github.com/mnashed13/playwright-testing-framework/blob/main/src/pages/login.page.ts"
click node_test_data "https://github.com/mnashed13/playwright-testing-framework/blob/main/src/test-data/test-data.ts"
click node_playwright "https://github.com/mnashed13/playwright-testing-framework/blob/main/playwright.config.ts"
click node_api_features "https://github.com/mnashed13/playwright-testing-framework/blob/main/api-tests/features/echo-api.feature"
click node_api_steps "https://github.com/mnashed13/playwright-testing-framework/blob/main/api-tests/steps/echo-api.steps.ts"
click node_api_world "https://github.com/mnashed13/playwright-testing-framework/blob/main/api-tests/support/world.ts"
click node_api_client "https://github.com/mnashed13/playwright-testing-framework/blob/main/api-tests/support/api-client.ts"
click node_curl "https://github.com/mnashed13/playwright-testing-framework/blob/main/api-tests/support/curl-formatter.ts"
click node_reports "https://github.com/mnashed13/playwright-testing-framework/blob/main/api-tests/support/report-generator.ts"
click node_typescript_build "https://github.com/mnashed13/playwright-testing-framework/blob/main/tsconfig.json"
click node_dist "https://github.com/mnashed13/playwright-testing-framework/blob/main/dist/steps/login.steps.js"
click node_ci "https://github.com/mnashed13/playwright-testing-framework/blob/main/.github/workflows/api-tests.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cucumber_ui,node_ui_features,node_ui_steps,node_ui_world,node_ui_hooks,node_env,node_base_page,node_login_page,node_test_data,node_playwright,node_target_web toneBlue
class node_api_features,node_api_steps,node_api_world,node_api_client,node_target_api,node_curl,node_reports toneAmber
class node_npm,node_typescript_build,node_dist,node_ci toneMint
```

## Components

### UI BDD Suite

- [Cucumber UI runner](https://github.com/mnashed13/playwright-testing-framework/blob/main/cucumber.cjs): scenario orchestrator · `cucumber.cjs`
- [Login feature](https://github.com/mnashed13/playwright-testing-framework/blob/main/src/features/login.feature): Gherkin feature · `src/features/login.feature`
- [Login steps](https://github.com/mnashed13/playwright-testing-framework/blob/main/src/steps/login.steps.ts): step definitions · `src/steps/login.steps.ts`
- [UI World](https://github.com/mnashed13/playwright-testing-framework/blob/main/src/support/world.ts): scenario state · Holds per-scenario Playwright state. · `src/support/world.ts`
- [UI hooks](https://github.com/mnashed13/playwright-testing-framework/blob/main/src/support/hooks.ts): lifecycle hooks · Creates and disposes browser resources per scenario. · `src/support/hooks.ts`
- [Environment settings](https://github.com/mnashed13/playwright-testing-framework/blob/main/src/support/env.ts): runtime config · `src/support/env.ts`
- [BasePage](https://github.com/mnashed13/playwright-testing-framework/blob/main/src/pages/base.page.ts): page-object base · `src/pages/base.page.ts`
- [LoginPage](https://github.com/mnashed13/playwright-testing-framework/blob/main/src/pages/login.page.ts): page object · Encapsulates login navigation and locators. · `src/pages/login.page.ts`
- [Test data](https://github.com/mnashed13/playwright-testing-framework/blob/main/src/test-data/test-data.ts): test inputs · `src/test-data/test-data.ts`
- [Playwright](https://github.com/mnashed13/playwright-testing-framework/blob/main/playwright.config.ts): browser automation · Drives browser interactions and assertions. · `playwright.config.ts`
- **Target web app**: external application

### API BDD Suite

- [API features](https://github.com/mnashed13/playwright-testing-framework/blob/main/api-tests/features/echo-api.feature): Gherkin features · Covers echo and user endpoint behavior. · `api-tests/features/echo-api.feature`
- [API step definitions](https://github.com/mnashed13/playwright-testing-framework/blob/main/api-tests/steps/echo-api.steps.ts): step definitions · Echo and user scenarios bind endpoint actions. · `api-tests/steps/echo-api.steps.ts`
- [API World](https://github.com/mnashed13/playwright-testing-framework/blob/main/api-tests/support/world.ts): scenario context · Retains request and response state. · `api-tests/support/world.ts`
- [API client](https://github.com/mnashed13/playwright-testing-framework/blob/main/api-tests/support/api-client.ts): HTTP client boundary · Centralizes external HTTP requests. · `api-tests/support/api-client.ts`
- **Target HTTP services**: external service
- [curl formatter](https://github.com/mnashed13/playwright-testing-framework/blob/main/api-tests/support/curl-formatter.ts): diagnostics · Formats reproducible request commands. · `api-tests/support/curl-formatter.ts`
- [API report generator](https://github.com/mnashed13/playwright-testing-framework/blob/main/api-tests/support/report-generator.ts): reporting · Generates Cucumber HTML and JSON artifacts. · `api-tests/support/report-generator.ts`

### Runtime & Delivery

- [npm scripts](https://github.com/mnashed13/playwright-testing-framework/blob/main/package.json): entry point · Runs UI and API test commands. · `package.json`
- [TypeScript build](https://github.com/mnashed13/playwright-testing-framework/blob/main/tsconfig.json): compiler output · Compiles suite source into dist/. · `tsconfig.json`
- [Compiled UI suite](https://github.com/mnashed13/playwright-testing-framework/blob/main/dist/steps/login.steps.js): generated JavaScript · `dist/steps/login.steps.js`
- [CI and release](https://github.com/mnashed13/playwright-testing-framework/blob/main/.github/workflows/api-tests.yml): pipeline · Runs API tests and semantic release after test gates. · `.github/workflows/api-tests.yml`

## Connections

- npm scripts → Cucumber UI runner: npm test
- npm scripts → API features: test:api
- Cucumber UI runner → Login feature: executes
- Login feature → Login steps: binds steps
- Login steps → LoginPage: uses
- Login steps → UI World: reads state
- UI hooks → UI World: initializes
- UI hooks → Playwright: manages
- Environment settings → UI hooks: configures
- BasePage → LoginPage: shared behavior
- LoginPage → Playwright: automates through
- LoginPage → Target web app: interacts with
- Test data → Login steps: supplies inputs
- API features → API step definitions: binds steps
- API step definitions → API World: stores context
- API step definitions → API client: issues requests
- API client → Target HTTP services: HTTP calls
- API client → curl formatter: diagnostics
- API World → API report generator: report data
- TypeScript build → Compiled UI suite: emits
- CI and release → npm scripts: runs test gates
- CI and release → API report generator: publishes artifacts