How ryanrosello-og/playwright-slack-report works
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.