How bhavinkumar-vegad/playwright-email-utils works
Project Type and Purpose
• This is an open-source utility/library package (an SDK) designed to let Playwright tests extract and interact with emails from:
• Gmail (via Gmail API + OAuth2)
• Disposable web-based services like Yopmail (via browser automation)
• It exposes a unified API (emailUtils) and a CLI helper (get-gmail-refresh-token) for initial Gmail setup.
File Structure Analysis
• src/
• bin/get-gmail-refresh-token.ts → CLI entrypoint
• index.ts → main library export (emailUtils)
• emailUtils.ts → builds the API surface, maps providers and methods
• providers/
– gmail.ts → Gmail provider implementation
– yopmail.ts → Yopmail provider implementation
• utils/
– emailBodyParser.ts → shared parsing logic for body extraction
– gmailApi.ts → wraps actual calls to Gmail REST API
– gmailAuthUtils.ts → OAuth flow (token exchange, refresh)
• types.ts → shared TypeScript interfaces and types
• dist/ → transpiled JavaScript + type declarations for npm publish
• examples/ → sample integration tests showing usage of Gmail + Yopmail
Core Components
a. Client / Test Code
• The user’s Playwright test or script that calls emailUtils.getEmail.* or the CLI to obtain a refresh token.
b. Library API Layer (emailUtils)
• Unified façade exposing .fromGmail(), .fromYopmail(), and advanced extraction methods.
c. Providers
• Gmail Provider
• Yopmail Provider
d. Utility Modules
• Parser (emailBodyParser)
• Gmail REST wrapper (gmailApi)
• OAuth helper (gmailAuthUtils)
e. CLI Tool
• get-gmail-refresh-token: runs OAuth dance, prompts user, writes .env entries.
f. External Systems
• Google OAuth2 & Gmail REST API (secure HTTPS calls)
• Yopmail web UI (HTTP + browser automation via Playwright)
Relationships and Data Flow
1. Setup (CLI)
• Developer runs npx get-gmail-token → CLI loads dotenv → uses gmailAuthUtils → opens browser for consent → receives code → exchanges for refresh token → writes to .env.
2. Runtime (Library)
• Test Code → calls emailUtils.fromGmail(config, searchOptions)
↳ emailUtils delegates to Gmail Provider
↳ Gmail Provider calls gmailAuthUtils to ensure valid access token
↳ Gmail Provider uses gmailApi to query messages → returns raw email payload
↳ emailBodyParser applies extraction strategies (between-markers, regex, full-text) → returns structured result to test code
• Test Code → calls emailUtils.fromYopmail(page, inbox, subject, actions)
↳ emailUtils delegates to Yopmail Provider
↳ Yopmail Provider drives Playwright page to navigate to Yopmail URL
↳ Performs UI actions (text lookup, click, attribute extraction) → returns result to test code
• Optional: Yopmail auto-delete flag triggers extra navigation/click to clear mailbox
Architectural Patterns and Design Principles
• Provider Abstraction/Strategy Pattern: each email-service implements the same interface for .getEmail and extraction rules
• Single Responsibility: utils are factored by concern (parsing, API calls, auth)
• CLI vs Library separation: clear boundary between one-off setup tool and reusable API
• Type Safety: interfaces and types defined in types.ts used across modules
• Build Pipeline: TypeScript source → tsc → dist/ → npm publish
Essential Elements to Capture
• API façade vs provider implementations
• Shared utility modules
• CLI vs library runtime
• External dependencies (Gmail API, web UI)