testdriverai 7.2.9 → 7.2.10

package/docs/v7/presets/electron.mdx

@@ -1,460 +0,0 @@
----
-title: "Desktop Apps"
-sidebarTitle: "Desktop Apps"
-description: "Automatically launch and test Electron applications"
-icon: "atom"
----
-
-## Overview
-
-The `electron()` preset automatically sets up an Electron application with TestDriver and Dashcam recording. Perfect for testing desktop apps built with Electron.
-
-<Note>
-  **Recommended Pattern (v7.1+):** Use `TestDriver()` hook + `provision.electron()` for more flexibility:
-  
-  ```javascript
-  import { TestDriver } from 'testdriverai/vitest/hooks';
-  
-  test('my test', async (context) => {
-    const testdriver = TestDriver(context, { headless: true });
-    await testdriver.provision.electron({ 
-      appPath: './dist/my-app'
-    });
-    // ...
-  });
-  ```
-  
-  The `electron()` preset is still supported but the direct API provides better control and clearer lifecycle management.
-</Note>
-
-## Quick Start
-
-```javascript
-import { test } from 'vitest';
-import { TestDriver } from 'testdriverai/vitest/hooks';
-
-test('electron app test', async (context) => {
-  const testdriver = TestDriver(context, { headless: true });
-  
-  await testdriver.provision.electron({ appPath: './dist/my-app' });
-  
-  await testdriver.find('main window').click();
-  await testdriver.find('File menu').click();
-  await testdriver.find('New Document').click();
-});
-```
-
-## Signature
-
-```typescript
-electron(context, options): Promise<ElectronResult>
-```
-
-### Parameters
-
-<ParamField path="context" type="object" required>
-  Vitest test context - automatically passed to your test function
-</ParamField>
-
-<ParamField path="options" type="object">
-  Configuration options for Electron
-
-  <Expandable title="properties">
-    <ParamField path="appPath" type="string" required>
-      Path to your Electron application executable or main file
-    </ParamField>
-
-    <ParamField path="args" type="string[]" default={[]}>
-      Additional command-line arguments to pass to Electron
-    </ParamField>
-
-    <ParamField path="dashcam" type="boolean" default={true}>
-      Enable Dashcam test recording
-    </ParamField>
-
-    <ParamField path="os" type="'linux' | 'mac' | 'windows'" default="linux">
-      Target operating system for the test
-    </ParamField>
-  </Expandable>
-</ParamField>
-
-### Returns
-
-<ResponseField name="testdriver" type="TestDriver" required>
-  TestDriver instance ready to use
-</ResponseField>
-
-<ResponseField name="app" type="TestDriver" required>
-  Alias for testdriver (semantic clarity for Electron apps)
-</ResponseField>
-
-<ResponseField name="dashcam" type="Dashcam">
-  Dashcam instance for test recording (if enabled)
-</ResponseField>
-
-## Examples
-
-### Basic Electron App
-
-```javascript
-import { test } from 'vitest';
-import { TestDriver } from 'testdriverai/vitest/hooks';
-
-test('opens main window', async (context) => {
-  const testdriver = TestDriver(context, { headless: true });
-  
-  await testdriver.provision.electron({ appPath: './dist/my-electron-app' });
-  
-  await testdriver.assert('Main window is visible');
-  await testdriver.find('Welcome message').click();
-});
-```
-
-### With Command-Line Arguments
-
-```javascript
-import { test } from 'vitest';
-import { TestDriver } from 'testdriverai/vitest/hooks';
-
-test('app with debug mode', async (context) => {
-  const testdriver = TestDriver(context, { headless: true });
-  
-  await testdriver.provision.electron({
-    appPath: './dist/app',
-    args: [
-      '--enable-logging',
-      '--debug',
-      '--user-data-dir=/tmp/test-data'
-    ]
-  });
-  
-  await testdriver.find('Debug panel').click();
-  await testdriver.assert('Debug information is visible');
-});
-```
-
-### Menu Navigation
-
-```javascript
-import { test } from 'vitest';
-import { TestDriver } from 'testdriverai/vitest/hooks';
-
-test('file menu operations', async (context) => {
-  const testdriver = TestDriver(context, { headless: true });
-  
-  await testdriver.provision.electron({ appPath: './dist/editor-app' });
-  
-  // Open File menu
-  await testdriver.find('File').click();
-  await testdriver.find('New File').click();
-  
-  // Verify new file created
-  await testdriver.assert('Untitled document is open');
-  
-  // Save file
-  await testdriver.find('File').click();
-  await testdriver.find('Save As').click();
-  await testdriver.type('test-document.txt');
-  await testdriver.pressKeys(['enter']);
-  
-  await testdriver.assert('File saved successfully');
-});
-```
-
-### Testing on Different Platforms
-
-```javascript
-import { test } from 'vitest';
-import { TestDriver } from 'testdriverai/vitest/hooks';
-
-test('windows electron app', async (context) => {
-  const testdriver = TestDriver(context, { headless: true, os: 'windows' });
-  
-  await testdriver.provision.electron({ 
-    appPath: 'C:\\Program Files\\MyApp\\MyApp.exe'
-  });
-  
-  await testdriver.find('Start button').click();
-});
-
-test('mac electron app', async (context) => {
-  const testdriver = TestDriver(context, { headless: true, os: 'mac' });
-  
-  await testdriver.provision.electron({
-    appPath: '/Applications/MyApp.app/Contents/MacOS/MyApp'
-  });
-  
-  await testdriver.find('Start button').click();
-});
-```
-
-### Preferences and Settings
-
-```javascript
-import { test } from 'vitest';
-import { TestDriver } from 'testdriverai/vitest/hooks';
-
-test('configure app settings', async (context) => {
-  const testdriver = TestDriver(context, { headless: true });
-  
-  await testdriver.provision.electron({ appPath: './dist/my-app' });
-  
-  // Open preferences
-  await testdriver.find('Settings').click();
-  
-  // Change theme
-  await testdriver.find('Appearance').click();
-  await testdriver.find('Dark mode toggle').click();
-  
-  // Verify change
-  await testdriver.assert('Dark mode is enabled');
-  
-  // Save settings
-  await testdriver.find('Save button').click();
-  
-  await testdriver.assert('Settings saved');
-});
-```
-
-### Window Management
-
-```javascript
-import { test } from 'vitest';
-import { TestDriver } from 'testdriverai/vitest/hooks';
-
-test('multiple windows', async (context) => {
-  const testdriver = TestDriver(context, { headless: true });
-  
-  await testdriver.provision.electron({ appPath: './dist/multi-window-app' });
-  
-  // Open new window
-  await testdriver.find('File').click();
-  await testdriver.find('New Window').click();
-  
-  // Switch between windows
-  await testdriver.find('second window').click();
-  await testdriver.assert('Second window is focused');
-  
-  // Close window
-  await testdriver.find('Close button').click();
-  
-  await testdriver.assert('Window closed');
-});
-```
-
-### Form Interaction
-
-```javascript
-import { test } from 'vitest';
-import { TestDriver } from 'testdriverai/vitest/hooks';
-
-test('form submission', async (context) => {
-  const testdriver = TestDriver(context, { headless: true });
-  
-  await testdriver.provision.electron({ appPath: './dist/form-app' });
-  
-  // Fill form
-  await testdriver.find('Name input').type('John Doe');
-  await testdriver.find('Email input').type('john@example.com');
-  await testdriver.find('Phone input').type('555-1234');
-  
-  // Select dropdown
-  await testdriver.find('Country dropdown').click();
-  await testdriver.find('United States').click();
-  
-  // Check checkbox
-  await testdriver.find('Terms and conditions').click();
-  
-  // Submit
-  await testdriver.find('Submit button').click();
-  
-  await testdriver.assert('Form submitted successfully');
-  
-  // Dashcam captures entire interaction
-});
-```
-
-## What It Does
-
-When you call `electron()`, it automatically:
-
-1. **Initializes TestDriver** - Creates and connects to sandbox
-2. **Sets up Dashcam** - Authenticates and starts recording (if enabled)
-3. **Launches Electron** - Starts your app with specified arguments
-4. **Waits for Ready** - Ensures app is focused and windows are loaded
-5. **Returns Instances** - Provides ready-to-use testdriver, app alias, and dashcam
-
-At test end:
-- Dashcam automatically stops and saves replay URL
-- TestDriver automatically disconnects
-- All cleanup is handled for you
-
-## Common Patterns
-
-### IPC Communication Testing
-
-```javascript
-test('ipc events', async (context) => {
-  const testdriver = TestDriver(context, { headless: true });
-  
-  await testdriver.provision.electron({ appPath: './dist/ipc-app' });
-  
-  // Trigger IPC event from renderer
-  await testdriver.find('Send Message button').click();
-  
-  // Verify main process response
-  await testdriver.assert('Response received from main process');
-});
-```
-
-### Notification Testing
-
-```javascript
-test('system notifications', async (context) => {
-  const testdriver = TestDriver(context, { headless: true });
-  
-  await testdriver.provision.electron({ appPath: './dist/notification-app' });
-  
-  await testdriver.find('Show Notification').click();
-  await testdriver.assert('System notification appears');
-});
-```
-
-### Tray Icon Interaction
-
-```javascript
-test('system tray', async (context) => {
-  const testdriver = TestDriver(context, { headless: true });
-  
-  await testdriver.provision.electron({ appPath: './dist/tray-app' });
-  
-  // Click tray icon
-  await testdriver.find('app tray icon').click();
-  
-  // Interact with tray menu
-  await testdriver.find('Show Window').click();
-  
-  await testdriver.assert('Main window appears');
-});
-```
-
-### Auto-Update Flow
-
-```javascript
-test('app update', async (context) => {
-  const testdriver = TestDriver(context, { headless: true });
-  
-  await testdriver.provision.electron({
-    appPath: './dist/updatable-app',
-    args: ['--check-updates']
-  });
-  
-  await testdriver.find('Check for Updates').click();
-  await testdriver.assert('Checking for updates message');
-  
-  // Assuming update is available
-  await testdriver.find('Download Update').click();
-  await testdriver.assert('Update downloaded');
-});
-```
-
-## Development Paths
-
-### Common Development Paths
-
-```javascript
-// Electron Forge
-appPath: './out/my-app-linux-x64/my-app'
-
-// Electron Builder
-appPath: './dist/linux-unpacked/my-app'
-
-// Direct execution
-appPath: './node_modules/.bin/electron'
-args: ['./main.js']
-
-// Packaged app (Windows)
-appPath: 'C:\\Program Files\\MyApp\\MyApp.exe'
-
-// Packaged app (macOS)
-appPath: '/Applications/MyApp.app/Contents/MacOS/MyApp'
-
-// Packaged app (Linux)
-appPath: '/opt/MyApp/my-app'
-```
-
-## Using with provision()
-
-The `electron()` preset can also be called via the unified `provision()` function:
-
-```javascript
-import { provision } from 'testdriverai/presets';
-
-test('using provision', async (context) => {
-  const { app } = await provision('electron', {
-    appPath: './dist/my-app'
-  }, context);
-  
-  // Same functionality as electron() directly
-});
-```
-
-## Error Handling
-
-```javascript
-test('handles missing app path', async (context) => {
-  try {
-    const testdriver = TestDriver(context, { headless: true });
-    await testdriver.provision.electron({ appPath: '/nonexistent/path' });
-  } catch (error) {
-    // Cleanup still happens automatically
-    expect(error.message).toContain('appPath');
-  }
-});
-
-test('handles app crashes', async (context) => {
-  const testdriver = TestDriver(context, { headless: true });
-  
-  await testdriver.provision.electron({ appPath: './dist/my-app' });
-  
-  try {
-    // Trigger something that might crash
-    await testdriver.find('Crash button').click();
-  } catch (error) {
-    // Dashcam still saves replay of crash
-    console.error('App crashed:', error);
-  }
-});
-```
-
-## Debugging Tips
-
-1. **Enable Electron DevTools** - Pass `--enable-logging` in args
-2. **Use Dashcam** - Review test recordings to see what happened
-3. **Custom User Data** - Use `--user-data-dir` for isolated testing
-4. **Remote Debugging** - Use `--remote-debugging-port=9222`
-
-```javascript
-test('with debugging enabled', async (context) => {
-  const testdriver = TestDriver(context, { headless: true });
-  
-  await testdriver.provision.electron({
-    appPath: './dist/my-app',
-    args: [
-      '--enable-logging',
-      '--remote-debugging-port=9222',
-      '--user-data-dir=/tmp/test-profile'
-    ]
-  });
-  
-  // Test with full debugging capabilities
-});
-```
-
-## See Also
-
-- [Provision API](/v7/progressive-apis/PROVISION) - Overview of all presets
-- [Chrome Preset](/v7/presets/chrome) - Testing web applications
-- [VS Code Preset](/v7/presets/vscode) - Testing VS Code extensions
-- [Vitest Integration](/v7/guides/vitest) - Complete Vitest setup guide
-- [Hooks API](/v7/progressive-apis/HOOKS) - Manual lifecycle control