test(playground): add unit tests for PlaygroundSDK and RemoteExecutionAdapter

Author: quanru

apps/report/src/components/playground.tsx

@@ -378,7 +378,7 @@ export function StandardPlayground({
 
     try {
       console.log('destroy agent.page', activeAgent?.page);
-      await activeAgent?.page?.destroy();
+      await activeAgent?.page?.destroy?.();
       console.log('destroy agent.page done', activeAgent?.page);
     } catch (e) {
       console.error(e);

package.json

@@ -6,7 +6,7 @@
     "dev": "nx run-many --target=build:watch --exclude=android-playground,chrome-extension,@midscene/report,doc --verbose --parallel=6",
     "build": "nx run-many --target=build --exclude=doc --verbose",
     "build:skip-cache": "nx run-many --target=build --exclude=doc --verbose --skip-nx-cache",
-    "test": "nx run-many --target=test --projects=@midscene/core,@midscene/shared,@midscene/visualizer,@midscene/web,@midscene/cli,@midscene/android  --verbose",
+    "test": "nx run-many --target=test --projects=@midscene/core,@midscene/shared,@midscene/visualizer,@midscene/web,@midscene/cli,@midscene/android,@midscene/playground  --verbose",
     "test:ai": "nx run-many --target=test:ai --projects=@midscene/core,@midscene/web,@midscene/cli --verbose",
     "e2e": "nx run @midscene/web:e2e --verbose --exclude-task-dependencies",
     "e2e:cache": "nx run @midscene/web:e2e:cache --verbose  --exclude-task-dependencies",

packages/playground/tests/README.md

@@ -0,0 +1,157 @@
+# @midscene/playground Tests
+
+This directory contains the test suite for the `@midscene/playground` package.
+
+## Test Structure
+
+```
+tests/
+├── unit/                    # Unit tests for individual components
+│   ├── common.test.ts          # Tests for common utilities
+│   ├── playground-sdk.test.ts  # Tests for PlaygroundSDK
+│   ├── base-adapter.test.ts    # Tests for BasePlaygroundAdapter
+│   ├── local-execution-adapter.test.ts   # Tests for LocalExecutionAdapter
+│   ├── remote-execution-adapter.test.ts  # Tests for RemoteExecutionAdapter
+│   └── types.test.ts           # Type definition tests
+├── integration/             # Integration tests
+│   └── playground-integration.test.ts    # End-to-end workflow tests
+├── setup.ts                # Test setup and global mocks
+└── README.md               # This file
+```
+
+## Running Tests
+
+### All Tests
+```bash
+pnpm test
+```
+
+### Watch Mode
+```bash
+pnpm test:watch
+```
+
+### Coverage Report
+```bash
+pnpm test -- --coverage
+```
+
+### Specific Test Files
+```bash
+# Run only unit tests
+pnpm test tests/unit
+
+# Run only integration tests
+pnpm test tests/integration
+
+# Run specific test file
+pnpm test tests/unit/common.test.ts
+```
+
+## Test Categories
+
+### Unit Tests
+
+**common.test.ts**
+- Tests core utility functions like `formatErrorMessage`, `validateStructuredParams`, and `executeAction`
+- Validates API constants and their relationships
+- Tests error handling and parameter validation
+
+**playground-sdk.test.ts**
+- Tests the main PlaygroundSDK class
+- Validates adapter selection logic
+- Tests delegation to appropriate adapters
+- Mocks underlying adapters for isolation
+
+**base-adapter.test.ts**
+- Tests the abstract BasePlaygroundAdapter class
+- Validates common validation logic
+- Tests parameter filtering and display content creation
+- Tests helper methods and error handling
+
+**local-execution-adapter.test.ts**
+- Tests LocalExecutionAdapter specific functionality
+- Validates local agent interaction
+- Tests progress tracking and task cancellation
+- Tests parameter parsing for local execution
+
+**remote-execution-adapter.test.ts**
+- Tests RemoteExecutionAdapter specific functionality
+- Validates server communication methods
+- Tests Android-specific error formatting
+- Mocks fetch calls for server interactions
+
+**types.test.ts**
+- Validates TypeScript type definitions
+- Ensures interfaces accept valid objects
+- Tests type compatibility and extensibility
+
+### Integration Tests
+
+**playground-integration.test.ts**
+- End-to-end workflow testing
+- Tests complete scenarios from SDK creation to action execution
+- Validates cross-adapter compatibility
+- Tests real-world usage patterns
+
+## Test Setup
+
+The `setup.ts` file provides:
+- Global mock configuration
+- Console method mocking to reduce test noise
+- Browser global mocking for server-side tests
+- Automatic cleanup between tests
+
+## Mocking Strategy
+
+- **External Dependencies**: Mocked using Vitest's `vi.mock()`
+- **Network Calls**: Mocked using global `fetch` mock
+- **Console Output**: Suppressed during tests to reduce noise
+- **Browser APIs**: Mocked for Node.js environment compatibility
+
+## Coverage
+
+The test suite aims for high coverage of:
+- All exported functions and classes
+- Error handling paths
+- Edge cases and boundary conditions
+- Type safety and interface compliance
+
+Coverage reports are generated in `coverage/` directory when running with `--coverage` flag.
+
+## Writing New Tests
+
+When adding new functionality:
+
+1. **Unit Tests**: Add tests in the appropriate `tests/unit/*.test.ts` file
+2. **Integration Tests**: Add end-to-end scenarios to `playground-integration.test.ts`
+3. **Type Tests**: Add type validation to `types.test.ts` for new interfaces
+4. **Mocking**: Use existing mock patterns and add new mocks as needed
+
+### Test Naming Convention
+
+- Describe blocks: Use present tense describing the component
+- Test cases: Use "should" statements describing expected behavior
+- Mock functions: Prefix with "mock" for clarity
+
+### Example Test Structure
+
+```typescript
+describe('ComponentName', () => {
+  let component: ComponentType;
+
+  beforeEach(() => {
+    component = new ComponentType();
+  });
+
+  describe('methodName', () => {
+    it('should handle normal case', () => {
+      // Test implementation
+    });
+
+    it('should handle error case', () => {
+      // Error test implementation
+    });
+  });
+});
+```

packages/playground/tests/setup.ts

@@ -0,0 +1,79 @@
+import { afterEach, beforeEach, vi } from 'vitest';
+
+// Mock console methods to avoid noise in tests
+vi.spyOn(console, 'warn').mockImplementation(() => {});
+vi.spyOn(console, 'error').mockImplementation(() => {});
+
+// Mock problematic dependencies early
+vi.mock('@midscene/shared', () => ({
+  generateId: vi.fn(() => 'mock-id'),
+  sleep: vi.fn(() => Promise.resolve()),
+}));
+
+vi.mock('@midscene/shared/img/get-photon', () => ({
+  default: vi.fn(),
+}));
+
+vi.mock('@midscene/shared/env', () => ({
+  overrideAIConfig: vi.fn(),
+  resetAIConfig: vi.fn(),
+}));
+
+vi.mock('@midscene/core/ai-model', () => ({
+  findAllMidsceneLocatorField: vi.fn(() => ['locateField']),
+}));
+
+vi.mock('@midscene/core', () => ({
+  Puppeteer: vi.fn(),
+  Playwright: vi.fn(),
+  createPage: vi.fn(),
+}));
+
+vi.mock('express', () => {
+  const mockExpress = () => ({
+    use: vi.fn(),
+    get: vi.fn(),
+    post: vi.fn(),
+    listen: vi.fn(),
+  });
+  mockExpress.static = vi.fn();
+  return { default: mockExpress };
+});
+
+vi.mock('cors', () => ({
+  default: vi.fn(() => (req: any, res: any, next: any) => next()),
+}));
+
+vi.mock('fs', () => ({
+  existsSync: vi.fn(() => true),
+  readFileSync: vi.fn(() => '{}'),
+  writeFileSync: vi.fn(),
+  mkdirSync: vi.fn(),
+}));
+
+// Global test setup
+beforeEach(() => {
+  // Reset all mocks before each test
+  vi.clearAllMocks();
+});
+
+// Clean up after tests
+afterEach(() => {
+  // Restore console methods
+  vi.clearAllMocks();
+});
+
+// Mock browser globals for tests that need them
+Object.defineProperty(global, 'window', {
+  value: {
+    location: {
+      href: 'http://localhost:3000',
+    },
+  },
+  writable: true,
+});
+
+Object.defineProperty(global, 'fetch', {
+  value: vi.fn(),
+  writable: true,
+});