# ianahilario/playwright-notion-reporter architecture

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

- Interactive diagram: https://gitdiagram.com/ianahilario/playwright-notion-reporter
- Repository: https://github.com/ianahilario/playwright-notion-reporter

## Overview

1. This repository is a small TypeScript package, not an app: it plugs into Playwright Test as a custom reporter and writes one summary row per test run into a Notion database.

2. The runtime boundary is the Playwright test process. The reporter receives test lifecycle events from `@playwright/test`, aggregates results for the whole run, and only at the end sends a single write to Notion.

3. The main entrypoint is `src/index.ts`, which exposes the reporter implementation and the option types consumed from `playwright.config.ts`. This is the public API that downstream projects import via the package name.

4. The core data flow is: individual test attempts → reporter counts outcomes → final run summary → Notion database row. The summary includes passed, failed, skipped, flaky, total, and optional duration; “flaky” means a test that eventually passed after retries, and only the last attempt per test is counted.

5. Configuration is the main integration boundary. Consumers provide `apiKey`, `databaseId`, a required `statusColumns` mapping to exact Notion property names, and optional extra `columns` for metadata like branch or CI run URL. Empty custom values are omitted rather than written as blanks.

6. The Notion schema is intentionally strict and matters architecturally: numeric columns must exist for counts, `Status` must be a Notion `Select` property rather than a `Status` property, and select values like `Passed`/`Failed` must already exist in the database.

7. Error handling is centralized in `src/notion-errors.ts`. Instead of surfacing raw Notion JSON, the reporter classifies failures into actionable categories such as authentication issues, inaccessible databases, missing columns, wrong property types, and invalid select values, then prints fix guidance.

8. A key operational boundary is graceful degradation: if `apiKey` or `databaseId` is missing, the reporter logs a skip message and does not fail the test run. That keeps CI/test execution independent from Notion availability or secrets setup.

9. The repository includes unit tests under `test/` for the counting logic and error categorization. These are likely the main verification layer for the reporter’s internal behavior without hitting Notion.

10. There is also an end-to-end example under `example/` with Playwright tests (`example/tests/demo.spec.ts`) and a root `playwright.config.ts`. That sample exercises the full integration path: Playwright run → reporter → live Notion database.

11. Tooling is lightweight and standard for a library: TypeScript compilation (`tsconfig.json`), Vitest for unit tests (`vitest.config.ts`), and Playwright config for the example suite (`playwright.config.ts` / `tsconfig.playwright.json`). The package-lock and `package.json` indicate an npm-distributed module.

12. In diagram terms, the important components are: caller project’s Playwright runner, this reporter package, the Notion API as the external persistence service, and the local test/example harness used to validate the integration. The system has no internal server or database of its own; Notion is the only durable sink.

Main entry points: [`src/index.ts`](https://github.com/ianahilario/playwright-notion-reporter/blob/main/src/index.ts) (Reporter API), [`src/notion-errors.ts`](https://github.com/ianahilario/playwright-notion-reporter/blob/main/src/notion-errors.ts) (Error Categories), [`example/tests/demo.spec.ts`](https://github.com/ianahilario/playwright-notion-reporter/blob/main/example/tests/demo.spec.ts) (Demo Tests), [`vitest.config.ts`](https://github.com/ianahilario/playwright-notion-reporter/blob/main/vitest.config.ts) (Vitest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_source["Source"]
  node_node_public_api["Reporter API<br/>package entrypoint<br/>[index.ts]"]
  node_node_lifecycle["Test Events<br/>run lifecycle<br/>[index.ts]"]
  node_node_aggregator["Run Summary<br/>counter aggregator<br/>[index.ts]"]
  node_node_config["Config Schema<br/>options contract<br/>[index.ts]"]
  node_node_writer[("Notion Write<br/>persistence client<br/>[index.ts]")]
  node_node_errors["Error Categories<br/>failure classifier<br/>[notion-errors.ts]"]
end

subgraph group_grp_tests["Tests"]
  node_node_unit_count["Count Tests<br/>vitest unit<br/>[reporter.test.ts]"]
  node_node_unit_errors["Error Tests<br/>vitest unit"]
end

subgraph group_grp_example["Example"]
  node_node_example_suite["Demo Tests<br/>playwright example<br/>[demo.spec.ts]"]
end

subgraph group_grp_tooling["Tooling"]
  node_node_vitest["Vitest<br/>test runner<br/>[vitest.config.ts]"]
  node_node_playwright_cfg["Playwright Config<br/>example config"]
  node_node_tsconfig["TypeScript Build<br/>compiler config<br/>[tsconfig.json]"]
end

subgraph group_grp_external["External"]
  node_node_playwright_runner["Playwright Test<br/>test runner"]
  node_node_notion_api[("Notion API<br/>external service")]
  node_node_package["npm Package<br/>distributed module<br/>[package.json]"]
end

node_node_package -->|"exports"| node_node_public_api
node_node_playwright_runner -->|"loads"| node_node_public_api
node_node_playwright_runner -->|"provides"| node_node_config
node_node_public_api -->|"handles"| node_node_lifecycle
node_node_lifecycle -->|"accumulates"| node_node_aggregator
node_node_aggregator -->|"summarizes"| node_node_writer
node_node_config -->|"configures"| node_node_writer
node_node_config -->|"filters"| node_node_aggregator
node_node_writer -->|"writes"| node_node_notion_api
node_node_writer -->|"classifies"| node_node_errors
node_node_public_api -->|"uses"| node_node_errors
node_node_unit_count -->|"verifies"| node_node_aggregator
node_node_unit_errors -->|"verifies"| node_node_errors
node_node_example_suite -->|"runs via"| node_node_playwright_cfg
node_node_playwright_cfg -->|"installs"| node_node_public_api
node_node_example_suite -->|"executes in"| node_node_playwright_runner
node_node_public_api -.->|"optionally skips"| node_node_notion_api
node_node_vitest -->|"runs"| node_node_unit_count
node_node_vitest -->|"runs"| node_node_unit_errors
node_node_tsconfig -->|"builds"| node_node_public_api

click node_node_public_api "https://github.com/ianahilario/playwright-notion-reporter/blob/main/src/index.ts"
click node_node_lifecycle "https://github.com/ianahilario/playwright-notion-reporter/blob/main/src/index.ts"
click node_node_aggregator "https://github.com/ianahilario/playwright-notion-reporter/blob/main/src/index.ts"
click node_node_config "https://github.com/ianahilario/playwright-notion-reporter/blob/main/src/index.ts"
click node_node_writer "https://github.com/ianahilario/playwright-notion-reporter/blob/main/src/index.ts"
click node_node_errors "https://github.com/ianahilario/playwright-notion-reporter/blob/main/src/notion-errors.ts"
click node_node_unit_count "https://github.com/ianahilario/playwright-notion-reporter/blob/main/test/reporter.test.ts"
click node_node_unit_errors "https://github.com/ianahilario/playwright-notion-reporter/blob/main/test/notion-errors.test.ts"
click node_node_example_suite "https://github.com/ianahilario/playwright-notion-reporter/blob/main/example/tests/demo.spec.ts"
click node_node_package "https://github.com/ianahilario/playwright-notion-reporter/blob/main/package.json"
click node_node_vitest "https://github.com/ianahilario/playwright-notion-reporter/blob/main/vitest.config.ts"
click node_node_playwright_cfg "https://github.com/ianahilario/playwright-notion-reporter/blob/main/playwright.config.ts"
click node_node_tsconfig "https://github.com/ianahilario/playwright-notion-reporter/blob/main/tsconfig.json"

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_node_public_api,node_node_lifecycle,node_node_aggregator,node_node_config,node_node_writer,node_node_errors toneBlue
class node_node_unit_count,node_node_unit_errors toneAmber
class node_node_example_suite toneMint
class node_node_vitest,node_node_playwright_cfg,node_node_tsconfig toneRose
class node_node_playwright_runner,node_node_notion_api,node_node_package toneIndigo
```

## Components

### Source

Published reporter implementation and shared runtime logic.

- [Reporter API](https://github.com/ianahilario/playwright-notion-reporter/blob/main/src/index.ts): package entrypoint · Public entrypoint exported by the package for Playwright Test consumers, including reporter implementation and option types. · `src/index.ts`
- [Test Events](https://github.com/ianahilario/playwright-notion-reporter/blob/main/src/index.ts): run lifecycle · Consumes Playwright Test lifecycle events for a whole run and coordinates aggregation. · `src/index.ts`
- [Run Summary](https://github.com/ianahilario/playwright-notion-reporter/blob/main/src/index.ts): counter aggregator · Aggregates the final run counts: passed, failed, skipped, flaky, total, and optional duration. · `src/index.ts`
- [Config Schema](https://github.com/ianahilario/playwright-notion-reporter/blob/main/src/index.ts): options contract · Reporter options boundary: apiKey, databaseId, statusColumns, and optional extra columns with omission of empty values. · `src/index.ts`
- [Notion Write](https://github.com/ianahilario/playwright-notion-reporter/blob/main/src/index.ts): persistence client · Sends one final database row to Notion at the end of the run. · `src/index.ts`
- [Error Categories](https://github.com/ianahilario/playwright-notion-reporter/blob/main/src/notion-errors.ts): failure classifier · Classifies Notion failures into actionable categories with fix guidance instead of raw API payloads. · `src/notion-errors.ts`

### Tests

Unit and example coverage for counting and error handling.

- [Count Tests](https://github.com/ianahilario/playwright-notion-reporter/blob/main/test/reporter.test.ts): vitest unit · Verifies outcome counting and retry/flaky semantics. · `test/reporter.test.ts`
- [Error Tests](https://github.com/ianahilario/playwright-notion-reporter/blob/main/test/notion-errors.test.ts): vitest unit · Verifies Notion error categorization and guidance. · `test/notion-errors.test.ts`

### Example

Playwright sample that exercises the full integration path.

- [Demo Tests](https://github.com/ianahilario/playwright-notion-reporter/blob/main/example/tests/demo.spec.ts): playwright example · Sample Playwright spec that exercises the reporter against a live Notion database. · `example/tests/demo.spec.ts`

### Tooling

Compilation and test runners for the package.

- [Vitest](https://github.com/ianahilario/playwright-notion-reporter/blob/main/vitest.config.ts): test runner · Unit-test harness used for repository verification. · `vitest.config.ts`
- [Playwright Config](https://github.com/ianahilario/playwright-notion-reporter/blob/main/playwright.config.ts): example config · Root Playwright configuration for the sample integration path. · `playwright.config.ts`
- [TypeScript Build](https://github.com/ianahilario/playwright-notion-reporter/blob/main/tsconfig.json): compiler config · TypeScript compilation setup for the published source. · `tsconfig.json`

### External

Upstream test runner and downstream persistence service.

- **Playwright Test**: test runner · External runtime boundary that invokes the reporter from the consumer project's test process.
- **Notion API**: external service · Remote database API used as the only durable sink for run summaries.
- [npm Package](https://github.com/ianahilario/playwright-notion-reporter/blob/main/package.json): distributed module · Published library consumed by downstream Playwright projects. · `package.json`

## Connections

- npm Package → Reporter API: exports · The package publishes the reporter entrypoint and option types.
- Playwright Test → Reporter API: loads · Consumer Playwright processes load the reporter implementation.
- Playwright Test → Config Schema: provides · Projects pass reporter options from Playwright config.
- Reporter API → Test Events: handles · The reporter receives test lifecycle events from Playwright.
- Test Events → Run Summary: accumulates · Per-test attempts are reduced into a final run summary.
- Run Summary → Notion Write: summarizes · The final aggregate is transformed into a single Notion row.
- Config Schema → Notion Write: configures · Credentials, database id, status mappings, and extra columns drive the write.
- Config Schema → Run Summary: filters · Empty custom values are omitted from the final payload.
- Notion Write → Notion API: writes · A single database row is sent to Notion after the run ends.
- Notion Write → Error Categories: classifies · Failures are converted into actionable categories and guidance.
- Reporter API → Error Categories: uses · Reporter code relies on centralized Notion error handling.
- Count Tests → Run Summary: verifies · Unit tests cover counting and flaky retry behavior.
- Error Tests → Error Categories: verifies · Unit tests cover error classification logic.
- Demo Tests → Playwright Config: runs via · The sample suite is executed through the root Playwright config.
- Playwright Config → Reporter API: installs · The example config wires the reporter into Playwright.
- Demo Tests → Playwright Test: executes in · The demo spec runs inside Playwright Test.
- Reporter API → Notion API: optionally skips · Missing apiKey or databaseId causes a graceful skip instead of a failing run.
- Vitest → Count Tests: runs · Vitest executes the unit test suite.
- Vitest → Error Tests: runs · Vitest executes the error classification tests.
- TypeScript Build → Reporter API: builds · TypeScript compilation targets the published source.