# thewikidea/leaf-automated-tests architecture

> Architecture diagram of the GitHub repository thewikidea/leaf-automated-tests, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thewikidea/leaf-automated-tests
- Repository: https://github.com/thewikidea/leaf-automated-tests

## Overview

This repository is not the LEAF application itself; it is the automated test suite for LEAF, the target system hosted elsewhere. Architecturally, it is split into two independent test harnesses that validate different layers of behavior: API-level contract testing in Go and browser-level end-to-end testing with Playwright.

The main system boundary is external: both test suites connect to a running LEAF development environment at `https://host.docker.internal/` and exercise the deployed app through its HTTP APIs and UI. The tests do not appear to mock LEAF internals; instead they verify the behavior of the integrated system as a black-box consumer.

`API-tests/` is the service/API validation layer. It is a Go module with many focused test files grouped by domain: `employee`, `events`, `form`, `group`, `platform`, `service`, `workflow`, plus auth/redirect coverage. This layer is likely doing direct HTTP/API calls and asserting response correctness, status codes, and data shape.

Within `API-tests/`, the presence of `database/nexus_test_db.sql` and `database/portal_test_db.sql` plus `dbsetup_test.go` shows that the API tests also depend on seeded relational test data. That means the API layer is not just stateless request/response testing; it validates behavior against a known database state and probably resets or prepares fixtures before execution.

`API-tests/helper_test.go`, `main_test.go`, and `hotspot_benchmarks_test.go` suggest shared test scaffolding and some performance-oriented coverage. The domain-specific files such as `formQuery.go`, `formStack.go`, and `formWorkflow.go` indicate that some tests model LEAF’s internal business objects and workflows rather than purely testing raw endpoints.

`api-test-helper/` is a small Go utility module with its own `main.go`. It likely exists to support API test execution or environment setup, acting as a lightweight companion tool rather than a separate product subsystem.

`end2end/` is the UI validation layer. It is a Node/TypeScript Playwright project with `playwright.config.ts`, `global.setup.ts`, `main.js`, `package.json`, and a suite of `.spec.ts` files. This layer drives a browser and verifies user-visible flows end to end.

The Playwright test suite is organized around user journeys and application areas: inbox, lifecycle/request creation, admin panels, report builder, organizational chart, mass actions, email templates, print view, advanced search, and account updater flows. These tests cover cross-cutting interactions that span UI, backend, and database state, which complements the lower-level API suite.

`end2end/tests/global.setup.ts` likely prepares shared authentication or environment state before the browser suite runs. The variety of specs implies that the end-to-end tests are scenario-based rather than unit-like, and they validate that LEAF features work together through the actual UI.

The repository also contains documentation artifacts under `end2end/docs/` and issue templates in `.github/`, which support test management rather than runtime behavior. The Excel files suggest manual QA planning or traceability alongside automation.

CI/CD is handled through GitHub Actions in `.github/workflows/`, with CodeQL analysis and pull-request automation. This indicates the repo is set up to enforce code health and run validation on changes, though the actual test execution likely depends on external LEAF environment availability.

For an architecture diagram, the key flows are: developer/CI triggers API tests and Playwright tests; both suites connect outward to a running LEAF instance; API tests additionally depend on seeded test databases; end-to-end tests depend on browser automation setup; and GitHub Actions provides the repository-level automation and security scanning around those test assets.

Main entry points: [`API-tests`](https://github.com/thewikidea/leaf-automated-tests/tree/main/API-tests) (API tests), [`end2end`](https://github.com/thewikidea/leaf-automated-tests/tree/main/end2end) (Playwright suite), [`.github/workflows/pullrequests.yml`](https://github.com/thewikidea/leaf-automated-tests/blob/main/.github/workflows/pullrequests.yml) (PR checks), [`.github/workflows`](https://github.com/thewikidea/leaf-automated-tests/blob/main/.github/workflows) (GitHub Actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ci["CI / repo automation"]
  node_n_ci_actions["GitHub Actions<br/>workflow automation<br/>[workflows]"]
  node_n_ci_codeql["CodeQL<br/>security scanning"]
  node_n_ci_pr["PR checks<br/>validation workflow<br/>[pullrequests.yml]"]
end

subgraph group_group_api["API tests"]
  node_n_api_suite["API tests<br/>go test suite"]
  node_n_api_db[("Test DBs<br/>seeded sql fixtures")]
  node_n_api_setup["DB setup<br/>test bootstrap<br/>[dbsetup_test.go]"]
  node_n_api_helpers["Shared helpers<br/>test scaffolding<br/>[helper_test.go]"]
  node_n_api_domains["Domain cases<br/>domain test modules"]
  node_n_api_forms["Form models<br/>workflow fixtures<br/>[formQuery.go]"]
  node_n_api_perf["Hotspot bench<br/>benchmark tests"]
  node_n_api_tool["API helper tool<br/>go utility<br/>[main.go]"]
end

subgraph group_group_e2e["End-to-end tests"]
  node_n_e2e_suite["Playwright suite<br/>browser test project"]
  node_n_e2e_setup["Global setup<br/>suite bootstrap<br/>[global.setup.ts]"]
  node_n_e2e_config["Playwright config<br/>runner config"]
  node_n_e2e_ui["UI journeys<br/>spec collection"]
  node_n_e2e_docs["QA docs<br/>test documentation"]
end

subgraph group_group_external["External LEAF system"]
  node_n_leaf_http[("LEAF APIs<br/>external http service")]
  node_n_leaf_ui["LEAF UI<br/>external web app"]
  node_n_leaf_data[("LEAF data<br/>external database")]
end

node_n_ci_actions -->|"includes"| node_n_ci_codeql
node_n_ci_actions -->|"includes"| node_n_ci_pr
node_n_ci_pr -->|"runs"| node_n_api_suite
node_n_ci_pr -->|"runs"| node_n_e2e_suite
node_n_api_suite -->|"boots"| node_n_api_setup
node_n_api_setup -->|"loads"| node_n_api_db
node_n_api_suite -->|"shares"| node_n_api_helpers
node_n_api_suite -->|"covers"| node_n_api_domains
node_n_api_suite -->|"models"| node_n_api_forms
node_n_api_suite -->|"measures"| node_n_api_perf
node_n_api_suite -->|"supports"| node_n_api_tool
node_n_api_suite -->|"calls"| node_n_leaf_http
node_n_api_suite -->|"verifies"| node_n_leaf_data
node_n_e2e_suite -->|"configured by"| node_n_e2e_config
node_n_e2e_suite -->|"prepares"| node_n_e2e_setup
node_n_e2e_suite -->|"runs"| node_n_e2e_ui
node_n_e2e_suite -.->|"documents"| node_n_e2e_docs
node_n_e2e_suite -->|"drives"| node_n_leaf_ui
node_n_e2e_suite -->|"depends on"| node_n_leaf_http
node_n_e2e_suite -->|"observes"| node_n_leaf_data

click node_n_ci_actions "https://github.com/thewikidea/leaf-automated-tests/blob/main/.github/workflows"
click node_n_ci_codeql "https://github.com/thewikidea/leaf-automated-tests/blob/main/.github/workflows/codeql-analysis.yml"
click node_n_ci_pr "https://github.com/thewikidea/leaf-automated-tests/blob/main/.github/workflows/pullrequests.yml"
click node_n_api_suite "https://github.com/thewikidea/leaf-automated-tests/tree/main/API-tests"
click node_n_api_db "https://github.com/thewikidea/leaf-automated-tests/tree/main/API-tests/database"
click node_n_api_setup "https://github.com/thewikidea/leaf-automated-tests/blob/main/API-tests/dbsetup_test.go"
click node_n_api_helpers "https://github.com/thewikidea/leaf-automated-tests/blob/main/API-tests/helper_test.go"
click node_n_api_forms "https://github.com/thewikidea/leaf-automated-tests/blob/main/API-tests/formQuery.go"
click node_n_api_perf "https://github.com/thewikidea/leaf-automated-tests/blob/main/API-tests/hotspot_benchmarks_test.go"
click node_n_api_tool "https://github.com/thewikidea/leaf-automated-tests/blob/main/api-test-helper/main.go"
click node_n_e2e_suite "https://github.com/thewikidea/leaf-automated-tests/tree/main/end2end"
click node_n_e2e_setup "https://github.com/thewikidea/leaf-automated-tests/blob/main/end2end/tests/global.setup.ts"
click node_n_e2e_config "https://github.com/thewikidea/leaf-automated-tests/blob/main/end2end/playwright.config.ts"
click node_n_e2e_ui "https://github.com/thewikidea/leaf-automated-tests/tree/main/end2end/tests"
click node_n_e2e_docs "https://github.com/thewikidea/leaf-automated-tests/tree/main/end2end/docs"

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_n_ci_actions,node_n_ci_codeql,node_n_ci_pr toneBlue
class node_n_api_suite,node_n_api_db,node_n_api_setup,node_n_api_helpers,node_n_api_domains,node_n_api_forms,node_n_api_perf,node_n_api_tool toneAmber
class node_n_e2e_suite,node_n_e2e_setup,node_n_e2e_config,node_n_e2e_ui,node_n_e2e_docs toneMint
class node_n_leaf_http,node_n_leaf_ui,node_n_leaf_data toneRose
```

## Components

### CI / repo automation

GitHub Actions, templates, and policy files that govern validation and maintenance.

- [GitHub Actions](https://github.com/thewikidea/leaf-automated-tests/blob/main/.github/workflows): workflow automation · Runs code quality checks and pull-request automation. · `.github/workflows`
- [CodeQL](https://github.com/thewikidea/leaf-automated-tests/blob/main/.github/workflows/codeql-analysis.yml): security scanning · Static analysis and security scanning configuration. · `.github/workflows/codeql-analysis.yml`
- [PR checks](https://github.com/thewikidea/leaf-automated-tests/blob/main/.github/workflows/pullrequests.yml): validation workflow · Pull request automation and repository checks. · `.github/workflows/pullrequests.yml`

### API tests

Go-based contract and database-backed validation against the LEAF system.

- [API tests](https://github.com/thewikidea/leaf-automated-tests/tree/main/API-tests): go test suite · Contract and behavior tests for LEAF's HTTP and domain APIs. · `API-tests`
- [Test DBs](https://github.com/thewikidea/leaf-automated-tests/tree/main/API-tests/database): seeded sql fixtures · Seed data used to prepare and validate API test state. · `API-tests/database`
- [DB setup](https://github.com/thewikidea/leaf-automated-tests/blob/main/API-tests/dbsetup_test.go): test bootstrap · Prepares or resets database state for the API suite. · `API-tests/dbsetup_test.go`
- [Shared helpers](https://github.com/thewikidea/leaf-automated-tests/blob/main/API-tests/helper_test.go): test scaffolding · Common test support used across API test cases. · `API-tests/helper_test.go`
- **Domain cases**: domain test modules · Focused coverage for employee, events, form, group, platform, service, workflow, login, and redirects.
- [Form models](https://github.com/thewikidea/leaf-automated-tests/blob/main/API-tests/formQuery.go): workflow fixtures · Form query, stack, and workflow modeling used by the API suite. · `API-tests/formQuery.go`
- [Hotspot bench](https://github.com/thewikidea/leaf-automated-tests/blob/main/API-tests/hotspot_benchmarks_test.go): benchmark tests · Performance-oriented API coverage. · `API-tests/hotspot_benchmarks_test.go`
- [API helper tool](https://github.com/thewikidea/leaf-automated-tests/blob/main/api-test-helper/main.go): go utility · Small companion executable used to support API test execution or setup. · `api-test-helper/main.go`

### End-to-end tests

Playwright browser suite that exercises LEAF through the UI.

- [Playwright suite](https://github.com/thewikidea/leaf-automated-tests/tree/main/end2end): browser test project · Node/TypeScript end-to-end tests driven through a real browser. · `end2end`
- [Global setup](https://github.com/thewikidea/leaf-automated-tests/blob/main/end2end/tests/global.setup.ts): suite bootstrap · Shared Playwright initialization such as authentication or environment setup. · `end2end/tests/global.setup.ts`
- [Playwright config](https://github.com/thewikidea/leaf-automated-tests/blob/main/end2end/playwright.config.ts): runner config · Defines how the browser suite is executed. · `end2end/playwright.config.ts`
- [UI journeys](https://github.com/thewikidea/leaf-automated-tests/tree/main/end2end/tests): spec collection · Scenario-based browser coverage for inbox, lifecycle, admin, reports, search, templates, print, and account flows. · `end2end/tests`
- [QA docs](https://github.com/thewikidea/leaf-automated-tests/tree/main/end2end/docs): test documentation · Manual test planning and traceability artifacts. · `end2end/docs`

### External LEAF system

The running LEAF environment hosted outside this repository that both test harnesses target.

- **LEAF APIs**: external http service · Running LEAF development environment exercised by the API suite.
- **LEAF UI**: external web app · Browser-facing LEAF application exercised by Playwright.
- **LEAF data**: external database · Underlying application state and relational data observed by the tests.

## Connections

- GitHub Actions → CodeQL: includes · Workflow definition for security scanning.
- GitHub Actions → PR checks: includes · Workflow definition for pull-request automation.
- PR checks → API tests: runs · Triggers the API validation suite.
- PR checks → Playwright suite: runs · Triggers the browser validation suite.
- API tests → DB setup: boots · Prepares test database state before execution.
- DB setup → Test DBs: loads · Uses seeded SQL fixtures.
- API tests → Shared helpers: shares · Common scaffolding across tests.
- API tests → Domain cases: covers · Domain-specific HTTP and behavior checks.
- API tests → Form models: models · Encodes form and workflow business objects.
- API tests → Hotspot bench: measures · Benchmark coverage.
- API tests → API helper tool: supports · Companion utility for API test execution.
- API tests → LEAF APIs: calls · Black-box HTTP/API validation against LEAF.
- API tests → LEAF data: verifies · Assertions depend on seeded database state.
- Playwright suite → Playwright config: configured by · Playwright execution settings.
- Playwright suite → Global setup: prepares · Shared browser-suite initialization.
- Playwright suite → UI journeys: runs · Scenario-based browser specs.
- Playwright suite → QA docs: documents · Manual QA and traceability artifacts.
- Playwright suite → LEAF UI: drives · Browser-based black-box interaction with LEAF.
- Playwright suite → LEAF APIs: depends on · UI flows rely on the live LEAF backend.
- Playwright suite → LEAF data: observes · Flows are validated against persistent system state.
