# abishek-gitspace/suitecrm-playwright-e2e architecture

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

- Interactive diagram: https://gitdiagram.com/abishek-gitspace/suitecrm-playwright-e2e
- Repository: https://github.com/abishek-gitspace/suitecrm-playwright-e2e

## Overview

#### Purpose and Execution Model
This repository is a TypeScript Playwright end-to-end test suite for a locally hosted SuiteCRM instance. Its current implemented scope is authentication behavior: login success/failure, logout, and unauthenticated dashboard access. Test execution is driven by npm scripts in `package.json` and Playwright configuration in `playwright.config.ts`.

#### CRM Runtime Boundary
SuiteCRM is an external system under test, not application code in this repository. Docker Compose provisions the local CRM environment, expected at `http://localhost:8080`; browser tests interact with it only through its UI.
- `docker-compose.yml`
- `.env.example`
- `README.md`

#### Playwright Test Orchestration
`playwright.config.ts` is the central execution boundary for browser projects, workers, reporting, base URL behavior, and likely authentication-state reuse. The suite runs Chromium-based UI automation and separates a setup phase from normal authenticated tests.
- `playwright.config.ts`
- `package.json`
- `tests/auth.spec.ts`

#### Authentication Bootstrap and Session Reuse
Authentication setup logs in once and persists browser storage/session state for subsequent tests. This avoids repeating login for tests that require an authenticated SuiteCRM session, while explicit negative-access coverage can run without that state.
- `fixtures/auth.setup.ts`
- `playwright.config.ts`
- `tests/auth.spec.ts`

#### Page Object Layer
Page objects isolate SuiteCRM UI selectors and user workflows from test assertions. `BasePage` provides shared browser/page behavior, while `LoginPage` encapsulates login-page actions and state checks. This is the main maintainability boundary as future CRM modules are added.
- `pages/BasePage.ts`
- `pages/LoginPage.ts`
- `tests/auth.spec.ts`

#### Authentication Test Flow
`tests/auth.spec.ts` composes page objects and Playwright fixtures to verify the auth lifecycle: valid credentials reach the dashboard; invalid/empty input remains or errors on login; logout returns to login; and direct dashboard navigation without authentication redirects appropriately. Credentials/environment-specific values are expected to remain outside test code.
- `tests/auth.spec.ts`
- `pages/LoginPage.ts`
- `.env.example`

#### Tooling and Planned Integration Boundaries
The material runtime is Node.js/TypeScript plus Playwright and Chromium, with Docker hosting SuiteCRM. Allure reporting, GitHub Actions, and Claude-powered locator recovery are stated future phases rather than present architecture; no corresponding implementation paths appear in the repository tree.
- `package.json`
- `playwright.config.ts`
- `docker-compose.yml`

Main entry points: [`playwright.config.ts`](https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/playwright.config.ts) (Playwright configuration), [`fixtures/auth.setup.ts`](https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/fixtures/auth.setup.ts) (Authentication setup), [`docker-compose.yml`](https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/docker-compose.yml) (Docker Compose), [`pages/LoginPage.ts`](https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/pages/LoginPage.ts) (Login page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Local CRM Runtime"]
  node_docker_compose["Docker Compose<br/>CRM provisioning<br/>[docker-compose.yml]"]
  node_environment_template["Environment template<br/>environment contract<br/>[.env.example]"]
  node_suitecrm{{"SuiteCRM<br/>external system under test"}}
end

subgraph group_orchestration["Test Orchestration"]
  node_package["npm scripts &amp; dependencies<br/>Node.js tooling<br/>[package.json]"]
  node_playwright_config["Playwright configuration<br/>test configuration"]
end

subgraph group_automation["Browser Automation"]
  node_auth_setup["Authentication setup<br/>Playwright setup project<br/>[auth.setup.ts]"]
  node_auth_tests["Authentication tests<br/>Playwright spec<br/>[auth.spec.ts]"]
  node_base_page["Base page<br/>page object base<br/>[BasePage.ts]"]
  node_login_page["Login page<br/>page object<br/>[LoginPage.ts]"]
  node_browser(("Chromium browser<br/>Playwright browser runtime"))
  node_storage_state["Persisted session state<br/>browser storage state"]
end

node_readme["Repository guidance<br/>documentation<br/>[README.md]"]

node_package -->|"runs with"| node_playwright_config
node_playwright_config -->|"orders setup"| node_auth_setup
node_playwright_config -->|"runs spec"| node_auth_tests
node_docker_compose -->|"provisions"| node_suitecrm
node_environment_template -.->|"supplies environment"| node_docker_compose
node_environment_template -.->|"supplies credentials"| node_auth_setup
node_auth_setup -->|"uses"| node_login_page
node_auth_setup -->|"persists"| node_storage_state
node_auth_tests -->|"uses"| node_login_page
node_login_page -->|"extends"| node_base_page
node_playwright_config -->|"reuses for authenticated projects"| node_storage_state
node_playwright_config -->|"launches"| node_browser
node_browser -->|"drives UI at localhost:8080"| node_suitecrm
node_readme -.->|"documents setup"| node_docker_compose

click node_package "https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/package.json"
click node_playwright_config "https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/playwright.config.ts"
click node_docker_compose "https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/docker-compose.yml"
click node_environment_template "https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/.env.example"
click node_auth_setup "https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/fixtures/auth.setup.ts"
click node_auth_tests "https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/tests/auth.spec.ts"
click node_base_page "https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/pages/BasePage.ts"
click node_login_page "https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/pages/LoginPage.ts"
click node_readme "https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/README.md"

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_docker_compose,node_environment_template,node_suitecrm toneBlue
class node_package,node_playwright_config toneAmber
class node_auth_setup,node_auth_tests,node_base_page,node_login_page,node_browser,node_storage_state toneMint
class node_readme toneNeutral
```

## Components

### Local CRM Runtime

- [Docker Compose](https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/docker-compose.yml): CRM provisioning · Provisions the local SuiteCRM environment. · `docker-compose.yml`
- [Environment template](https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/.env.example): environment contract · Keeps credentials and environment-specific values outside test code. · `.env.example`
- **SuiteCRM**: external system under test · Locally hosted CRM reached only through the browser UI.

### Test Orchestration

- [npm scripts & dependencies](https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/package.json): Node.js tooling · Starts the Playwright test workflow. · `package.json`
- [Playwright configuration](https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/playwright.config.ts): test configuration · Defines projects, workers, reporting, base URL, and setup ordering. · `playwright.config.ts`

### Browser Automation

- [Authentication setup](https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/fixtures/auth.setup.ts): Playwright setup project · Logs in once and persists browser storage state. · `fixtures/auth.setup.ts`
- [Authentication tests](https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/tests/auth.spec.ts): Playwright spec · Covers login, logout, invalid input, and unauthenticated dashboard access. · `tests/auth.spec.ts`
- [Base page](https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/pages/BasePage.ts): page object base · Provides shared page/browser behavior. · `pages/BasePage.ts`
- [Login page](https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/pages/LoginPage.ts): page object · Encapsulates login selectors, actions, and state checks. · `pages/LoginPage.ts`
- **Chromium browser**: Playwright browser runtime · Executes UI automation against local SuiteCRM.
- **Persisted session state**: browser storage state · Reused by authenticated test projects.

### Other components

- [Repository guidance](https://github.com/abishek-gitspace/suitecrm-playwright-e2e/blob/main/README.md): documentation · Documents local CRM setup and test use. · `README.md`

## Connections

- npm scripts & dependencies → Playwright configuration: runs with
- Playwright configuration → Authentication setup: orders setup
- Playwright configuration → Authentication tests: runs spec
- Docker Compose → SuiteCRM: provisions
- Environment template → Docker Compose: supplies environment
- Environment template → Authentication setup: supplies credentials
- Authentication setup → Login page: uses
- Authentication setup → Persisted session state: persists
- Authentication tests → Login page: uses
- Login page → Base page: extends
- Playwright configuration → Persisted session state: reuses for authenticated projects
- Playwright configuration → Chromium browser: launches
- Chromium browser → SuiteCRM: drives UI at localhost:8080
- Repository guidance → Docker Compose: documents setup