How suiramdev/docwright works
Project Type & Purpose
• Docwright is a library that automates the generation of UI documentation from Playwright-style test scripts. Its purpose is to let users author UI scenarios using a DSL of directives (such as describe, scenario, text, screenshot, highlight) and automatically convert these into documented UI flows. It is built to work on Bun and leverages Playwright for browser automation.
Analyzing the File Structure
• There are several high-level directories that suggest a monorepo structure:
• packages/core – Contains the core functionality including the CLI command definitions (commands/generate.ts), configuration resolvers (packages/core/src/config), directive implementations (the “directives” folder with beforeAll, afterEach, etc.), and internal utilities (registry, tracer, worker, models).
• packages/render-markdown – Handles the transformation of processed data into Markdown (and likely other outputs).
• playground – Provides example configuration files and sample UI documentation scripts.
• Additionally, configuration files like tsconfig.json, package.json, and Bun-related files (bun.lock, .bun-version) indicate TypeScript usage and that the project is built to run on Bun.
Key Architectural Components & Their Relationships
a. CLI Interface:
• Found in packages/core/src/cli.
• Exposes commands such as "generate" (e.g., via generate.ts) and initialization (docwright init) to the user.
• It acts as the entry point for users to run the docwright library.
b. Configuration Management:
• The configuration resolver (resolve.ts) and configuration schema (schema.ts) are responsible for reading and validating the user's docwright.config.ts file.
• This component determines which test scripts (such as those found in the playground or user-provided scripts) should be processed.
c. Core Engine:
• This is the heart of docwright. It parses and executes Playwright-style test scripts and their embedded documentation directives.
• Within the core engine, the following subcomponents are important:
• Directives: Implementations for describe, scenario, text, screenshot, highlight, etc., which enable users to annotate UI flows.
• Registry: Keeps track of directives and test cases.
• Tracer/Worker: Possibly used for tracking the execution of tests and managing the sequencing or concurrency of tests, gathering output details.
• Models: Definitions (such as Task, TaskCase, TaskSuite, Renderer) that structure the data generated from test runs.
• The core engine interprets the DSL (the special functions exported by the library) and organizes data for documentation.
d. Rendering Module:
• Located in packages/render-markdown.
• Converts the structured output (and potentially raw data from tests) into Markdown format—serving as the final output format for documentation.
• This module ensures that the user gets a readable UI documentation file with descriptions, screenshots, and highlighted elements.
Relationships and Data Flow
• The flow starts with a user invoking the CLI (via bunx docwright generate or similar).
• The CLI first uses the Configuration Management component to load the docwright.config.ts file.
• Then, the Core Engine is triggered to parse and execute the user's test scripts:
• The DSL directives (describe, scenario, etc.) capture data as they run.
• The Registry, Tracer, and Worker collaborate to manage and aggregate this data.
• Once the execution is complete and data is assembled into defined Models, the Rendering Module (Markdown Renderer) converts this information into UI documentation.
• If needed, additional scripts (or even integration with external APIs) could be visualized as outputs or further processing steps.
Architectural Patterns and Design Principles
• Modular design: The monorepo structure separates concerns (core logic, rendering, CLI, configuration, tests).
• Clear separation of responsibilities: CLI handles user interaction, configuration is abstracted, the core engine orchestrates execution using well-defined models and directives, and rendering is isolated.
• Extensibility: Users can easily add new scenarios or directives without changing the core processing engine.
Elements
• Clear labels for each component (e.g. “CLI”, “Configuration Manager”, “Core Engine”, “Directives”, “Registry”, “Tracer/Worker”, “Models”, “Render Markdown”).
• CLI → Config Manager
• Config Manager → Core Engine
• Core Engine (with internal flows among directives, registry, and tracer/worker) → Render Module
• Optionally, include external elements like “Playwright” or “Bun Runtime” to show the external ecosystem in which docwright operates.