# ryanrosello-og/playwright-slack-report architecture

> Architecture diagram of the GitHub repository ryanrosello-og/playwright-slack-report, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ryanrosello-og/playwright-slack-report
- Repository: https://github.com/ryanrosello-og/playwright-slack-report

## Overview

##### Project Type & Purpose
- This is a NodeJS/TypeScript library designed to integrate with Playwright testing. Its purpose is to take Playwright JSON test results and post summary reports to Slack channels.
- The README and file tree reveal support for two main scenarios:
– Integration as a Playwright reporter (via custom SlackReporter integration).
– A standalone CLI utility that processes merged JSON reports and sends them to Slack (using a dedicated configuration file and optional custom layouts).

##### Analyzing the File Structure
- Top-Level Files & Folders:
- Configuration files (.eslintrc.json, .prettierrc.js, tsconfig.json, package.json) and CI/CD related files under .github and .gitpod.
- The CLI entry point (cli.ts) and its configuration file (cli_config.json) indicate a command-line interface mode.
- The “custom_block” folder contains modules that define custom Slack message layouts.
- The “src” folder holds the core logic:
◦ LayoutGenerator.ts – for generating Slack message layouts.
◦ ResultsParser.ts – for processing Playwright JSON results.
◦ SlackClient.ts and SlackWebhookClient.ts – for handling communication with Slack (via bot OAuth or webhook methods).
◦ SlackReporter.ts – the key integration module used as a Playwright reporter.
- A dedicated “tests” folder verifies functionality across core modules and CLI pre-checks.

##### Core Components
a. Input & Data Sources:
- Playwright test runner generates JSON reports.
- CLI mode receives a merged JSON report (possibly generated via Playwright’s merge-reports command).
b. Processing & Parsing:
- ResultsParser: Processes and validates the JSON test results.
- (Optionally) CustomLayout Generator modules in “custom_block” and LayoutGenerator.ts: These format the parsed results into Slack Block Kit message objects.
c. Slack Reporting:
- SlackReporter: Acts as the orchestration layer that receives parsed results and decides what to send based on configuration (e.g., sendResults option “always” or “on-failure”).
- SlackClient and SlackWebhookClient: These components handle sending messages; one uses the Slack Web API (bot OAuth token) and the other uses webhook URLs.
d. Configuration & CLI Interface:
- cli.ts and cli_config.json: Provide a standalone command-line interface to send reports based on a user-defined configuration.
e. Optional Customization:
- Custom message layout functions (with both synchronous and asynchronous variants) allow clients to specify exactly how the Slack messages appear.

##### Relationships & Interactions
- Playwright generates test reports (JSON) → (CLI mode) → JSON report gets handed off to the ResultsParser.
- ResultsParser feeds data into the SlackReporter.
- SlackReporter then calls into either the SlackClient (for bot user integration) or SlackWebhookClient (when using a webhook).
- Optionally, before sending, the SlackReporter may use a custom layout function (imported from either “src/LayoutGenerator.ts” or one of the “custom_block” modules) to tailor the report format.
- Outgoing communication moves from SlackReporter to Slack through directional calls handled by the appropriate client.
- All configurations (e.g., channels, meta, options like “disableUnfurl” and “showInThread”) are passed through and influence behavior in SlackReporter and clients.

##### Important Architectural Patterns
- Separation of concerns: The parsing, layout generation, Slack communication, and CLI interfacing are all cleanly separated.
- Pluggability: Custom layout functions provide extension points so that message formatting is modular.
- Dual integration paths: One integration as a reporter within Playwright is separated from the CLI mode for merged JSON reports.
- Use of configuration files (both via package configuration and CLI-specific configuration) to drive runtime behavior.

##### Key Technologies & Frameworks
- Node.js and TypeScript as the programming environment.
- Playwright (for generating test results).
- Slack Web API and Slack Incoming Webhooks for publishing messages.
- GitHub Actions workflows and associated configuration for CI/CD.
- Testing frameworks (likely Jest or similar) are used in the “tests” folder.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Sources
    subgraph "Input Sources"
        A["Playwright Test Runner Integration"]:::input
        B["CLI Interface"]:::input
    end

    %% Processing Components
    subgraph "Processing"
        C["ResultsParser"]:::processing
        D["Custom Layout Module"]:::processing
    end

    %% Slack Reporting Components
    subgraph "Slack Reporting"
        E["SlackReporter"]:::reporting
        F["SlackClient"]:::reporting
        G["SlackWebhookClient"]:::reporting
    end

    %% Data Flow Connections
    A -->|"generatesJSONreports"| C
    B -->|"sendsMergedJSONreport"| C
    C -->|"parsesResults"| E
    D -->|"formatsSlackMessages"| E
    E -->|"sendsViaAPI"| F
    E -->|"sendsViaWebhook"| G

    %% Click Events
    click A "https://github.com/ryanrosello-og/playwright-slack-report/blob/main/playwright.config.ts"
    click C "https://github.com/ryanrosello-og/playwright-slack-report/blob/main/src/ResultsParser.ts"
    click D "https://github.com/ryanrosello-og/playwright-slack-report/blob/main/src/LayoutGenerator.ts"
    click D "https://github.com/ryanrosello-og/playwright-slack-report/tree/main/custom_block/"
    click E "https://github.com/ryanrosello-og/playwright-slack-report/blob/main/src/SlackReporter.ts"
    click F "https://github.com/ryanrosello-og/playwright-slack-report/blob/main/src/SlackClient.ts"
    click G "https://github.com/ryanrosello-og/playwright-slack-report/blob/main/src/SlackWebhookClient.ts"
    click B "https://github.com/ryanrosello-og/playwright-slack-report/blob/main/cli.ts"
    click B "https://github.com/ryanrosello-og/playwright-slack-report/blob/main/cli_config.json"
    click B "https://github.com/ryanrosello-og/playwright-slack-report/tree/main/src/cli/"

    %% Styles
    classDef input fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef processing fill:#ccffcc,stroke:#008000,stroke-width:2px;
    classDef reporting fill:#ccccff,stroke:#0000cc,stroke-width:2px;
```
