feat: add Playwright testing support and enhance project structure

JakubAndrysek · JakubAndrysek · commit 70151dba40da · 2025-11-11T15:15:02.000+01:00
- Introduced Playwright for end-to-end testing, including new test scripts and configurations.
- Updated .gitignore to exclude Playwright reports and test results.
- Enhanced ESLint configuration to ignore Playwright-related files.
- Added new scripts in package.json for running Playwright tests.
- Created a new Playwright configuration file and integrated it into the TypeScript setup.
- Updated GitHub workflows to include Playwright browser installation and testing steps.
- Refactored wokwi-cli to improve modularity and maintainability with new transport mechanisms.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -2,9 +2,9 @@ name: Tests
 
 on:
   push:
-    branches: [main]
   pull_request:
     branches: [main]
+  workflow_dispatch:
 
 jobs:
   test:
@@ -20,5 +20,11 @@ jobs:
           cache: 'pnpm'
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
+      - name: Build packages
+        run: pnpm run build
+      - name: Install Playwright browsers
+        run: pnpm exec playwright install --with-deps
       - name: Run tests
         run: pnpm test
+      - name: Test wokwi-embed with Playwright
+        run: pnpm test:embed:playwright
diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,5 @@ wokwi.toml
 *.bin
 diagram.json
 screenshot.png
+playwright-report/
+test-results/
diff --git a/eslint.config.ts b/eslint.config.ts
@@ -18,6 +18,8 @@ export default defineConfig(
       '**/.git/**',
       '**/coverage/**',
       '**/*.min.js',
+      '**/playwright-report/**',
+      '**/test-results/**',
     ],
   },
 
diff --git a/package.json b/package.json
@@ -10,6 +10,8 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "test": "pnpm run lint && vitest --run",
+    "test:embed:playwright": "playwright test test/wokwi-embed",
+    "test:embed:playwright:ui": "playwright test test/wokwi-embed --ui",
     "cli": "tsx packages/wokwi-cli/src/main.ts",
     "prepare": "husky install"
   },
@@ -21,6 +23,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",
+    "@playwright/test": "^1.48.0",
     "esbuild": "^0.25.2",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
diff --git a/packages/wokwi-cli/src/main.ts b/packages/wokwi-cli/src/main.ts
@@ -3,7 +3,8 @@ import chalkTemplate from 'chalk-template';
 import { createWriteStream, existsSync, readFileSync, writeFileSync } from 'fs';
 import path, { join } from 'path';
 import YAML from 'yaml';
-import { APIClient, WebSocketTransport, type APIEvent, type ChipsLogPayload, type SerialMonitorDataPayload } from 'wokwi-client-js';
+import { APIClient, type APIEvent, type ChipsLogPayload, type SerialMonitorDataPayload } from 'wokwi-client-js';
+import { WebSocketTransport } from './transport/WebSocketTransport.js';
 import { DEFAULT_SERVER } from './constants.js';
 import { ExpectEngine } from './ExpectEngine.js';
 import { SimulationTimeoutError } from './SimulationTimeoutError.js';
@@ -361,7 +362,7 @@ async function main() {
 	});
 
 	if (interactive) {
-	  process.stdin.pipe(client.serialMonitorWritable());
+	  process.stdin.pipe(await client.serialMonitorWritable());
 	}
 
 	if (scenario != null) {
diff --git a/packages/wokwi-cli/src/mcp/SimulationManager.ts b/packages/wokwi-cli/src/mcp/SimulationManager.ts
@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'fs';
 import path from 'path';
-import { APIClient, WebSocketTransport, type APIEvent } from 'wokwi-client-js';
+import { APIClient, type APIEvent } from 'wokwi-client-js';
+import { WebSocketTransport } from '../transport/WebSocketTransport.js';
 import { DEFAULT_SERVER } from '../constants.js';
 import { parseConfig } from '../config.js';
 import { loadChips } from '../loadChips.js';
diff --git a/packages/wokwi-cli/src/transport/WebSocketTransport.ts b/packages/wokwi-cli/src/transport/WebSocketTransport.ts
@@ -1,5 +1,5 @@
+import { type ITransport } from 'wokwi-client-js';
 import { WebSocket } from 'ws';
-import { ITransport } from './ITransport.js';
 
 const retryDelays = [1000, 2000, 5000, 10000, 20000];
 
diff --git a/packages/wokwi-client-js/package.json b/packages/wokwi-client-js/package.json
@@ -9,6 +9,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./transport/MessagePortTransport.js": {
+      "types": "./dist/transport/MessagePortTransport.d.ts",
+      "import": "./dist/transport/MessagePortTransport.js"
+    },
+    "./APIClient.js": {
+      "types": "./dist/APIClient.d.ts",
+      "import": "./dist/APIClient.js"
     }
   },
   "files": [
diff --git a/packages/wokwi-client-js/src/APIClient.ts b/packages/wokwi-client-js/src/APIClient.ts
@@ -1,4 +1,3 @@
-import { Writable } from 'stream';
 import type {
   APICommand,
   APIError,
@@ -107,9 +106,12 @@ export class APIClient {
     });
   }
 
-  serialMonitorWritable() {
+  async serialMonitorWritable() {
+    // Dynamic import for Node.js-only API
+    const { Writable } = await import('stream');
+    const { Buffer } = await import('buffer');
     return new Writable({
-      write: (chunk, encoding, callback) => {
+      write: (chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void) => {
         if (typeof chunk === 'string') {
           chunk = Buffer.from(chunk, encoding);
         }
diff --git a/packages/wokwi-client-js/src/index.ts b/packages/wokwi-client-js/src/index.ts
@@ -4,7 +4,6 @@ export { APIClient } from './APIClient.js';
 // Transport interfaces and implementations
 export { ITransport } from './transport/ITransport.js';
 export { MessagePortTransport } from './transport/MessagePortTransport.js';
-export { WebSocketTransport } from './transport/WebSocketTransport.js';
 
 // Pause Point
 export { PausePoint } from './PausePoint.js';
diff --git a/playwright.config.ts b/playwright.config.ts
@@ -0,0 +1,33 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './test',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: 'html',
+  use: {
+    trace: 'on-first-retry',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+  ],
+  webServer: {
+    command: 'npx --yes http-server . -p 8000 -c-1',
+    url: 'http://127.0.0.1:8000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120 * 1000,
+  },
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/test/wokwi-embed/index.html b/test/wokwi-embed/index.html
@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>MicroPython + ESP32 on Wokwi</title>
+    <script type="importmap">
+      {
+        "imports": {
+          "wokwi-client-js": "/packages/wokwi-client-js/dist/index.js"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <h1>MicroPython + ESP32 on Wokwi</h1>
+    <div>
+      <button class="start-button">Start</button>
+    </div>
+    <iframe
+      src="https://wokwi.com/experimental/embed?client_id=wokwi_client_omf4ejkz6n6twj7d3x2eqmyp"
+      width="50%"
+      height="500"
+      id="wokwi-embed"
+    ></iframe>
+    <h2>Serial Monitor Output</h2>
+    <div id="output"><pre id="output-text"></pre></div>
+    <script type="module" src="script.js"></script>
+  </body>
+</html>
diff --git a/test/wokwi-embed/script.js b/test/wokwi-embed/script.js
@@ -0,0 +1,66 @@
+import { MessagePortTransport, APIClient } from 'wokwi-client-js';
+
+const diagram = `{
+  "version": 1,
+  "author": "Uri Shaked",
+  "editor": "wokwi",
+  "parts": [
+    {
+      "type": "board-esp32-devkit-c-v4",
+      "id": "esp",
+      "top": 0,
+      "left": 0,
+      "attrs": { "env": "micropython-20231227-v1.22.0" }
+    }
+  ],
+  "connections": [ [ "esp:TX", "$serialMonitor:RX", "", [] ], [ "esp:RX", "$serialMonitor:TX", "", [] ] ],
+  "dependencies": {}
+}`;
+
+const microPythonCode = `
+import time
+while True:
+    print(f"Hello, World {time.time()}")
+    time.sleep(1)
+`;
+
+const outputText = document.getElementById('output-text');
+
+window.addEventListener('message', async (event) => {
+  if (!event.data.port) {
+    return;
+  }
+
+  const client = new APIClient(new MessagePortTransport(event.data.port));
+
+  // Wait for connection
+  await client.connected;
+  console.log('Wokwi client connected');
+
+  // Set up event listeners
+  client.listen('serial-monitor:data', (event) => {
+    const rawBytes = new Uint8Array(event.payload.bytes);
+    outputText.textContent += new TextDecoder().decode(rawBytes);
+  });
+
+  // Initialize simulation
+  try {
+    await client.serialMonitorListen();
+    await client.fileUpload('main.py', microPythonCode);
+    await client.fileUpload('diagram.json', diagram);
+  } catch (error) {
+    console.error('Error initializing simulation:', error);
+  }
+
+  document.querySelector('.start-button').addEventListener('click', async () => {
+    try {
+      await client.simStart({
+        firmware: 'main.py',
+        elf: 'main.py',
+      });
+    } catch (error) {
+      console.error('Error starting simulation:', error);
+    }
+  });
+});
+console.log('Wokwi ESP32 MicroPython script loaded');
diff --git a/test/wokwi-embed/wokwi-embed.spec.ts b/test/wokwi-embed/wokwi-embed.spec.ts
@@ -0,0 +1,21 @@
+import { test, expect, type Page } from '@playwright/test';
+
+test.describe('Wokwi Embed', () => {
+  test('should start simulation and wait for output', async ({ page }: { page: Page }) => {
+    await page.goto('http://127.0.0.1:8000/test/wokwi-embed/');
+
+    // Wait 3 seconds after page load
+    await page.waitForTimeout(3000);
+
+    // Click the start button
+    const startButton = page.locator('.start-button');
+    await startButton.click();
+
+    // Wait until output-text contains the expected messages
+    const outputText = page.locator('#output-text');
+    await expect(outputText).toContainText('Hello, World 2', { timeout: 60000 });
+    await expect(outputText).toContainText('Hello, World 3', { timeout: 60000 });
+    await expect(outputText).toContainText('Hello, World 4', { timeout: 60000 });
+  });
+});
+
diff --git a/tsconfig.json b/tsconfig.json
@@ -2,6 +2,8 @@
     "extends": "./tsconfig.base.json",
     "include": [
         "eslint.config.ts",
+        "playwright.config.ts",
+        "vitest.config.ts",
         "./test/**/*.test.ts",
         "./test/**/*.ts",
         "./packages/*/src/**/*.ts"
diff --git a/vitest.config.ts b/vitest.config.ts
