How sclavijosuero/pw-api-plugin works
Project Type and Purpose
• This is an open‐source plugin aimed at enhancing Playwright API testing.
• Its purpose is to wrap standard API request methods and provide additional debugging/logging features by displaying API request/response details in the Playwright UI, Trace Viewer, and HTML Report.
• It supports two API calling mechanisms: Playwright native and Axios, each with a set of methods (GET, POST, PUT, etc.).
Analyzing the File Structure
• Top-level directories/files:
– The “src” folder contains the main source code modules: axiosApi.ts, pwApi.ts, displayUi.ts, testApi.ts, and the index file (exports/initializes the plugin).
– The “tests” folder contains example specifications that show how to use both pwApi and axiosApi.
– The “.github” directory houses the CI configuration (workflows) which likely is used to run Playwright tests including the UI and trace features.
– Configuration files like package.json and tsconfig.json support dependency management and TypeScript compilation.
• This organization suggests a clean separation of core API functionality (in src) and demonstration/testing (in tests).
Key Components
a. Core Plugin Module (Library Entry Point):
– Represent the “index.ts” module that aggregates and exports the plugin functionalities.
– Internal modules such as:
• pwApi class (in pwApi.ts): wraps Playwright native API calls.
• axiosApi class (in axiosApi.ts): wraps Axios-based API requests.
• displayUi module (in displayUi.ts): handles integration with Playwright UI (and by extension, the Trace Viewer and HTML report attachments).
• testApi module (in testApi.ts): possibly handles additional test-related utilities.
• types file (types.d.ts): defines the types and interfaces for the plugin.
b. Playwright Integration Layer:
– An extended “test” function imported from the plugin that can override the standard Playwright test function.
– This layer intercepts test execution to conditionally include page fixtures and to manage how captured API calls are routed to the UI or report attachments.
c. Environment Config Manager:
– Components that read environment variables such as LOG_API_UI and LOG_API_REPORT.
– These variables determine whether API call details are shown in the UI and/or attached to the HTML report.
d. External Dependencies & Integrations:
– Playwright Test Framework: Integrates with Playwright’s APIRequestContext, Page, and configuration.
– Axios Library: Used when the user prefers Axios-based API calls.
– UI Components: The display and logging features (tabs for Body, Headers, Params, and more) are rendered in the Playwright UI, HTML report, and Trace Viewer.
e. CI/CD and Documentation:
– The “.github/workflows” directory with a Playwright test workflow file.
– Documentation and usage examples provided in the README (including videos and screenshots).
Relationships and Interactions
• The core plugin module (index.ts) initializes and exports both the pwApi and axiosApi classes.
• When tests execute, they import the “test” function from the plugin rather than from the vanilla Playwright library. This function wraps or extends test behavior, especially with respect to handling the “page” fixture.
• API calls are made by invoking methods on either the pwApi or axiosApi classes. These methods internally:
– Call the actual API function (either Playwright’s native APIRequestContext or Axios).
– Capture the request and response data.
– Pass the data to the displayUi module, which formats the data into tabs (or cards) for the UI and/or attaches them to the HTML Report.
• The Environment Config Manager toggles the UI/logging behavior based on environment variable settings.
• CI/CD pipelines (GitHub workflows) run the Playwright tests and capture traces/reports utilizing this enhanced logging.
Architectural Patterns and Design Principles
• Modularity: The source is separated into clearly defined modules (API classes, UI, types, etc.).
• Separation of Concerns: The API execution and UI/logging are handled in separate modules.
• Extensibility: The plugin is designed to support multiple API calling mechanisms and could be extended with additional request configuration options.
• Dependency Inversion: Relying on external libraries (Playwright and Axios) through defined interfaces/types.