Merge pull request #68 from wix-incubator/fix/expose-drivers-properly

feat: make puppeteer and playwright optional peer dependencies and drivers.

examples/puppeteer/package.json

@@ -15,4 +15,4 @@
     "typescript": "^5.3.3",
     "puppeteer": "^20.8.0"
   }
-} 
+}

examples/puppeteer/tests/example.test.ts

@@ -1,4 +1,5 @@
 import copilot from "@copilot";
+import puppeteer from "puppeteer";
 import { PromptHandler } from "../../utils/promptHandler";
 import { PuppeteerFrameworkDriver } from "@copilot/drivers/puppeteer";
 
@@ -11,6 +12,7 @@ describe("Example Test Suite", () => {
     const promptHandler: PromptHandler = new PromptHandler();
 
     frameworkDriver = new PuppeteerFrameworkDriver();
+    frameworkDriver = new PuppeteerFrameworkDriver(puppeteer.executablePath());
 
     copilot.init({
       frameworkDriver,

package.json

@@ -36,6 +36,10 @@
   "bugs": {
     "url": "https://github.com/wix-incubator/detox-copilot/issues"
   },
+  "peerDependencies": {
+    "playwright": ">=1.50.0",
+    "puppeteer-core": ">=20.8.0"
+  },
   "devDependencies": {
     "@playwright/test": "^1.50.0",
     "@types/jest": "^29.5.12",

src/drivers/puppeteer/getCleanDOM.ts

@@ -1,4 +1,4 @@
-import * as puppeteer from "puppeteer";
+import * as puppeteer from "puppeteer-core";
 
 /**
  * Get clean DOM from the page content

src/drivers/puppeteer/index.ts

@@ -1,15 +1,17 @@
 import { TestingFrameworkAPICatalog, TestingFrameworkDriver } from "@/types";
-import * as puppeteer from "puppeteer";
+import * as puppeteer from "puppeteer-core";
 import path from "path";
 import fs from "fs";
 import getCleanDOM from "./getCleanDOM";
 
 export class PuppeteerFrameworkDriver implements TestingFrameworkDriver {
   private currentPage?: puppeteer.Page;
+  private executablePath?: string;
 
-  constructor() {
+  constructor(executablePath?: string) {
     this.getCurrentPage = this.getCurrentPage.bind(this);
     this.setCurrentPage = this.setCurrentPage.bind(this);
+    this.executablePath = executablePath;
   }
 
   /**
@@ -84,8 +86,10 @@ export class PuppeteerFrameworkDriver implements TestingFrameworkDriver {
               signature: "const browser = await puppeteer.launch([options])",
               description: "Launches a new browser instance.",
               example:
-                'const browser = await puppeteer.launch({`headless: "new"`});',
+                `const browser = await puppeteer.launch({\`headless: "new"\`, executablePath: "${this.executablePath}" });\n` +
+                `const browser = await puppeteer.launch({\`headless: "false"\`, executablePath: "${this.executablePath}" });`,
               guidelines: [
+                `Executable path is required always, use the path: ${this.executablePath}`,
                 "Options can specify `headless`, `slowMo`, `args`, etc.",
                 "Useful for running tests in a headless browser environment.",
                 'Prefer passing `headless: "new"` to `puppeteer.launch() unless mentioned that ' +

src/utils/CodeEvaluator.ts

@@ -17,6 +17,12 @@ export class CodeEvaluator {
     try {
       const result = await asyncFunction();
 
+      logger.info({
+        message: `\nCopilot evaluated the code: \n\`\`\`\n${code}\n\`\`\``,
+        isBold: false,
+        color: "gray",
+      });
+
       return { code, result, sharedContext };
     } catch (error) {
       logger.error({

website/docs/guides/implementing-custom-testing-framework-driver.md

@@ -11,6 +11,21 @@ The **testing framework driver** is a core component of **Copilot by Detox**, en
 
 ---
 
+## Available Framework Drivers
+
+Copilot has several framework drivers available:
+
+### Built into this package:
+- **Puppeteer Driver**: A complete implementation for web testing using Puppeteer
+- **Playwright Driver**: A modern web testing implementation using Playwright
+
+### Available in other packages:
+- **Detox Driver**: Mobile app testing implementation (available in the [Detox repository](https://github.com/wix/Detox/tree/master/detox/src/copilot))
+
+You can use these implementations as references when creating your own custom driver.
+
+---
+
 ## Recommended Approach for Framework Support
 
 Where possible, framework support should ideally be provided directly from the framework's codebase. For example, Detox includes support within its own repository: [Detox Copilot Driver](https://github.com/wix/Detox/tree/master/detox/src/copilot).
@@ -40,7 +55,7 @@ All drivers must implement the `TestingFrameworkDriver` interface. Key methods i
   Returns the view hierarchy of the current screen as a string.
 
 - `apiCatalog: TestingFrameworkAPICatalog`\
-  Categorizes the framework’s actions, matchers, and utilities.
+  Categorizes the framework's actions, matchers, and utilities.
 
 For detailed documentation, see the [Framework Driver API](../API/framework-driver.md).
 
@@ -52,7 +67,7 @@ For detailed documentation, see the [Framework Driver API](../API/framework-driv
 
 ### 3. **Define the API Catalog**
 
-The `apiCatalog` organizes the framework’s capabilities into categories:
+The `apiCatalog` organizes the framework's capabilities into categories:
 
 - **Actions**: e.g., `tap`, `longPress`, `scroll`.
 - **Matchers**: e.g., `by.id`, `by.text`.

website/docs/pages/supported-frameworks.md

@@ -1,47 +1,67 @@
 # Supported Frameworks for Copilot
 
-**Copilot by Detox** is designed to empower developers by simplifying the way they write tests for their applications. Originally developed as a feature for Detox, Copilot has grown into a **framework-agnostic tool**, making it adaptable to a wide range of testing frameworks with minimal customization.
+**Copilot by Detox** enables natural language testing across different testing frameworks. Here's how to use it with our supported frameworks:
 
----
+## Built-in Web Testing Support
 
-## Detox Integration: Mobile Apps Testing
+### Playwright
 
-Detox, a powerful end-to-end testing framework for mobile apps, is the first framework to provide Copilot as part of its API. Copilot’s integration with Detox offers developers:
-
-- **Natural language testing**: Write tests in plain, intuitive language instead of manual test scripting.
-- **Enhanced usability with Detox APIs**: Leverage Detox’s robust matchers and actions, such as `by.id()`, `tap()`, and `longPress()`, for seamless app interaction.
-- **Improved debugging tools**: Use snapshots, including screenshots and view hierarchies, to better analyze the app’s state during testing.
+```js
+// 1. Install: npm install --save-dev playwright
+// 2. Import and use:
+import { PlaywrightFrameworkDriver } from 'detox-copilot/drivers/playwright';
 
-**To learn more, visit the ********[official documentation](https://wix.github.io/Detox/docs/copilot/testing-with-copilot)********.**
+it('should login', async () => {
+  await copilot.perform(
+    'Open "https://example.com" in the browser',
+    'Fill in the username field with "testuser"',
+    'Fill in the password field with "password123"',
+    'Click the login button',
+    'Verify that the dashboard is visible'
+  );
+});
+```
 
-### Example: Writing Tests with Copilot in Detox
+Supports Chrome, Firefox, and WebKit with powerful auto-waiting mechanisms.
 
-Here is an example test written in natural language that demonstrates step-by-step execution:
+### Puppeteer
 
 ```js
-it('should verify element sizes and button states', async () => {
+// 1. Install: npm install --save-dev puppeteer
+// 2. Import and use:
+import { PuppeteerFrameworkDriver } from 'detox-copilot/drivers/puppeteer';
+
+it('should submit a form', async () => {
   await copilot.perform(
-    'Launch the app with notification permissions enabled',
-    'Navigate to the "Settings" page',
-    'Verify that the "Save" button is disabled',
-    'Locate the profile picture element',
-    'Verify that the profile picture size is 100 x 100 pixels and that the image is available and rendered',
-    'Tap on the "Edit Profile" button',
-    'Verify that the "Save" button is now enabled',
-    'Verify that the "Username" field text is bold'
+    'Open "https://example.com/signup" in the browser',
+    'Fill in the email field with "[email protected]"',
+    'Check the terms checkbox',
+    'Click submit',
+    'Verify success message appears'
   );
 });
 ```
 
----
+Specialized for Chrome/Chromium automation with DevTools Protocol access.
 
-## Expanding Copilot’s Reach: Call for Contributions
+## External Framework Support
 
-**Copilot by Detox** is built with a flexible, framework-agnostic design, enabling integration with various testing frameworks. Currently, Detox is the only framework providing the API and necessary framework driver for Copilot. However, we believe the potential for Copilot extends far beyond Detox.
+### Detox
 
-We invite the community to contribute by:
+Available directly in the Detox package for mobile app testing. [See Detox documentation](https://wix.github.io/Detox/docs/copilot/testing-with-copilot).
+
+```js
+it('should update profile', async () => {
+  await copilot.perform(
+    'Launch the app',
+    'Navigate to Settings',
+    'Tap on "Edit Profile"',
+    'Update username to "john_doe"',
+    'Verify changes are saved'
+  );
+});
+```
 
-- **Integrating new frameworks**: Extend Copilot’s compatibility to other testing frameworks by [developing the necessary drivers and APIs](https://github.com/wix-incubator/detox-copilot/issues).
-- **Enhancing existing integrations**: Refine and optimize Copilot’s functionality within Detox or other supported frameworks.
+## Contributing
 
-Your contributions can help shape Copilot into a universal testing tool for developers worldwide. To get involved or learn more about potential integrations, visit our [GitHub repository](https://github.com/wix-incubator/detox-copilot/issues).
+Want to add support for another framework? Check our [GitHub Issues](https://github.com/wix-incubator/detox-copilot/issues) or submit a PR.